project-setup

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."

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 brainstorming 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 brainstorming 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 brainstorming skill first
• 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

Before starting, 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.

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.

Use sub-agents to explore the codebase in parallel:

# All launched in ONE message for parallel execution
Task(subagent_type="Explore", run_in_background=true,
  prompt="Explore {{PROJECT_ROOT}}. Map packages, interfaces, and patterns
  relevant to: {{FEATURE_DESCRIPTION}}.
  Write findings to output/planning/codebase-scan.md")

Task(subagent_type="general-purpose", model="haiku", run_in_background=true,
  prompt="Run: bd list --status=open, bd ready, bd blocked.
  Identify work related to {{FEATURE_DESCRIPTION}}.
  Write to output/planning/beads-context.md")

After agents complete, read the output files. Check bd list / bd ready / bd blocked for related or overlapping work.

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

Check for Implementation Philosophy Doc

After reading the plan and design doc, check if the project has an implementation philosophy doc — a file defining anti-patterns, red flags, and non-negotiable criteria:

1. Check if the design doc references a philosophy doc (look for "philosophy", "anti-patterns", "implementation standards" keywords)

2. Search for existing files:

   find . -name "*philosophy*" -o -name "*anti-pattern*" -o -name "*implementation-standards*" | head
   

3. If found: Read it and extract the key anti-patterns. These will be injected into each epic's prompt in Phase 4.

4. If not found: Offer to create one from the philosophy-template.md file in this skill's resources/ directory. Use AskUserQuestion to ask whether to create it now or skip.

This is the project's "rules of engagement" for implementation agents. Without it, agents can only verify "tests pass" — they can't verify architectural compliance.

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:

Task(subagent_type="general-purpose", model="haiku",
  prompt="Create these beads tasks under epic {{EPIC_1_ID}}:
  1. bd create --title='...' --type=task --priority=2 --description='...'
  2. bd create --title='...' --type=task --priority=1 --description='...'
  Then set ordering: bd dep add <later_id> <earlier_id>
  Return the created task IDs and their titles.")

Task(subagent_type="general-purpose", model="haiku",
  prompt="Create these beads tasks under epic {{EPIC_2_ID}}:
  ...")

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

# From the project root — MUST pass --base thrum-dev
./scripts/setup-worktree-thrum.sh \
  <worktree-path> <branch-name> \
  --identity <agent-name> --role implementer --base thrum-dev

The setup script handles: 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, generate the {{ANTI_PATTERNS}} content:

1. Read the design doc's Key Decisions section — extract decisions that constrain implementation (e.g., "full page reload, not HTMX", "real service calls, not hardcoded")
2. Read the philosophy doc's Anti-Patterns and Red Flags sections (identified in Phase 1)
3. Generate 3-5 epic-specific rules and red flags:
   • State what MUST happen (positive requirement)
   • State what MUST NOT happen (anti-pattern)
   • Make rules grep-able where possible (e.g., "grep for display:none")
4. Present the generated anti-patterns to the user for approval via AskUserQuestion before injecting into the prompt

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 from design doc + philosophy doc
{{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 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}}"

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.