1# Tool Reference23Two perspectives on the same 19 tools. Use whichever table matches what you4already know.56## Artifact → tool mapping78If you already know OpenSpec's artifact model (proposal, design, tasks, specs,9ideas, archive), this table maps each artifact operation to the Hermes tool10that performs it.1112| You want to… | OpenSpec artifact | Hermes tool | Effect |13|---|---|---|---|14| Capture a raw idea | `openspec/ideas/<slug>.md` (new) | `openspec_idea_create` | Writes the idea file |15| Add a structured evaluation to an idea | `openspec/ideas/<slug>.md` (update) | `openspec_idea_enrich` | Appends problem, direction, feasibility, T-shirt size, risks, questions, next step |16| Turn an idea into a change | `openspec/changes/<change>/` (new) | `openspec_idea_promote` | Creates the change scaffold with proposal/tasks/spec traceability |17| Create a change without an idea | `openspec/changes/<change>/` (new) | `openspec_change_create` | Creates the change scaffold directly |18| Author the proposal | `openspec/changes/<change>/proposal.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |19| Author the design doc | `openspec/changes/<change>/design.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |20| Author specs | `openspec/changes/<change>/specs/<spec>/spec.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |21| Author tasks | `openspec/changes/<change>/tasks.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |22| Mark a change ready to implement | `tasks.md` + `specs/` placeholder | `openspec_change_promote` | Ensures checklist items and spec placeholder exist |23| Read a change or spec | Any artifact | `openspec_show` | Returns JSON: proposal, tasks, design, specs, deltas |24| Get the implementation guide | `openspec apply` instructions | `openspec_instructions` (artifact=`apply`) | Returns step-by-step apply instructions |25| Track task progress | `tasks.md` checkboxes | `openspec_task_set_status` | Toggles `- [ ]` ↔ `- [x]` |26| Check what artifacts exist | Change directory | `openspec_status` | Returns which artifacts are present/missing and readiness |27| Validate before archiving | All artifacts | `openspec_validate` | Returns validation errors |28| Archive a completed change | `openspec/changes/archive/` | `openspec_change_archive` | Moves the change dir to archive |29| Reopen an archived change | `openspec/changes/` (restore) | `openspec_change_unarchive` | Moves the change dir back to active |30| Compare a change spec against its baseline | Spec files (read-only) | `openspec_spec_diff` | Returns a structured semantic delta at the requirement/scenario level plus a unified line diff fallback. Filesystem-backed. |31| Create a spec from structured input | `openspec/specs/<spec>/spec.md` or `openspec/changes/<change>/specs/<spec>/spec.md` | `openspec_spec_create` | Writes formatted spec.md from title/purpose/requirements array. Overwrite with `force`. Filesystem-backed. |32| Read a spec as structured JSON | Spec files (read-only) | `openspec_spec_show` | Returns parsed title, purpose, requirements with scenarios and steps. Filesystem-backed. |33| List specs in a project | `openspec/specs/` or `openspec/changes/<change>/specs/` | `openspec_spec_list` | Returns array of spec names. Change-scoped or baseline. Filesystem-backed. |3435---3637## Tool → filesystem effect3839If you know the Hermes tools but want the exact filesystem mutation, this is40the reference.4142### Write tools4344| Tool | Filesystem effect | Lifecycle transition |45|---|---|---|46| `openspec_idea_create` | Creates `openspec/ideas/<slug>.md` | → Idea |47| `openspec_idea_enrich` | Updates `openspec/ideas/<slug>.md` with structured report | Idea (stays) |48| `openspec_idea_promote` | Creates `openspec/changes/<change>/` (proposal, tasks, specs) | Idea → Draft |49| `openspec_change_create` | Creates `openspec/changes/<change>/` (proposal, tasks, specs) | → Draft |50| `openspec_change_promote` | Ensures `tasks.md` has checklist items + `specs/` has placeholder | Draft → Todo |51| `openspec_task_set_status` | Toggles checkboxes in `openspec/changes/<change>/tasks.md` | Todo → In progress → Done |52| `openspec_change_archive` | Moves `openspec/changes/<change>/` → `openspec/changes/archive/<change>/` | Done → Archived |53| `openspec_change_unarchive` | Moves archive dir back to active changes | Archived → Done |54| `openspec_spec_diff` | Returns structured semantic delta (requirement/scenario level) between change spec and baseline, or worktree spec and HEAD. Read-only. | (no transition — read tool) |55| `openspec_spec_create` | Writes formatted spec.md from structured input (title, purpose, requirements with scenarios). `change` scopes to delta specs; omit for baseline. | (creates spec file) |56| `openspec_spec_show` | Reads and parses a spec into structured JSON (title, purpose, requirements, scenarios, steps). Read-only. | (no transition — read tool) |57| `openspec_spec_list` | Lists spec names under `openspec/specs/` or `openspec/changes/<change>/specs/`. Read-only. | (no transition — read tool) |5859### Read tools6061| Tool | Returns | When to call |62|---|---|---|63| `openspec_context` | Repo path + change/spec content (resolves `os_*` identifiers) | First — gives you the `workdir` for all other tools |64| `openspec_list` | Changes or specs in a project | Before picking a change to work on |65| `openspec_show` | Full change or spec as JSON | To read proposal/tasks/design/specs/deltas |66| `openspec_status` | Artifact completion status (what exists, what's missing) | Before promoting or archiving |67| `openspec_instructions` | Authoring guide for an artifact (proposal, design, tasks, specs, apply) | Before authoring or implementing |68| `openspec_validate` | Validation errors for changes/specs | After editing, before archiving |69| `openspec_task_list` | Task ids, text, status, completion counts | Before marking tasks done |7071> **Authoring note:** `openspec_instructions` returns the guide, not the72> artifact. After calling it, the caller writes the file (proposal.md,73> design.md, spec.md, tasks.md) using normal file tools. This is by design —74> the guide is reusable, the content is human/agent judgment.7576---7778← [Back to overview](index.md) · [← Previous: Lifecycle](lifecycle.md) · [Next: Delegation →](delegation.md)