51 lines
3.7 KiB
Markdown
51 lines
3.7 KiB
Markdown
---
|
|
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.
|