1# Delegation23How to run a change end-to-end and delegate authoring and implementation work4to subagents.56## Full workflow78Two entry paths (idea pipeline or direct creation) converge at Draft, then9follow the same path to archive. Authoring (design + specs) can be done by10the orchestrator or delegated.1112```mermaid13flowchart 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 end1920 IP --> D[Draft]21 CC --> D2223 D --> PROM["openspec_change_promote<br/>(ensure tasks + spec placeholder)"]24 PROM --> T[Todo]2526 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"]2930 IMPL --> VAL["openspec_validate"]31 VAL -->|errors| AUTHOR32 VAL -->|clean| STAT["openspec_status"]33 STAT --> ARC["openspec_change_archive"]34 ARC --> DONE[Archived]35```3637Authoring and implementation are both delegatable (see below). The validation38loop returns to authoring, not implementation — if specs are wrong, the spec39needs fixing, not just the code.4041## Orchestration with subagent delegation4243The orchestrator owns the lifecycle: context resolution, change creation,44promotion, validation, and archival. Subagents own authoring and/or45implementation: they receive a change + scope, read the specs, write files or46code, and mark tasks done.4748Two delegation patterns:4950| 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 |5455### Delegation contract5657The handoff is the same for both patterns — only the goal differs:5859| 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 |6566### Sequence: orchestrator with delegated authoring + implementation6768```mermaid69sequenceDiagram70 participant O as Orchestrator71 participant A as Author subagent72 participant I as Implement subagent73 participant FS as OpenSpec filesystem7475 O->>FS: openspec_context(identifier) → workdir76 O->>FS: openspec_change_create(workdir, change, title, summary)77 O->>FS: openspec_instructions(workdir, artifact=design)7879 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: Summary8485 O->>FS: openspec_validate(workdir, change)86 O->>FS: openspec_change_promote(workdir, change)8788 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: Summary9495 O->>FS: openspec_validate(workdir, change)96 O->>FS: openspec_status(workdir, change)97 O->>FS: openspec_change_archive(workdir, change)98```99100### Subagent rules101102The subagent should:1031. Call `openspec_show(workdir, change)` to read the proposal, design, and specs.1042. Call `openspec_instructions(workdir, artifact=...)` for the relevant guide.1053. Do the work (write artifacts or implement code).1064. If implementing: call `openspec_task_set_status(workdir, change, task_ids=..., status=done)` for completed tasks.1075. Return a summary of what was done.108109The subagent should **not** create, promote, archive, or unarchive changes —110that's the orchestrator's job. This keeps lifecycle ownership in one place and111prevents race conditions when multiple subagents work on the same change.112113## Parallel delegation114115When a change has independent task groups, the orchestrator can delegate them116in parallel. This works for both authoring (different specs) and117implementation (different code areas):118119```mermaid120flowchart 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```130131Each subagent writes to its own files (spec authoring) or marks only its own132task ids (implementation). Because spec paths and task ids are unique, there133are no write conflicts. The orchestrator runs `openspec_validate` and134`openspec_status` after all subagents return to confirm everything is done135before promoting or archiving.136137---138139← [Back to overview](index.md) · [← Previous: Tool reference](tool-reference.md)