beadboard/.agents/skills/create-beads-orchestration/templates/beads-workflow-injection.md

You MUST follow this worktree-per-task workflow for ALL implementation work. 1. **Parse task parameters from orchestrator:** - BEAD_ID: Your task ID (e.g., BD-001 for standalone, BD-001.2 for epic child) - EPIC_ID: (epic children only) The parent epic ID (e.g., BD-001)

2. Create worktree:

   REPO_ROOT=$(git rev-parse --show-toplevel)
   WORKTREE_PATH="$REPO_ROOT/.worktrees/bd-{BEAD_ID}"
   
   mkdir -p "$REPO_ROOT/.worktrees"
   if [[ ! -d "$WORKTREE_PATH" ]]; then
     git worktree add "$WORKTREE_PATH" -b bd-{BEAD_ID}
   fi
   
   cd "$WORKTREE_PATH"
   

3. Mark in progress:

   bd update {BEAD_ID} --status in_progress
   

4. Read bead comments for investigation context:

   bd show {BEAD_ID}
   bd comments {BEAD_ID}
   

5. If epic child: Read design doc:

   design_path=$(bd show {EPIC_ID} --json | jq -r '.[0].design // empty')
   # If design_path exists: Read and follow specifications exactly
   

6. Invoke discipline skill:

   Skill(skill: "subagents-discipline")
   

The orchestrator has investigated and logged findings to the bead.

Default behavior: Execute the fix confidently based on bead comments.

Only deviate if: You find clear evidence during implementation that the fix is wrong.

If the orchestrator's approach would break something, explain what you found and propose an alternative.

1. Work ONLY in your worktree: `.worktrees/bd-{BEAD_ID}/` 2. Commit frequently with descriptive messages 3. Log progress: `bd comment {BEAD_ID} "Completed X, working on Y"` WARNING: You will be BLOCKED if you skip any step. Execute ALL in order:

1. Commit all changes:

   git add -A && git commit -m "..."
   

2. Push to remote:

   git push origin bd-{BEAD_ID}
   

3. Log what you learned (REQUIRED - you will be blocked without this):

   bd comment {BEAD_ID} "LEARNED: [key technical insight from this task]"
   

   Record a convention, gotcha, or pattern you discovered. Examples:

   • "LEARNED: MenuBarExtra popup closes on NSWindow activate. Use activates:false."
   • "LEARNED: All source adapters must handle nil SUFeedURL gracefully."
   • "LEARNED: TaskGroup requires @Sendable closures in strict concurrency mode."

4. Leave completion comment:

   bd comment {BEAD_ID} "Completed: [summary]"
   

5. Mark status:

   bd update {BEAD_ID} --status inreview
   

6. Return completion report:

   BEAD {BEAD_ID} COMPLETE
   Worktree: .worktrees/bd-{BEAD_ID}
   Files: [names only]
   Tests: pass
   Summary: [1 sentence]
   

The SubagentStop hook verifies: worktree exists, no uncommitted changes, pushed to remote, bead status updated, LEARNED comment exists.

- Working directly on main branch - Implementing without BEAD_ID - Merging your own branch (user merges via PR) - Editing files outside your worktree