Two-perspective workflow doc for driving OpenSpec changes with Hermes tools and subagent delegation: - Artifact → tool mapping (for OpenSpec-native readers) - Tool → filesystem effect (for Hermes-native readers) - Change lifecycle state diagram - Full workflow flowchart with two entry paths - Delegation contract and sequence diagram (author + implement patterns) - Parallel delegation for independent spec/task groups - Authoring is delegatable, lifecycle ownership stays with orchestrator
- commit
- 607cb6fbf2e3fa7f68bb5f93b8346da1055e1ae1
- parent
- 7f9eea9f70996e4619a1744c36f4db5840514e5f
- author
- dami etoile <dami.etoile@gmail.com>
| A | docs/ | 271 | ++++++++++++++++++++++++++++++ |
@@ -0,0 +1,271 @@
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.