feat(skills): add /work-decompose and /work-dispatch orchestration skills
In-session skill counterparts to `pnpm work decompose --execute` and `pnpm work dispatch --execute`. They dispatch sub-agents — a decomposer for /work-decompose; separate worktree-isolated implementer and read-only reviewer sub-agents for /work-dispatch's implement-review loop. Single source of truth: the skills read `.sandcastle/*.prompt.md` at dispatch time and never copy them — the prompt files stay authoritative for both Sandcastle and the skills, so the role definitions cannot drift. `.sandcastle/` and `pnpm work` are untouched; this is additive.
This commit is contained in:
50
.claude/skills/work-decompose/SKILL.md
Normal file
50
.claude/skills/work-decompose/SKILL.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: work-decompose
|
||||
description: Use when an approved PRD must be broken into an epic with story and task files under docs/work/. Triggers — the user asks to decompose a PRD, invokes /work-decompose, or wants a PRD turned into the work tree.
|
||||
---
|
||||
|
||||
# work-decompose
|
||||
|
||||
Decompose an `approved` PRD into an epic + story files under `docs/work/epics/`, by dispatching a **decomposer sub-agent** whose role is defined by the existing Sandcastle prompt.
|
||||
|
||||
This is the in-session, skill form of `pnpm work decompose --execute`. It adds a path; it changes nothing about `.sandcastle/` or `pnpm work`.
|
||||
|
||||
## Single source of truth — do not copy the prompt
|
||||
|
||||
The decomposer's role is defined in **`.sandcastle/decomposer.prompt.md`** — the same file `pnpm work decompose --execute` consumes. This skill **reads that file at dispatch time and passes it verbatim**. Never paraphrase, summarise, or inline it here. If this skill and the prompt ever disagree, **the prompt wins** — fix this skill, not the prompt.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Resolve the PRD.** The user names a PRD (slug or path); otherwise list `docs/work/prds/*.prd.md` and ask which. Read the file.
|
||||
|
||||
2. **Refuse drafts.** If the PRD's frontmatter `status:` is not `approved`, **stop** — tell the user to flip it after review. The decomposer refuses drafts; catch it early.
|
||||
|
||||
3. **Build the prompt.** Read `.sandcastle/decomposer.prompt.md`. Substitute its `{{PRD_FILE_CONTENT}}` placeholder with the full PRD file contents.
|
||||
|
||||
4. **Dispatch the decomposer sub-agent.** Use the Agent tool, `general-purpose`. Its instructions are the substituted prompt, followed by this environment-adaptation note (the note adapts the environment — it is not a prompt edit):
|
||||
|
||||
> **Environment:** you are a Claude Code sub-agent, not running inside Sandcastle. Ignore the `<promise>COMPLETE</promise>` marker instruction — there is no iteration loop; just return your final summary. Write the epic + story files to `docs/work/epics/`. **Do not commit** — leave the files for the human to review and commit, per your own "offer them a chance to review + edit" step.
|
||||
|
||||
5. **Report.** Relay the epic folder path the sub-agent created. Remind the user to review/edit the stories, then commit, and that `pnpm work rebuild-state` (or the pre-commit hook) refreshes `_state.json`. The next step in the pipeline is `/work-dispatch`.
|
||||
|
||||
## Why a sub-agent
|
||||
|
||||
Decomposition is a self-contained, read-heavy job — the whole PRD, the slice-rule reasoning, the file-writing. Running it in a sub-agent keeps all of that out of the main session; you get back only the epic path.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| | |
|
||||
| ----------------- | ------------------------------------------------------------------ |
|
||||
| Input | an `approved` PRD in `docs/work/prds/` |
|
||||
| Role prompt | `.sandcastle/decomposer.prompt.md` — read, never copied |
|
||||
| Sub-agent | one `general-purpose` agent |
|
||||
| Output | `docs/work/epics/<epic-id>/` — `_epic.md` + `NN-<story>/_story.md` |
|
||||
| Upstream | `to-prd` / `grill-with-docs` produce the PRD |
|
||||
| Downstream | `/work-dispatch` runs the tasks |
|
||||
| Sandcastle parity | mirrors `pnpm work decompose --execute` |
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Copying the prompt into this skill.** `.sandcastle/decomposer.prompt.md` is the source of truth — read it at dispatch time, every time.
|
||||
- **Decomposing a `draft` PRD.** Check `status: approved` first.
|
||||
- **Letting the sub-agent commit.** It writes files; the human reviews and commits.
|
||||
Reference in New Issue
Block a user