agentic-dev/.claude/skills/work-decompose/SKILL.md

name, description

name	description
work-decompose	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.