docs: split orchestration into lifecycle, tool-reference, delegation

dami etoile committed Jun 227dc0e8a

commit: 7dc0e8a1f3a10d7ac21ce08d5e878b7f5f936e06
parent: 107a60b8a011e91425885414de568369c72606ec
parent: cf0dce0a6c1700237371cf31db9e7a9c7e1bc5b2
author: dami etoile <dami.etoile@gmail.com>

6 files changed, +286 -272wrap lines

M	README.md	2	+-
A	docs/delegation.md	139	+++++++++++++++
A	docs/index.md	20	++
A	docs/lifecycle.md	56	++++++
D	docs/orchestration.md	271	------------------------------
A	docs/tool-reference.md	70	++++++++

M README.md +1 -1

@@ -24,7 +24,7 @@ This plugin closes both gaps:
2424 2525 `openspec_context` and the lifecycle write tools (idea/change/task) are filesystem-backed and always available. `openspec_list`, `openspec_show`, `openspec_validate`, `openspec_status`, and `openspec_instructions` require the `openspec` CLI binary.2626 27-For the full tool reference (what each does, when to call it, filesystem effects), see [docs/orchestration.md](docs/orchestration.md).27+For the full tool reference, lifecycle states, and delegation patterns, see [docs/index.md](docs/index.md).2828 2929 **Dashboard tab** (`/openspec`):3030 

A docs/delegation.md +139 -0

@@ -0,0 +1,139 @@
1+# Delegation2+3+How to run a change end-to-end and delegate authoring and implementation work4+to subagents.5+6+## Full workflow7+8+Two entry paths (idea pipeline or direct creation) converge at Draft, then9+follow the same path to archive. Authoring (design + specs) can be done by10+the orchestrator or delegated.11+12+```mermaid13+flowchart TD14+    subgraph Entry["Entry"]15+        IC["openspec_idea_create"] --> IE["openspec_idea_enrich"]16+        IE --> IP["openspec_idea_promote"]17+        CC["openspec_change_create"]18+    end19+20+    IP --> D[Draft]21+    CC --> D22+23+    D --> PROM["openspec_change_promote<br/>(ensure tasks + spec placeholder)"]24+    PROM --> T[Todo]25+26+    T --> AUTHOR["Author artifacts<br/>openspec_instructions → write design.md, specs"]27+    AUTHOR --> APPLY["openspec_instructions<br/>(artifact=apply)"]28+    APPLY --> IMPL["Implement<br/>openspec_task_set_status as tasks complete"]29+30+    IMPL --> VAL["openspec_validate"]31+    VAL -->|errors| AUTHOR32+    VAL -->|clean| STAT["openspec_status"]33+    STAT --> ARC["openspec_change_archive"]34+    ARC --> DONE[Archived]35+```36+37+Authoring and implementation are both delegatable (see below). The validation38+loop returns to authoring, not implementation — if specs are wrong, the spec39+needs fixing, not just the code.40+41+## Orchestration with subagent delegation42+43+The orchestrator owns the lifecycle: context resolution, change creation,44+promotion, validation, and archival. Subagents own authoring and/or45+implementation: they receive a change + scope, read the specs, write files or46+code, and mark tasks done.47+48+Two delegation patterns:49+50+| Pattern | Subagent does | Orchestrator does after |51+|---|---|---|52+| **Author** | Writes design.md / spec.md / tasks.md | Reviews, then promotes |53+| **Implement** | Writes code, marks task checkboxes | Validates, then archives |54+55+### Delegation contract56+57+The handoff is the same for both patterns — only the goal differs:58+59+| Field | Value | Why the subagent needs it |60+|---|---|---|61+| `workdir` | Absolute path to the repo | Required by every `openspec_*` tool |62+| `change` | Change id (kebab-case) | Identifies which change to read and update |63+| `task_ids` | List of task ids from `openspec_task_list` | Which tasks the subagent owns (implement only) |64+| `goal` | What to author or implement | The actual work — should reference spec sections |65+66+### Sequence: orchestrator with delegated authoring + implementation67+68+```mermaid69+sequenceDiagram70+    participant O as Orchestrator71+    participant A as Author subagent72+    participant I as Implement subagent73+    participant FS as OpenSpec filesystem74+75+    O->>FS: openspec_context(identifier) → workdir76+    O->>FS: openspec_change_create(workdir, change, title, summary)77+    O->>FS: openspec_instructions(workdir, artifact=design)78+79+    O->>A: delegate(goal: author design + specs, context: workdir + change)80+    A->>FS: openspec_show(workdir, change) → read proposal81+    A->>FS: openspec_instructions(workdir, artifact=specs)82+    Note over A: Write design.md, specs/<spec>/spec.md83+    A-->>O: Summary84+85+    O->>FS: openspec_validate(workdir, change)86+    O->>FS: openspec_change_promote(workdir, change)87+88+    O->>I: delegate(goal: implement, context: workdir + change + task_ids)89+    I->>FS: openspec_show(workdir, change) → read specs90+    I->>FS: openspec_instructions(workdir, artifact=apply)91+    Note over I: Implement code92+    I->>FS: openspec_task_set_status(workdir, change, task_ids, done)93+    I-->>O: Summary94+95+    O->>FS: openspec_validate(workdir, change)96+    O->>FS: openspec_status(workdir, change)97+    O->>FS: openspec_change_archive(workdir, change)98+```99+100+### Subagent rules101+102+The subagent should:103+1. Call `openspec_show(workdir, change)` to read the proposal, design, and specs.104+2. Call `openspec_instructions(workdir, artifact=...)` for the relevant guide.105+3. Do the work (write artifacts or implement code).106+4. If implementing: call `openspec_task_set_status(workdir, change, task_ids=..., status=done)` for completed tasks.107+5. Return a summary of what was done.108+109+The subagent should **not** create, promote, archive, or unarchive changes —110+that's the orchestrator's job. This keeps lifecycle ownership in one place and111+prevents race conditions when multiple subagents work on the same change.112+113+## Parallel delegation114+115+When a change has independent task groups, the orchestrator can delegate them116+in parallel. This works for both authoring (different specs) and117+implementation (different code areas):118+119+```mermaid120+flowchart LR121+    O[Orchestrator] -->|"spec: agent-tools"| S1[Author A]122+    O -->|"spec: dashboard-sources"| S2[Author B]123+    O -->|"task_ids [1,2]"| S3[Implement C]124+    O -->|"task_ids [3,4]"| S4[Implement D]125+    S1 -->|write spec.md| FS[(openspec/)]126+    S2 -->|write spec.md| FS127+    S3 -->|mark done| FS128+    S4 -->|mark done| FS129+```130+131+Each subagent writes to its own files (spec authoring) or marks only its own132+task ids (implementation). Because spec paths and task ids are unique, there133+are no write conflicts. The orchestrator runs `openspec_validate` and134+`openspec_status` after all subagents return to confirm everything is done135+before promoting or archiving.136+137+---138+139+← [Back to overview](index.md) · [← Previous: Tool reference](tool-reference.md)

