project-setup

name	project-setup
description	Use when converting a plan file (from writing-plans skill) into beads epics, tasks, implementation prompts, and worktrees — before any coding begins

Project Setup

Convert a plan file into beads epics and tasks with TDD-quality descriptions, filled implementation prompts, and ready-to-use worktrees.

Core principle: Task descriptions are the source of truth. Each task is a self-contained implementation guide — detailed enough for an agent to work autonomously.

Announce at start: "I'm using the project-setup skill to decompose this plan into epics and tasks."

Phase 0 — Review gate (hard bail)

This is the first gate and the ONLY structurally-enforceable gate in the planning-skill review loop. A SKILL.md is prose the agent follows; the upstream wrapper's pre-flight greps are strong-but-soft behavioral guardrails. This gate is different: project-setup is thrum-owned, so it is authored to genuinely refuse to run.

Before doing anything else, verify the plan/spec doc carries a passing review stamp. Resolve the plan path first (it is the skill's primary input — the same path the caller passes), then:

# PLAN_FILE = the plan/spec doc this project-setup run is decomposing
grep -F 'THRUM-REVIEW: stage=plan verdict=Ready:Yes' "$PLAN_FILE" \
  || grep -F 'THRUM-REVIEW: stage=plan verdict=OVERRIDE' "$PLAN_FILE"

Notes on the check:

• Case-sensitive, literal match. Use grep -F on the exact canonical (fixed-key-order) string. Never grep -i. The canonical verdict values are exactly Ready:Yes and OVERRIDE — a mis-cased stamp (ready:yes, READY:YES) does NOT pass.
• OVERRIDE is a valid pass. A coordinator override (logged when the review loop hit its cap with BLOCKINGs still open) is an authorized way through this gate — accept it exactly like Ready:Yes. Surface any THRUM-DEFER lines still present in the doc as part of the override audit.

If neither stamp is present, STOP — do not proceed. Tell the user:

project-setup requires the plan/spec to have passed the planning-loop review (or carry a coordinator override). The plan at <PLAN_FILE> has no THRUM-REVIEW: stage=plan verdict=Ready:Yes (or verdict=OVERRIDE) stamp. Run the plan review first, or obtain a coordinator override, then re-invoke project-setup.

Fail closed, not open. Plans that predate this feature, or that arrive from a different flow, will not carry the stamp — they still bail. The caller must add an OVERRIDE stamp (a deliberate coordinator decision, with a reason) to proceed. Do not silently fall through when the stamp is absent.

When to Use

digraph when_to_use {
    "Have a design doc?" [shape=diamond];
    "Have a plan file?" [shape=diamond];
    "Need epics & tasks?" [shape=diamond];
    "Use coordinator-running-brainstorm-cycles skill first" [shape=box];
    "Use writing-plans skill first" [shape=box];
    "Already have tasks in beads" [shape=box];
    "Run project-setup" [shape=doublecircle];

    "Have a design doc?" -> "Use coordinator-running-brainstorm-cycles skill first" [label="no"];
    "Have a design doc?" -> "Have a plan file?" [label="yes"];
    "Have a plan file?" -> "Use writing-plans skill first" [label="no"];
    "Have a plan file?" -> "Need epics & tasks?" [label="yes"];
    "Need epics & tasks?" -> "Already have tasks in beads" [label="no"];
    "Need epics & tasks?" -> "Run project-setup" [label="yes"];
}

Don't use when:

• No design doc exists yet — use the coordinator-running-brainstorm-cycles skill first (spawns a researcher in an isolated worktree, runs the brainstorm interactively with the user, iterates dual-review cycles, then hands off back to project-setup)
• No plan file exists yet — use writing-plans skill first
• Tasks already exist in beads — go straight to creating the implementation prompt closely following the template (implementation-agent.md)

Prerequisites

Two prereqs must be satisfied before project-setup proceeds. Bail on either rather than trying to work around it.

Beads (bd) installed

Verify beads is installed:

bd version

If bd is not found, stop and tell the user:

project-setup requires beads (bd) for task tracking with dependencies. Install it:

brew install dolt                    # required dependency
brew install steveyegge/beads/bd     # beads CLI
bd init                              # initialize in your repo

See the beads repo for alternative install methods. Requires dolt v1.81.8+ and bd v0.59.0+.

Do not proceed without beads. Do not fall back to markdown task lists or TodoWrite.

Implementation Philosophy Doc

Verify the project has an implementation philosophy doc at the canonical path. In worktrees, .thrum/ is a redirect file pointing at the project root's real .thrum/ directory — the check must resolve through it:

PHILOSOPHY_DIR=.thrum
[ -f .thrum/redirect ] && PHILOSOPHY_DIR="$(cat .thrum/redirect)"
test -f "$PHILOSOPHY_DIR/philosophy.md"

If the file does not exist, stop and tell the user:

project-setup requires a philosophy doc at .thrum/philosophy.md. Run the project-philosophy skill first to generate or locate one, then re-invoke project-setup.

Do not proceed without the philosophy doc. Do not inline-create.

If the doc exists, read it and extract the anti-patterns for injection in Phase 4. Refer to the project-philosophy skill for the doc contents and the anti-pattern format.

Inputs

Primary input: plan file path (output of writing-plans, e.g. dev-docs/plans/2026-02-21-feature-plan.md). The plan references the design doc — both are read in Phase 1.

Also needed from CLAUDE.md or conversation context:

• Project root — absolute path to the project
• Tech stack — languages, frameworks, tools in use
• Quality commands — test/lint commands (e.g. make test && make lint)
• Coverage target — minimum coverage threshold (e.g. >80%)

If any are missing, ask the user (prefer multiple choice when possible).

Phase 1: Understand the Plan

Read the plan file and the design doc it references. Identify major phases, components, data flow, and interfaces.

The Two-Artifact System

This skill produces two complementary artifacts per task:

Artifact	Contains	Authoritative For
Beads task	Acceptance criteria, deps, status	What must be true to close the task
Plan file section	Step-by-step code, file paths, verify commands	How to implement the task

Both are required. Agents read bd show {TASK_ID} first (what must be true), then search the plan file for the matching ## Task: {BEAD_ID} section (how to get there).

If the plan file lacks code for a task, the task description must be detailed enough to stand alone. Flag any plan tasks with vague or missing implementation code during this phase.

Explore the codebase and recent beads state in parallel. Partition the work so:

• One sub-agent maps packages, interfaces, and patterns relevant to {{FEATURE_DESCRIPTION}} — output: output/planning/codebase-scan.md.
• One sub-agent runs bd list --status=open, bd ready, and bd blocked and identifies work related to {{FEATURE_DESCRIPTION}} — output: output/planning/beads-context.md.

Invoke efficient-multi-agent-research for the launch-and-wait mechanics. After agents complete, read the two output files — do not fan-read individual beads entries into your main context.

Ask the user focused questions (prefer multiple choice) about anything the plan leaves ambiguous — constraints, scope boundaries, patterns to follow.

Phase 2: Decompose into Epics & Tasks

Map Plan Phases to Epics

Map each plan phase to a beads epic. Each epic should:

• Represent a cohesive, independently deliverable unit of work
• Be completable in 1-3 agent sessions
• Have clear boundaries (a single worktree/branch per epic)
• Map to a logical layer or component from the design spec

Naming: Imperative form — "Implement Sync Protocol", "Build Session Manager", "Create Filter Component".

Present the epic breakdown to the user for approval before creating anything.

Create Epics in Beads

Once the user approves the epic breakdown:

bd create "Epic Title" --type=epic --priority=1

# If epics have ordering dependencies:
bd dep add <later-epic-id> <earlier-epic-id>

Create Tasks

When creating > 6 tasks, delegate to parallel sub-agents — one per epic. Each sub-agent (haiku is sufficient — the work is mechanical) gets the epic ID, the list of bd create --title=... --type=task --priority=N --description=... commands to run, the within-epic bd dep add <later_id> <earlier_id> ordering commands, and instructions to return the created task IDs and titles. Invoke efficient-multi-agent-research § Core Pattern for launch-and-wait mechanics.

After sub-agents return IDs, set cross-epic dependencies directly (requires IDs from multiple sub-agents):

bd dep add <epic-2-id> <epic-1-id>

# Verify no circular dependencies
bd blocked

Task Description Quality

Every beads task description is a self-contained implementation guide:

Required sections:

## Files

- Create: `exact/path/to/new_file.go`
- Modify: `exact/path/to/existing.go` (add XyzService interface)
- Test: `exact/path/to/new_file_test.go`

## Steps

### Step 1: Write the failing test

```go
func TestSpecificBehavior(t *testing.T) {
    result := Function(input)
    assert.Equal(t, expected, result)
}
```

### Step 2: Implement

```go
func Function(input Type) ReturnType {
    // implementation
}
```

### Step 3: Verify and commit

```bash
go test ./path/to/package/... -run TestSpecificBehavior -v
git commit -m "feat(module): add specific feature"
```

## Acceptance Criteria

- [ ] All tests pass
- [ ] Function handles edge case X
- [ ] Error returns are typed, not generic

Scale code detail to task type:

Task Type	Code in Steps	Test Detail
API/Interface design	Full signatures + types	Contract tests, error case tests
Business logic	Full implementation code	TDD: failing test → implement → pass
Integration/Wiring	Connection code + config	Integration test against mock/real dependency
UI/Styling	Full CSS/component code	Visual verification steps, screenshot check
Testing-only	N/A	Full test code with scenarios and edge cases
Documentation	N/A (outline only)	Verification: doc renders, links work

Granularity: Each task should be completable in one focused session (30-90 minutes). If a task has more than 5 steps, split it.

Ensure Refactoring Epic Exists

Implementation agents log DRY/refactoring opportunities they discover during feature work. These go into a persistent refactoring epic in beads. Check if one exists; if not, create it:

# Search for existing refactoring epic
bd list --type=epic | grep -i refactor

If found, note the epic ID — it will be referenced in the implementation template's "Logging Refactoring Opportunities" section.

If not found, create one:

bd create "Refactoring & DRY Opportunities" --type=epic --priority=3 \
  --description="Persistent backlog for refactoring, DRY improvements, and code
organization opportunities discovered during feature work. Tasks are added by
implementation agents as they encounter opportunities. Reviewed and prioritized
by the coordinator periodically."

This epic is project-wide and long-lived — it persists across feature epics. Do not close it when closing feature epics. Implementation agents find it via bd list --type=epic | grep -i refactor and add tasks under it.

Verify Setup

Before proceeding to Phase 3:

• Every task has a clear title and detailed description
• Task ordering within each epic makes sense (foundations first)
• Epic dependencies reflect the actual build order
• No circular dependencies (bd blocked should be clean)
• Each epic can be assigned to one worktree/branch
• Total scope is realistic (flag if > 20 tasks per epic)

Verify Plan File Anchors

After creating all tasks, verify the plan file has a searchable anchor for each task. Implementation agents find their code by searching for:

## Task: {BEAD_ID} — {Title}

For each created task, grep the plan file:

grep "## Task:" {{PLAN_FILE}} | head -20

Cross-reference against the created bead IDs. If any task lacks a matching anchor, add it to the plan file at the corresponding section. This ensures agents can search for their section instead of reading the entire (potentially large) file.

Detect Cross-Epic Dependencies

After setting all dependencies, scan for tasks that depend on tasks in OTHER epics:

bd blocked

For each cross-epic dependency (where the blocker is in a different epic than the blocked task), record:

Blocked Task	Blocked By	Blocker's Epic

Save this map — it feeds Phase 4, where each implementation prompt will include its epic's cross-epic dependencies so agents know exactly which external tasks to check before starting blocked work.

If no cross-epic dependencies exist, note that and move on.

Phase 3: Select Worktrees & Agents

This phase is an interactive decision gate. You MUST ask the user which worktree and agent to use for each epic before generating prompts. Do not infer silently — present options and let the user choose.

Step 1: Gather Current State

Run these commands and present the results to the user:

# List all active worktrees with branches
git worktree list

# Check which worktrees have in-progress beads tasks
bd list --status=in_progress

# Check the CLAUDE.md worktree table for status info
# (read the "Worktree Layout" section from the project root CLAUDE.md)

Step 2: Present Worktree Options

For each epic, use AskUserQuestion to let the user choose a worktree. Build the options from the gathered state:

Option types to present:

Scenario	Option label
Existing idle worktree with related branch	"Reuse <path> (<branch>)"
Existing idle worktree, unrelated branch	"Reuse <path>, create new branch"
No suitable worktree exists	"Create new worktree"
Work is small enough for the current branch	"Use current worktree (<branch>)"

Include in each option's description:

• The worktree path and current branch
• Whether it's clean or has uncommitted changes
• Whether it has an existing agent registered
• Its status from CLAUDE.md (active/idle/merged)

For "Create new worktree", suggest:

• Path: ~/.workspaces/{repo}/{feature} (from CLAUDE.md convention)
• Branch: feature/{feature-name} (from thrum-dev)

For agent names, suggest a name derived from the feature in each option description (e.g., impl_{feature}). The user can override.

Step 3: Set Up the Chosen Worktree

Based on the user's choice, execute the appropriate setup:

For reused worktrees

cd <worktree-path>

# Check if clean
git status

# Fast-forward or rebase to thrum-dev if behind
git fetch origin thrum-dev
git rebase origin/thrum-dev
# OR if branches diverged: ask user before rebasing

# Verify redirects are intact
cat .thrum/redirect    # should point to <project-root>/.thrum
cat .beads/redirect    # should point to <project-root>/.beads

# If redirects are missing or wrong, fix them:
# (from project root)
./scripts/setup-worktree-thrum.sh <worktree-path>

# Verify beads sees shared database
bd where    # Should show <project-root>/.beads
bd ready    # Should show issues from the shared database

# Register the agent (if not already registered with the right name)
thrum quickstart --name <agent-name> --role implementer \
  --module <branch-name> --intent "Implementing <epic-id>"

For new worktrees

The preferred path is thrum worktree create (alias: thrum worktree setup). Both commands are interchangeable — use whichever you prefer. They create the worktree, set up thrum and beads redirects, register the agent identity, and enforce single-identity-per-worktree (registering a second identity in the same worktree is an error).

# Preferred: single command via thrum CLI
thrum worktree create <worktree-path> <branch-name> \
  --identity <agent-name> --role implementer --base thrum-dev

# Alias — identical behavior
thrum worktree setup <worktree-path> <branch-name> \
  --identity <agent-name> --role implementer --base thrum-dev

# Alternative: shell script (does the same thing)
./scripts/setup-worktree-thrum.sh \
  <worktree-path> <branch-name> \
  --identity <agent-name> --role implementer --base thrum-dev

All three handle: branch creation, worktree creation, thrum redirect, beads redirect, and thrum quickstart registration.

For current worktree (small fixes)

# Just register the agent
thrum quickstart --name <agent-name> --role implementer \
  --module <current-branch> --intent "Implementing <epic-id>"

# Verify beads
bd where
bd ready

Step 4: Verify Setup

Before proceeding to Phase 4, verify for each worktree:

cd <worktree-path>

# Beads sees shared database
bd where
# Expected: <project-root>/.beads

# Issues are visible
bd ready

# Thrum daemon reachable
thrum daemon status

# Redirects correct
cat .thrum/redirect
cat .beads/redirect

# Agent registered
thrum agent list --context

Step 5: Update CLAUDE.md

If a new worktree was created, update the worktree table in the project root CLAUDE.md. Use the existing table format:

| `<path>` | `<branch>` | <purpose> | active |

Troubleshooting

"not in a bd workspace" — The beads redirect file is missing or incorrect:

ls -la .beads/
cat .beads/redirect
bd where
# Fix: run setup-worktree-thrum.sh <path> (redirect-only mode)

Wrong database — bd where shows a local database instead of shared:

bd where
# Should show <project-root>/.beads, not a local database
# Fix: rm .beads/*.db && re-run setup script

Sync warnings in worktrees — Warnings about "snapshot validation failed" or "git status failed" are normal in worktrees. If the final output shows success, it's fine.

Record Worktree Assignments

At the end of this phase, you should have a confirmed assignment for each epic:

Epic	Worktree Path	Branch	Agent Name
<epic-id>	<path>	<branch>	<agent-name>

These values feed directly into the {{PLACEHOLDER}} resolution in Phase 4.

Phase 4: Generate Implementation Prompts

CRITICAL: You MUST generate prompts yourself. Do NOT delegate prompt generation to sub-agents. Sub-agents take shortcuts — they skip sections, leave template metadata in the output, fail to strip meta-sections, and produce prompts that confuse the implementation agent. The prompt is the most important artifact this skill produces. It defines how the implementation agent behaves for the entire epic. Treat it with the same care as writing code.

For each epic/worktree assignment, generate a filled prompt file.

Step 1: Read the template

Read the implementation-agent.md file from this skill's resources/ directory.

This is the source template. Do not work from memory — read the actual file every time.

Step 1.5: Generate Anti-Patterns for Each Epic

For each epic's prompt, derive the {{ANTI_PATTERNS}} content by combining two sources:

1. The design doc's Key Decisions section — implementation-constraining decisions (e.g., "full page reload, not HTMX", "real service calls, not hardcoded").
2. The philosophy doc's Anti-Patterns and Red Flags sections (already read during the Prerequisites check).

Present the derived anti-patterns to the user for approval via AskUserQuestion before injecting into the prompt.

Refer to the project-philosophy skill for the anti-pattern format spec (rule count, grep-ability, positive + negative pair structure).

Why this matters: The verifier sub-agent pattern in the implementation template uses these red flags to check each task. Generic "tests pass" verification misses architectural violations that pass tests but violate design decisions.

Step 2: Resolve all placeholders

Perform literal find-and-replace on every {{PLACEHOLDER}} in the template. All worktree-related values come from the Phase 3 assignments:

Placeholder	Source
{{EPIC_ID}}	Beads epic ID from Phase 2
{{EPIC_TITLE}}	Epic title (used in commit messages)
{{WORKTREE_PATH}}	From Phase 3 worktree assignment
{{BRANCH_NAME}}	From Phase 3 worktree assignment
{{PROJECT_ROOT}}	Absolute path to the project root
{{DESIGN_DOC}}	Absolute path to the design spec
{{REFERENCE_CODE}}	Relevant reference code paths (relative OK if committed)
{{QUALITY_COMMANDS}}	Test/lint commands — scoped to packages this epic modifies. Avoid full-suite commands (e.g., go test ./...) that hit pre-existing failures. Example: go build ./... && go test ./internal/processing/localstore/ -v
{{COVERAGE_TARGET}}	Coverage threshold (e.g., >80%)
{{AGENT_NAME}}	From Phase 3 agent registration
{{PLAN_FILE}}	Absolute path to the plan file (primary input)
{{ANTI_PATTERNS}}	Generated in Step 1.5; refer to the project-philosophy skill for the anti-pattern format spec.
{{SUPERVISOR_NAME}}	From thrum team — first agent with role=orchestrator; if none, first with role=coordinator; if none, ask user
{{CROSS_EPIC_DEPS}}	From Phase 2 cross-epic dependency map. If no cross-epic deps, replace with "No cross-epic dependencies."

IMPORTANT — Absolute paths for gitignored files: {{DESIGN_DOC}}, {{PLAN_FILE}}, and the saved prompt path (dev-docs/prompts/) are typically gitignored. Agents in worktrees cannot resolve relative paths to these files because worktrees only share committed content. Always resolve these to absolute paths (e.g., /Users/you/project/dev-docs/plans/file.md, not dev-docs/plans/file.md). This also applies to beads task descriptions — any reference to a plan or design doc in a task description must be an absolute path.

Strip template meta-sections. The following sections exist to document the template itself and MUST NOT appear in the filled prompt:

• ## Purpose — template description, not agent instructions
• ## CRITICAL: Prompt Generation Rules — instructions for the coordinator filling the template, not for the implementation agent
• ## Inputs Required — placeholder documentation for the coordinator, not the agent. Including this section confuses agents with {{PLACEHOLDER}} descriptions alongside already-resolved values.
• Any <!-- STRIP ... --> HTML comment blocks — these are meta-instructions that must be removed along with any text they annotate
• Any lines that address "the coordinator" or say "when filling this template"

Keep all behavioral sections. The output must contain every behavioral section from the template — Sub-Agent Strategy, all 4 Phases (including the new Phase 3: Self-Review Gate), Resume Quick Reference, etc. — with placeholders replaced by resolved values. Do not omit, reorganize, or summarize behavioral sections.

Step 3: Prepend feature-specific context

Add a header before the filled template with quick context, task inventory, and architecture notes specific to this feature:

# Implementation Prompt: {{FEATURE_NAME}}

> Generated by project-setup on YYYY-MM-DD Plan: {{PLAN_FILE}} Design doc:
> {{DESIGN_DOC}} Epic: {{EPIC_ID}} (N tasks)

## Quick Context

<!-- 2-3 sentences about what this epic delivers and key decisions -->

<!-- Optional: task inventory table, architecture notes, suggested batches -->

## Worktree Setup

<!-- If worktree was already created in Phase 3, note that here: -->

Worktree ready at `{{WORKTREE_PATH}}` on branch `{{BRANCH_NAME}}`. Agent
`{{AGENT_NAME}}` registered.

<!-- If worktree needs to be created by the implementation agent: -->

./scripts/setup-worktree-thrum.sh {{WORKTREE_PATH}} {{BRANCH_NAME}} \
 --identity {{AGENT_NAME}} --role implementer --base thrum-dev

---

<!-- PASTE the filled template below this line.
     STRIP the "## Purpose" and "## Inputs Required" sections — those are
     template meta-documentation, not agent instructions.
     START from "## Sub-Agent Strategy" through "## Resume Quick Reference".
     All behavioral sections must be present with placeholders resolved. -->

Step 3.5: Insert review gates between epics

For multi-epic prompts (where one implementation agent handles sequential epics), insert a review gate block after each epic's task section. Use the template from implementation-agent.md (between REVIEW_GATE_TEMPLATE_START and REVIEW_GATE_TEMPLATE_END comments):

## Review Gate: <EPIC_BEAD_ID>

Before proceeding to the next epic:

1. Commit all work for this epic
2. Run tests: verify all tests pass for changes in this epic
3. Report completion via Thrum:
   `thrum send "Epic <EPIC_BEAD_ID> complete. Ready for review." --to @<SUPERVISOR_NAME>`
4. Set status: `thrum agent set-status idle`
5. **STOP.** Wait for review approval before continuing.

Resolve {{EPIC_ID}} with the current epic's bead ID and {{SUPERVISOR_NAME}} with the supervisor agent name. Insert one gate after each epic's tasks, before the next epic's heading. The orchestrator validates prompts by checking for ## Review Gate: headings — prompts without them will be rejected.

For single-epic prompts, omit the review gate (the Self-Review Gate in Phase 3 handles end-of-work review).

Step 4: Save and commit

Save to dev-docs/prompts/{feature}.md, then commit:

git add dev-docs/prompts/
git commit -m "plan: add implementation prompts for {{FEATURE_NAME}}"

Step 5: Stamp the prompt for the review loop

project-setup OWNS the impl-prompt stamps (the researcher stamps the brainstorm and plan stages; project-setup stamps the prompt stage — per the stamp-authorship convention). Two stamps, appended as a footer to the generated prompt file:

1. Immediately after generating the prompt, append the gate footer:

   <!-- THRUM-GATE: stage=prompt next=dispatch -->
   

2. After the post-setup prompt review terminates Ready:Yes, append the verdict stamp:

   <!-- THRUM-REVIEW: stage=prompt verdict=Ready:Yes cycle=<N> date=<YYYY-MM-DD> -->
   

   This review happens within the same project-setup session: after Step 4 generates the prompt, you dispatch the prompt dual-review (per the coordinator-running-brainstorm-cycles Phase 7 flow), wait for it to terminate, then append this stamp before closing out. Do NOT end the session at Step 4 and re-invoke project-setup later for the stamp.

Use the exact canonical, case-sensitive form (Ready:Yes / OVERRIDE; keep keys in the fixed order stage=, verdict=, cycle=, date= so a literal grep -F matches). At dispatch, the coordinator greps the prompt for this stamp: present → the pre-dispatch review is already satisfied (skip re-review); absent → fall through to the normal pre-dispatch dual review (the stamp is a shortcut, not a hard dispatch requirement).

Common Mistakes

Too vague tasks: "Add validation" is not a step — if err := validate(input); err != nil { return fmt.Errorf(...) } is. Prefer complete code over pseudocode.

Too large tasks: If a task has more than 5 steps, split it. Each task = one focused session.

Missing dependencies: Forgetting cross-epic deps leads to agents starting work they can't finish. Always run bd blocked to verify.

Skipping worktree selection: Always ask the user which worktree to use. Check git worktree list and bd list --status=in_progress for idle worktrees before proposing new ones. Never silently assign worktrees.

Wrong base branch: The setup script defaults --base to main. Always pass --base thrum-dev explicitly since features branch from thrum-dev.

Generating prompts before worktree setup: Prompts embed the worktree path, branch, and agent name. These must be confirmed in Phase 3 before generating prompts in Phase 4.

Skipping the plan file: This skill reads the plan file (from writing-plans) as primary input. If you only have a design doc, use writing-plans first to produce the plan.

Delegating prompt generation to sub-agents: The filled implementation prompt is the most critical artifact. Sub-agents take shortcuts: they leave template meta-sections (## Inputs Required, ## Purpose) in the output, skip behavioral sections, fail to properly resolve placeholders, and produce prompts that confuse the implementation agent. Always generate prompts yourself in the main context.

Leaving template meta-sections in filled prompts: The ## Purpose and ## Inputs Required sections are documentation ABOUT the template, not instructions FOR the agent. Strip them. If they appear in the filled prompt, agents see {{PLACEHOLDER}} descriptions alongside already-resolved values, which is confusing and wasteful of context.

Using relative paths for gitignored files: Plan files, design docs, and prompts live in gitignored directories (dev-docs/, docs/plans/). Agents in worktrees can't see these via relative paths — the worktree only shares committed files. Always use absolute paths (starting with /) when referencing these files in: placeholder resolution, beads task descriptions, and the generated implementation prompt. This is the most common source of "file not found" errors for worktree agents.

Output Summary

When complete, you should have produced:

1. Beads epics and tasks with dependency DAG and TDD-quality descriptions
2. Ready-to-use worktrees with thrum/beads redirects and agents registered
3. Filled implementation prompts at dev-docs/prompts/{feature}.md
4. All artifacts committed to git

Handoff

After setup is complete, each epic is ready for an implementation agent. The filled prompt at dev-docs/prompts/{feature}.md is the session start prompt — give it directly to the implementing agent.

Implementer Status Reports

Implementation agents prefix every completion or escalation message with one of four status tokens defined in implementation-agent.md's Phase 4 Status Vocabulary. Your response depends on the token:

Token	Coordinator Response
DONE	Proceed to code review and merge for the epic's branch.
DONE_WITH_CONCERNS	Read the concerns before review. Address correctness/scope issues before merging; note architectural observations for follow-up. Do not merge blind.
NEEDS_CONTEXT	Answer the question, then re-dispatch the implementer with the missing context.
BLOCKED	Assess the blocker: context problem → re-dispatch with more context; task too large → split it; stronger reasoning needed → re-dispatch on a more capable model; plan wrong → escalate to the user. Never force the same model to retry without changes.

Never ignore a status escalation or silently re-dispatch. If the implementer reports BLOCKED or NEEDS_CONTEXT, something must change before retrying — provide missing context, split the task, switch models, or escalate.