feat(skills): Add plan-awareness to bead workflow skills

- parallel_beads: Filter beads by plan readiness before selection
  - Include beads with plans or type=bug
  - Warn about skipped beads that need plans first
- beads_implement: Check for plan based on bead type
  - Bugs can proceed without plans
  - Features/tasks warn and ask user preference
- beads_workflow: Document design decisions
  - Artifacts vs statuses for phase tracking
  - One bead per feature as default
  - Discovered-work pattern for splitting work

Closes: nixos-configs-45r, nixos-configs-8gr, nixos-configs-oog, nixos-configs-505

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-01-12 18:39:51 -08:00
parent ba4922981b
commit b6e9de0f61
3 changed files with 105 additions and 5 deletions

View File

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