A docs/index.md +20 -0

@@ -0,0 +1,20 @@
1+# Orchestration Pattern2+3+How to drive an OpenSpec change from idea to archive with Hermes agent tools,4+including delegating authoring and implementation to subagents.5+6+## Pages7+8+| Page | For | Covers |9+|---|---|---|10+| [Lifecycle](lifecycle.md) | Everyone | Change states, transitions, artifact readiness |11+| [Tool reference](tool-reference.md) | Two perspectives | Artifact → tool mapping (OpenSpec-native) and tool → filesystem effect (Hermes-native) |12+| [Delegation](delegation.md) | Orchestrators | Full workflow, subagent patterns, parallel delegation |13+14+### Which page to start with15+16+- **Hermes-native** — you know the agent tools but not the OpenSpec artifact17+  model. Start with [Tool reference → Tool → filesystem effect](tool-reference.md#tool--filesystem-effect).18+- **OpenSpec-native** — you know the lifecycle (idea → change → specs →19+  archive) but not which Hermes tool does what. Start with20+  [Tool reference → Artifact → tool mapping](tool-reference.md#artifact--tool-mapping).

A docs/lifecycle.md +56 -0

@@ -0,0 +1,56 @@
1+# Change Lifecycle2+3+Every change moves through the same states. States are derived from task4+checkboxes in `tasks.md` — there is no explicit state field.5+6+```mermaid7+stateDiagram-v28+    [*] --> Idea: idea_create9+    Idea --> Idea: idea_enrich10+    Idea --> Draft: idea_promote11+    [*] --> Draft: change_create12+    Draft --> Todo: change_promote13+    Todo --> InProgress: task_set_status (first task done)14+    InProgress --> Done: task_set_status (all tasks done)15+    Done --> Archived: change_archive16+    Archived --> Done: change_unarchive17+```18+19+| State | Meaning | Where it lives |20+|---|---|---|21+| Idea | Raw or enriched idea, not yet a change | `openspec/ideas/<slug>.md` |22+| Draft | Change scaffold exists but lacks tasks or spec placeholder | `openspec/changes/<change>/` |23+| Todo | Tasks and spec placeholder exist — ready to implement | `openspec/changes/<change>/` |24+| In progress | At least one task done, at least one remaining | `openspec/changes/<change>/` |25+| Done | All tasks done | `openspec/changes/<change>/` |26+| Archived | Completed, moved out of active board | `openspec/changes/archive/<change>/` |27+28+## Artifact readiness29+30+OpenSpec derives readiness from artifact dependencies. `openspec_status`31+surfaces this so you know when a change is safe to promote or archive.32+33+```mermaid34+flowchart LR35+    P[Proposal] --> S[Specs]36+    P --> D[Design]37+    S --> T[Tasks]38+    D --> T39+    T --> A[Apply]40+```41+42+- **Proposal** is always required. A change without it is invalid.43+- **Specs** define what the change does — required before tasks make sense.44+- **Design** explains how — optional for small changes, required for45+  non-trivial ones.46+- **Tasks** break the implementation into checklist items.47+- **Apply** is the implementation guide returned by48+  `openspec_instructions(artifact=apply)` — what a subagent follows to write49+  the code.50+51+`openspec_change_promote` requires tasks + spec placeholder. It does not52+require design — that's a judgment call for the orchestrator.53+54+---55+56+← [Back to overview](index.md) · [Next: Tool reference →](tool-reference.md)

