diff --git a/home/roles/development/skills/beads_implement.md b/home/roles/development/skills/beads_implement.md index e1e2a70..cbf4843 100644 --- a/home/roles/development/skills/beads_implement.md +++ b/home/roles/development/skills/beads_implement.md @@ -18,20 +18,49 @@ When this command is invoked: ``` Then check which have plans in `thoughts/beads-{id}/plan.md` -2. **Load bead and plan context**: +2. **Load bead context**: ```bash bd show {bead-id} ``` + Note the bead **type** (bug, feature, task) from the output. + +3. **Check for plan and handle by type**: + + Check if plan exists: + ```bash + ls thoughts/beads-{bead-id}/plan.md 2>/dev/null + ``` + + **If plan exists**: Proceed normally (skip to step 4) + + **If no plan**: + - **type=bug**: Proceed without plan (simple bugs can implement directly) + - **type=feature or type=task**: Warn and ask: + ``` + No plan found for this {type}. + + Plans help ensure complex work is well-designed and verifiable. + Location expected: thoughts/beads-{bead-id}/plan.md + + Options: + 1. Create a plan first (recommended) - Run /beads_plan {bead-id} + 2. Proceed without a plan (for simple changes) + + How would you like to proceed? + ``` + Wait for user response before continuing. + +4. **Load plan and research context** (if plan exists): - Read `thoughts/beads-{bead-id}/plan.md` FULLY - Check for any existing checkmarks (- [x]) indicating partial progress - Read any research at `thoughts/beads-{bead-id}/research.md` -3. **Mark bead in progress** (if not already): +5. **Mark bead in progress** (if not already): ```bash bd update {bead-id} --status=in_progress ``` -4. **Respond with**: +6. **Respond with**: ``` Implementing plan for bead {bead-id}: {bead-title} diff --git a/home/roles/development/skills/beads_workflow.md b/home/roles/development/skills/beads_workflow.md index 21017e1..b24fbbe 100644 --- a/home/roles/development/skills/beads_workflow.md +++ b/home/roles/development/skills/beads_workflow.md @@ -335,3 +335,53 @@ The `shared/` structure still works for non-bead artifacts, but prefer per-bead - Keep existing `thoughts/shared/` content - New bead-tracked work uses `thoughts/beads-{id}/` - Reference old research from bead descriptions when relevant + +## Design Decisions + +### Phase Tracking: Artifacts vs Statuses + +**Current approach**: Skills infer workflow phase from artifact presence: +- Has `research.md` → research done +- Has `plan.md` → planning done +- No artifacts → needs research/planning + +**Alternative considered**: Explicit phase statuses (`needs_research`, `needs_plan`, `implementing`, etc.) + +**Why artifacts win**: +1. **Single source of truth** - Status can't drift from reality +2. **Less state to maintain** - No need to update status when creating artifacts +3. **Works across repos** - No custom status config needed +4. **Skills already check artifacts** - Natural fit with existing behavior + +**When explicit statuses would help**: +- Pipeline visualization (e.g., `bd list --status=needs_plan`) +- Agent self-selection by phase +- Team coordination dashboards + +**Recommendation**: Keep artifact-inference as primary mechanism. If pipeline visibility becomes important, consider adding statuses that skills auto-set when creating artifacts (advisory, not enforced). + +### One Bead Per Feature (Default) + +**Current approach**: File one bead per logical feature. Skills handle phases internally. + +**Alternative considered**: Separate beads for research → planning → implementation, linked by dependencies. + +**Why single bead wins for most work**: +1. **Lower friction** - Quick idea dump without filing 3 tickets +2. **Simpler tracking** - One status to check +3. **Natural grouping** - Artifacts stay together in `thoughts/beads-{id}/` + +**When to split into multiple beads**: +- Research reveals the work should be multiple features +- Different phases need different assignees +- Explicit dependency tracking matters (e.g., "auth must ship before payments") + +**The discovered-work pattern**: Start with one bead. If research reveals split work, file additional beads with dependencies. Skills guide this naturally. + +### Plan Requirements by Type + +**Bug fixes** (`type=bug`): Can proceed without plans - usually well-scoped from bug report. + +**Features/tasks** (`type=feature`, `type=task`): Should have plans - helps ensure design is sound before implementation. + +This is advisory, not enforced. Skills warn but allow override for simple changes. diff --git a/home/roles/development/skills/parallel_beads.md b/home/roles/development/skills/parallel_beads.md index 56ae0a2..ab043e1 100644 --- a/home/roles/development/skills/parallel_beads.md +++ b/home/roles/development/skills/parallel_beads.md @@ -9,8 +9,29 @@ This skill orchestrates parallel bead processing using subagents. Each bead gets ## Phase 1: Selection 1. **Get ready beads**: Run `bd ready` to list all beads with no blockers -2. **Present selection**: Use `AskUserQuestion` with `multiSelect: true` to let the user choose which beads to work on + +2. **Filter by plan readiness**: + For each ready bead, check if it's ready for batch implementation: + - **Has plan** (`thoughts/beads-{id}/plan.md` exists): Include + - **type=bug** without plan: Include (simple bugs can implement directly) + - **type=feature/task** without plan: Exclude with warning + + ```bash + # Check for plan existence + ls thoughts/beads-{bead-id}/plan.md 2>/dev/null + ``` + +3. **Report skipped beads**: + If any beads were skipped, inform the user: + ``` + Skipped beads (no plan): + - {bead-id}: {title} (type: feature) - Run /beads_plan {bead-id} first + - {bead-id}: {title} (type: task) - Run /beads_plan {bead-id} first + ``` + +4. **Present selection**: Use `AskUserQuestion` with `multiSelect: true` to let the user choose which beads to work on - Include bead ID and title for each option + - Only show beads that passed the plan check - Allow selection of multiple beads Example: @@ -18,7 +39,7 @@ Example: AskUserQuestion with: - question: "Which beads do you want to work on in parallel?" - multiSelect: true -- options from bd ready output +- options from filtered bd ready output ``` ## Phase 2: Parallel Implementation