D docs/orchestration.md +0 -271

@@ -1,271 +0,0 @@
1-# Orchestration Pattern2-3-This document describes the repeatable workflow for driving an OpenSpec change4-from idea to archive, including how to delegate authoring and implementation5-work to subagents.6-7-It's written for two audiences:8-9-- **Hermes-native** — you know the agent tools but not the OpenSpec artifact10-  model. Start with [Tool → filesystem effect](#tool--filesystem-effect).11-- **OpenSpec-native** — you know the lifecycle (idea → change → specs →12-  archive) but not which Hermes tool does what. Start with13-  [Artifact → tool mapping](#artifact--tool-mapping).14-15-Both perspectives describe the same system. The [full workflow](#full-workflow)16-and [delegation](#orchestration-with-subagent-delegation) sections apply to17-both.18-19----20-21-## Change lifecycle22-23-Every change moves through the same states. States are derived from task24-checkboxes in `tasks.md` — there is no explicit state field.25-26-```mermaid27-stateDiagram-v228-    [*] --> Idea: idea_create29-    Idea --> Idea: idea_enrich30-    Idea --> Draft: idea_promote31-    [*] --> Draft: change_create32-    Draft --> Todo: change_promote33-    Todo --> InProgress: task_set_status (first task done)34-    InProgress --> Done: task_set_status (all tasks done)35-    Done --> Archived: change_archive36-    Archived --> Done: change_unarchive37-```38-39-| State | Meaning | Where it lives |40-|---|---|---|41-| Idea | Raw or enriched idea, not yet a change | `openspec/ideas/<slug>.md` |42-| Draft | Change scaffold exists but lacks tasks or spec placeholder | `openspec/changes/<change>/` |43-| Todo | Tasks and spec placeholder exist — ready to implement | `openspec/changes/<change>/` |44-| In progress | At least one task done, at least one remaining | `openspec/changes/<change>/` |45-| Done | All tasks done | `openspec/changes/<change>/` |46-| Archived | Completed, moved out of active board | `openspec/changes/archive/<change>/` |47-48----49-50-## Artifact → tool mapping51-52-If you already know OpenSpec's artifact model (proposal, design, tasks, specs,53-ideas, archive), this table maps each artifact operation to the Hermes tool54-that performs it.55-56-| You want to… | OpenSpec artifact | Hermes tool | Effect |57-|---|---|---|---|58-| Capture a raw idea | `openspec/ideas/<slug>.md` (new) | `openspec_idea_create` | Writes the idea file |59-| 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 |60-| Turn an idea into a change | `openspec/changes/<change>/` (new) | `openspec_idea_promote` | Creates the change scaffold with proposal/tasks/spec traceability |61-| Create a change without an idea | `openspec/changes/<change>/` (new) | `openspec_change_create` | Creates the change scaffold directly |62-| Author the proposal | `openspec/changes/<change>/proposal.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |63-| Author the design doc | `openspec/changes/<change>/design.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |64-| Author specs | `openspec/changes/<change>/specs/<spec>/spec.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |65-| Author tasks | `openspec/changes/<change>/tasks.md` | `openspec_instructions` → write file | Returns the authoring guide; you write the file |66-| Mark a change ready to implement | `tasks.md` + `specs/` placeholder | `openspec_change_promote` | Ensures checklist items and spec placeholder exist |67-| Read a change or spec | Any artifact | `openspec_show` | Returns JSON: proposal, tasks, design, specs, deltas |68-| Get the implementation guide | `openspec apply` instructions | `openspec_instructions` (artifact=`apply`) | Returns step-by-step apply instructions |69-| Track task progress | `tasks.md` checkboxes | `openspec_task_set_status` | Toggles `- [ ]` ↔ `- [x]` |70-| Check what artifacts exist | Change directory | `openspec_status` | Returns which artifacts are present/missing and readiness |71-| Validate before archiving | All artifacts | `openspec_validate` | Returns validation errors |72-| Archive a completed change | `openspec/changes/archive/` | `openspec_change_archive` | Moves the change dir to archive |73-| Reopen an archived change | `openspec/changes/` (restore) | `openspec_change_unarchive` | Moves the change dir back to active |74-75-### Artifact readiness76-77-OpenSpec derives readiness from artifact dependencies. `openspec_status`78-surfaces this so you know when a change is safe to promote or archive.79-80-```mermaid81-flowchart LR82-    P[Proposal] --> S[Specs]83-    P --> D[Design]84-    S --> T[Tasks]85-    D --> T86-    T --> A[Apply]87-```88-89-- **Proposal** is always required. A change without it is invalid.90-- **Specs** define what the change does — required before tasks make sense.91-- **Design** explains how — optional for small changes, required for92-  non-trivial ones.93-- **Tasks** break the implementation into checklist items.94-- **Apply** is the implementation guide returned by95-  `openspec_instructions(artifact=apply)` — what a subagent follows to write96-  the code.97-98-`openspec_change_promote` requires tasks + spec placeholder. It does not99-require design — that's a judgment call for the orchestrator.100-101----102-103-## Tool → filesystem effect104-105-If you know the Hermes tools but want the exact filesystem mutation, this is106-the reference.107-108-### Write tools109-110-| Tool | Filesystem effect | Lifecycle transition |111-|---|---|---|112-| `openspec_idea_create` | Creates `openspec/ideas/<slug>.md` | → Idea |113-| `openspec_idea_enrich` | Updates `openspec/ideas/<slug>.md` with structured report | Idea (stays) |114-| `openspec_idea_promote` | Creates `openspec/changes/<change>/` (proposal, tasks, specs) | Idea → Draft |115-| `openspec_change_create` | Creates `openspec/changes/<change>/` (proposal, tasks, specs) | → Draft |116-| `openspec_change_promote` | Ensures `tasks.md` has checklist items + `specs/` has placeholder | Draft → Todo |117-| `openspec_task_set_status` | Toggles checkboxes in `openspec/changes/<change>/tasks.md` | Todo → In progress → Done |118-| `openspec_change_archive` | Moves `openspec/changes/<change>/` → `openspec/changes/archive/<change>/` | Done → Archived |119-| `openspec_change_unarchive` | Moves archive dir back to active changes | Archived → Done |120-121-### Read tools122-123-| Tool | Returns | When to call |124-|---|---|---|125-| `openspec_context` | Repo path + change/spec content (resolves `os_*` identifiers) | First — gives you the `workdir` for all other tools |126-| `openspec_list` | Changes or specs in a project | Before picking a change to work on |127-| `openspec_show` | Full change or spec as JSON | To read proposal/tasks/design/specs/deltas |128-| `openspec_status` | Artifact completion status (what exists, what's missing) | Before promoting or archiving |129-| `openspec_instructions` | Authoring guide for an artifact (proposal, design, tasks, specs, apply) | Before authoring or implementing |130-| `openspec_validate` | Validation errors for changes/specs | After editing, before archiving |131-| `openspec_task_list` | Task ids, text, status, completion counts | Before marking tasks done |132-133-> **Authoring note:** `openspec_instructions` returns the guide, not the134-> artifact. After calling it, the caller writes the file (proposal.md,135-> design.md, spec.md, tasks.md) using normal file tools. This is by design —136-> the guide is reusable, the content is human/agent judgment.137-138----139-140-## Full workflow141-142-Two entry paths (idea pipeline or direct creation) converge at Draft, then143-follow the same path to archive. Authoring (design + specs) can be done by144-the orchestrator or delegated.145-146-```mermaid147-flowchart TD148-    subgraph Entry["Entry"]149-        IC["openspec_idea_create"] --> IE["openspec_idea_enrich"]150-        IE --> IP["openspec_idea_promote"]151-        CC["openspec_change_create"]152-    end153-154-    IP --> D[Draft]155-    CC --> D156-157-    D --> PROM["openspec_change_promote<br/>(ensure tasks + spec placeholder)"]158-    PROM --> T[Todo]159-160-    T --> AUTHOR["Author artifacts<br/>openspec_instructions → write design.md, specs"]161-    AUTHOR --> APPLY["openspec_instructions<br/>(artifact=apply)"]162-    APPLY --> IMPL["Implement<br/>openspec_task_set_status as tasks complete"]163-164-    IMPL --> VAL["openspec_validate"]165-    VAL -->|errors| AUTHOR166-    VAL -->|clean| STAT["openspec_status"]167-    STAT --> ARC["openspec_change_archive"]168-    ARC --> DONE[Archived]169-```170-171-Authoring and implementation are both delegatable (see below). The validation172-loop returns to authoring, not implementation — if specs are wrong, the spec173-needs fixing, not just the code.174-175----176-177-## Orchestration with subagent delegation178-179-The orchestrator owns the lifecycle: context resolution, change creation,180-promotion, validation, and archival. Subagents own authoring and/or181-implementation: they receive a change + scope, read the specs, write files or182-code, and mark tasks done.183-184-Two delegation patterns:185-186-| Pattern | Subagent does | Orchator does after |187-|---|---|---|188-| **Author** | Writes design.md / spec.md / tasks.md | Reviews, then promotes |189-| **Implement** | Writes code, marks task checkboxes | Validates, then archives |190-191-### Delegation contract192-193-The handoff is the same for both patterns — only the goal differs:194-195-| Field | Value | Why the subagent needs it |196-|---|---|---|197-| `workdir` | Absolute path to the repo | Required by every `openspec_*` tool |198-| `change` | Change id (kebab-case) | Identifies which change to read and update |199-| `task_ids` | List of task ids from `openspec_task_list` | Which tasks the subagent owns (implement only) |200-| `goal` | What to author or implement | The actual work — should reference spec sections |201-202-### Sequence: orchestrator with delegated authoring + implementation203-204-```mermaid205-sequenceDiagram206-    participant O as Orchestrator207-    participant A as Author subagent208-    participant I as Implement subagent209-    participant FS as OpenSpec filesystem210-211-    O->>FS: openspec_context(identifier) → workdir212-    O->>FS: openspec_change_create(workdir, change, title, summary)213-    O->>FS: openspec_instructions(workdir, artifact=design)214-215-    O->>A: delegate(goal: author design + specs, context: workdir + change)216-    A->>FS: openspec_show(workdir, change) → read proposal217-    A->>FS: openspec_instructions(workdir, artifact=specs)218-    Note over A: Write design.md, specs/<spec>/spec.md219-    A-->>O: Summary220-221-    O->>FS: openspec_validate(workdir, change)222-    O->>FS: openspec_change_promote(workdir, change)223-224-    O->>I: delegate(goal: implement, context: workdir + change + task_ids)225-    I->>FS: openspec_show(workdir, change) → read specs226-    I->>FS: openspec_instructions(workdir, artifact=apply)227-    Note over I: Implement code228-    I->>FS: openspec_task_set_status(workdir, change, task_ids, done)229-    I-->>O: Summary230-231-    O->>FS: openspec_validate(workdir, change)232-    O->>FS: openspec_status(workdir, change)233-    O->>FS: openspec_change_archive(workdir, change)234-```235-236-### Subagent rules237-238-The subagent should:239-1. Call `openspec_show(workdir, change)` to read the proposal, design, and specs.240-2. Call `openspec_instructions(workdir, artifact=...)` for the relevant guide.241-3. Do the work (write artifacts or implement code).242-4. If implementing: call `openspec_task_set_status(workdir, change, task_ids=..., status=done)` for completed tasks.243-5. Return a summary of what was done.244-245-The subagent should **not** create, promote, archive, or unarchive changes —246-that's the orchestrator's job. This keeps lifecycle ownership in one place and247-prevents race conditions when multiple subagents work on the same change.248-249-### Parallel delegation250-251-When a change has independent task groups, the orchestrator can delegate them252-in parallel. This works for both authoring (different specs) and253-implementation (different code areas):254-255-```mermaid256-flowchart LR257-    O[Orchestrator] -->|"spec: agent-tools"| S1[Author A]258-    O -->|"spec: dashboard-sources"| S2[Author B]259-    O -->|"task_ids [1,2]"| S3[Implement C]260-    O -->|"task_ids [3,4]"| S4[Implement D]261-    S1 -->|write spec.md| FS[(openspec/)]262-    S2 -->|write spec.md| FS263-    S3 -->|mark done| FS264-    S4 -->|mark done| FS265-```266-267-Each subagent writes to its own files (spec authoring) or marks only its own268-task ids (implementation). Because spec paths and task ids are unique, there269-are no write conflicts. The orchestrator runs `openspec_validate` and270-`openspec_status` after all subagents return to confirm everything is done271-before promoting or archiving.

A docs/tool-reference.md +70 -0

@@ -0,0 +1,70 @@
1+# Tool Reference2+3+Two perspectives on the same 15 tools. Use whichever table matches what you4+already know.5+6+## Artifact → tool mapping7+8+If you already know OpenSpec's artifact model (proposal, design, tasks, specs,9+ideas, archive), this table maps each artifact operation to the Hermes tool10+that performs it.11+12+| 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+31+---32+33+## Tool → filesystem effect34+35+If you know the Hermes tools but want the exact filesystem mutation, this is36+the reference.37+38+### Write tools39+40+| Tool | Filesystem effect | Lifecycle transition |41+|---|---|---|42+| `openspec_idea_create` | Creates `openspec/ideas/<slug>.md` | → Idea |43+| `openspec_idea_enrich` | Updates `openspec/ideas/<slug>.md` with structured report | Idea (stays) |44+| `openspec_idea_promote` | Creates `openspec/changes/<change>/` (proposal, tasks, specs) | Idea → Draft |45+| `openspec_change_create` | Creates `openspec/changes/<change>/` (proposal, tasks, specs) | → Draft |46+| `openspec_change_promote` | Ensures `tasks.md` has checklist items + `specs/` has placeholder | Draft → Todo |47+| `openspec_task_set_status` | Toggles checkboxes in `openspec/changes/<change>/tasks.md` | Todo → In progress → Done |48+| `openspec_change_archive` | Moves `openspec/changes/<change>/` → `openspec/changes/archive/<change>/` | Done → Archived |49+| `openspec_change_unarchive` | Moves archive dir back to active changes | Archived → Done |50+51+### Read tools52+53+| Tool | Returns | When to call |54+|---|---|---|55+| `openspec_context` | Repo path + change/spec content (resolves `os_*` identifiers) | First — gives you the `workdir` for all other tools |56+| `openspec_list` | Changes or specs in a project | Before picking a change to work on |57+| `openspec_show` | Full change or spec as JSON | To read proposal/tasks/design/specs/deltas |58+| `openspec_status` | Artifact completion status (what exists, what's missing) | Before promoting or archiving |59+| `openspec_instructions` | Authoring guide for an artifact (proposal, design, tasks, specs, apply) | Before authoring or implementing |60+| `openspec_validate` | Validation errors for changes/specs | After editing, before archiving |61+| `openspec_task_list` | Task ids, text, status, completion counts | Before marking tasks done |62+63+> **Authoring note:** `openspec_instructions` returns the guide, not the64+> artifact. After calling it, the caller writes the file (proposal.md,65+> design.md, spec.md, tasks.md) using normal file tools. This is by design —66+> the guide is reusable, the content is human/agent judgment.67+68+---69+70+← [Back to overview](index.md) · [← Previous: Lifecycle](lifecycle.md) · [Next: Delegation →](delegation.md)