ai-workflow-init 6.4.2 → 6.6.0

package/.claude/commands/beads-breakdown.md

@@ -0,0 +1,278 @@
+---
+name: beads-breakdown
+description: Analyzes feature/requirement and breaks down into Beads epic with tasks and dependencies.
+---
+
+## Goal
+
+Analyze a feature description (user prompt, requirement file, or planning file) and break it down into a Beads epic with tasks and dependencies. Confirm with user before executing any `bd` commands.
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- ALWAYS confirm breakdown with user before executing `bd` commands.
+- Show exact commands that will be executed for transparency.
+
+---
+
+## Step 1: Detect Input Source
+
+**Parse user input to identify source type:**
+
+1. **File reference detected** (starts with `@` or file path):
+   - Requirement file: `@docs/ai/requirements/req-{name}.md`
+   - Planning file: `@docs/ai/planning/feature-{name}.md`
+   - Read file and extract content
+
+2. **User prompt only**:
+   - Use prompt directly for analysis
+
+3. **Both file + prompt**:
+   - File provides base requirements
+   - Prompt provides additional context/focus
+
+**Tool:** Read(file_path=...) if file reference detected
+
+**Extract from file (if requirement doc):**
+- Problem Statement → Epic description
+- Functional Requirements (FR-xx) → Tasks
+- Non-Functional Requirements → Constraints/notes
+- Dependencies/Constraints → Task dependencies
+- Acceptance Criteria → Task acceptance criteria
+
+**Extract from file (if planning doc):**
+- Goal → Epic description
+- Implementation phases → Tasks
+- Phase dependencies → Task dependencies
+
+---
+
+## Step 2: Analyze and Generate Breakdown
+
+**Generate epic structure:**
+
+1. **Epic title**: Concise name for the feature (e.g., "User Authentication System")
+
+2. **Tasks**: Break down into 3-10 tasks
+   - Each task should be independently plannable (1-3 phases when detailed)
+   - Task title: Action-oriented (e.g., "Setup JWT infrastructure")
+   - Priority: P0 (critical) to P4 (backlog)
+
+3. **Dependencies**: Identify blocking relationships
+   - Which tasks must complete before others can start?
+   - Which tasks can run in parallel?
+
+**Analysis guidelines:**
+- **Too granular**: If task takes < 1 hour → merge with related task
+- **Too large**: If task needs > 5 implementation phases → split further
+- **Parallel-friendly**: Maximize tasks that can run simultaneously
+
+---
+
+## Step 3: Present Breakdown for Confirmation
+
+**Display proposed breakdown:**
+
+```
+## Proposed Epic Breakdown
+
+**Epic**: {Epic Title}
+**Source**: {file path or "user prompt"}
+**Description**: {1-2 sentence summary}
+
+### Tasks
+
+| # | Title | Priority | Blocked By | Notes |
+|---|-------|----------|------------|-------|
+| 1 | {Task title} | P{0-4} | - | {brief note} |
+| 2 | {Task title} | P{0-4} | Task 1 | {brief note} |
+| 3 | {Task title} | P{0-4} | - | {can parallel with 1} |
+| 4 | {Task title} | P{0-4} | Task 2 | {brief note} |
+
+### Dependency Graph
+
+```
+Task 1 ──────────────────────┐
+                             ▼
+Task 3 ───▶ Task 2 ───▶ Task 4
+```
+
+### Ready to Start (can run in parallel)
+- Task 1: {title}
+- Task 3: {title}
+
+---
+
+### Commands to Execute
+
+```bash
+# Create Epic
+bd create "{Epic Title}" -p 0 --type epic
+
+# Create Tasks (after epic created, will use actual epic ID)
+bd create "{Task 1 title}" -p {priority} --parent {epic-id}
+bd create "{Task 2 title}" -p {priority} --parent {epic-id}
+bd create "{Task 3 title}" -p {priority} --parent {epic-id}
+bd create "{Task 4 title}" -p {priority} --parent {epic-id}
+
+# Set Dependencies
+bd dep add {task-2-id} {task-1-id}  # Task 2 blocked by Task 1
+bd dep add {task-4-id} {task-2-id}  # Task 4 blocked by Task 2
+
+# Sync to git
+bd sync
+```
+```
+
+**Ask for confirmation:**
+
+```
+AskUserQuestion(questions=[{
+  question: "Review the breakdown above. How would you like to proceed?",
+  header: "Confirm",
+  options: [
+    { label: "Execute breakdown", description: "Create epic and tasks in Beads with the structure shown above" },
+    { label: "Modify tasks", description: "I want to add, remove, or change tasks before creating" },
+    { label: "Cancel", description: "Don't create anything, I'll provide more context" }
+  ],
+  multiSelect: false
+}])
+```
+
+---
+
+## Step 4: Handle User Response
+
+### If "Execute breakdown":
+
+Execute `bd` commands sequentially:
+
+```bash
+# 1. Create Epic
+bd create "{Epic Title}" -p 0 --type epic
+# Capture epic ID from output (e.g., bd-auth)
+
+# 2. Create Tasks (use actual epic ID)
+bd create "{Task 1}" -p {priority} --parent {epic-id}
+# Capture task ID (e.g., bd-auth.1)
+
+bd create "{Task 2}" -p {priority} --parent {epic-id}
+# Capture task ID (e.g., bd-auth.2)
+
+# ... repeat for all tasks
+
+# 3. Set Dependencies (use actual task IDs)
+bd dep add {task-2-id} {task-1-id}
+# ... repeat for all dependencies
+
+# 4. Sync
+bd sync
+```
+
+**Output summary:**
+
+```
+✓ Created Epic: {epic-id} "{Epic Title}"
+
+Tasks created:
+  ├── {task-1-id} "{Task 1}" [ready]
+  ├── {task-2-id} "{Task 2}" [blocked by {task-1-id}]
+  ├── {task-3-id} "{Task 3}" [ready]
+  └── {task-4-id} "{Task 4}" [blocked by {task-2-id}]
+
+Ready to start (parallel): {task-1-id}, {task-3-id}
+
+Next steps:
+  1. Run `/beads-create-epic-plan` to create high-level epic plan
+  2. Run `/beads-next` to claim a task and start working
+```
+
+### If "Modify tasks":
+
+Ask follow-up:
+
+```
+AskUserQuestion(questions=[{
+  question: "What would you like to modify?",
+  header: "Modify",
+  options: [
+    { label: "Add tasks", description: "Add more tasks to the breakdown" },
+    { label: "Remove tasks", description: "Remove some tasks" },
+    { label: "Change dependencies", description: "Modify blocking relationships" },
+    { label: "Change priorities", description: "Adjust task priorities" }
+  ],
+  multiSelect: true
+}])
+```
+
+Collect modifications and return to Step 3 with updated breakdown.
+
+### If "Cancel":
+
+```
+Breakdown cancelled.
+
+To try again with more context:
+  /beads-breakdown "more detailed description"
+  /beads-breakdown @docs/ai/requirements/req-{name}.md
+```
+
+---
+
+## Step 5: Store Context for Next Commands
+
+After successful creation, store context for `/beads-create-epic-plan`:
+
+**File:** `.beads/current-epic.json`
+
+```json
+{
+  "epic_id": "{epic-id}",
+  "epic_title": "{Epic Title}",
+  "source_file": "{file path or null}",
+  "tasks": [
+    {
+      "id": "{task-1-id}",
+      "title": "{Task 1}",
+      "priority": 1,
+      "blocked_by": [],
+      "status": "open"
+    },
+    {
+      "id": "{task-2-id}",
+      "title": "{Task 2}",
+      "priority": 1,
+      "blocked_by": ["{task-1-id}"],
+      "status": "open"
+    }
+  ],
+  "created_at": "{ISO timestamp}"
+}
+```
+
+---
+
+## Notes
+
+- **Confirmation required**: Never execute `bd` commands without user confirmation
+- **Idempotent**: Safe to re-run; will show current state if epic exists
+- **Source tracking**: Links back to requirement/planning doc if provided
+- **Parallel-friendly**: Breakdown should maximize parallel execution opportunities
+
+### Task Sizing Guidelines
+
+| Size | Description | When to use |
+|------|-------------|-------------|
+| Too small | < 1 hour, single function | Merge with related task |
+| Good | 2-8 hours, 1-3 phases | Ideal task size |
+| Too large | > 2 days, > 5 phases | Split into subtasks |
+
+### Priority Guidelines
+
+| Priority | Meaning | Use for |
+|----------|---------|---------|
+| P0 | Critical | Blockers, urgent fixes |
+| P1 | High | Core functionality |
+| P2 | Medium | Important but not blocking |
+| P3 | Low | Nice to have |
+| P4 | Backlog | Future consideration |

package/.claude/commands/beads-create-epic-plan.md

@@ -0,0 +1,205 @@
+---
+name: beads-create-epic-plan
+description: Creates a high-level epic plan document for architecture, flow, and task overview.
+---
+
+## Goal
+
+Create a high-level epic plan document (`docs/ai/planning/epic-{name}.md`) that focuses on architecture, data flow, and task overview. This plan is NOT executable - it serves as a reference for task-level plans.
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- Generate plan automatically after gathering context.
+- Link to Beads epic and requirement doc if available.
+
+---
+
+## Step 1: Load Context
+
+### 1a: Check for Current Epic Context
+
+**Read:** `.beads/current-epic.json` (created by `/beads-breakdown`)
+
+If exists:
+- Extract epic_id, epic_title, source_file, tasks
+- Use as primary context
+
+If not exists:
+- Ask user for epic ID or title
+
+```
+AskUserQuestion(questions=[{
+  question: "Which epic would you like to create a plan for?",
+  header: "Epic",
+  options: [
+    { label: "Enter epic ID", description: "e.g., bd-auth or project-abc" },
+    { label: "Enter epic title", description: "I'll search for it in Beads" }
+  ],
+  multiSelect: false
+}])
+```
+
+Then run: `bd list --type epic` to find matching epic
+
+### 1b: Load Epic Details from Beads
+
+**Run:** `bd show {epic-id} --json`
+
+Extract:
+- Epic title, description
+- Child tasks (IDs, titles, priorities, dependencies)
+- Current status
+
+### 1c: Load Requirement Doc (if linked)
+
+If `source_file` exists in context:
+- Read requirement doc
+- Extract architecture hints, constraints, acceptance criteria
+
+### 1d: Explore Codebase (optional)
+
+**Tool:** Task(
+  subagent_type='Explore',
+  thoroughness='quick',
+  prompt="Identify existing architecture patterns relevant to {epic title}. Find similar features, common patterns, and key integration points. Return summarized findings."
+)
+
+---
+
+## Step 2: Generate Epic Plan
+
+**Load template:** Read `docs/ai/planning/epic-template.md`
+
+**Auto-derive epic name:**
+- From epic title: "User Authentication System" → `epic-auth-system`
+- Kebab-case, concise
+
+**Generate content sections:**
+
+### Section 1: Overview
+- Problem statement from requirement doc or infer from epic title
+- Goals from epic description
+- Success metrics (derive from acceptance criteria if available)
+
+### Section 2: Architecture
+- Propose high-level architecture based on:
+  - Codebase exploration findings
+  - Similar features in codebase
+  - Standard patterns for this type of feature
+- Keep diagram simple (ASCII art)
+- List key components and their responsibilities
+
+### Section 3: Task Breakdown
+- Pull from Beads (via `bd show {epic-id}`)
+- Include: task ID, title, priority, status, blocked by
+- Show dependency graph
+- Leave "Plan Doc" column empty (filled when `/create-plan` runs)
+
+### Section 4: Data Flow
+- Describe primary user/data flow
+- Include error handling flow
+- Keep high-level (details go in task plans)
+
+### Section 5: API Contracts (if applicable)
+- Only if epic involves API changes
+- High-level endpoints overview
+- Key data models (schema outline)
+
+### Section 6: Key Decisions
+- Document major architectural decisions
+- Include alternatives considered and trade-offs
+
+### Section 7: Risks & Mitigations
+- Technical risks
+- Dependency risks
+- Timeline risks
+
+### Section 8: Dependencies
+- External services/APIs
+- Internal teams/services
+- Blockers that must be resolved
+
+---
+
+## Step 3: Create Epic Plan File
+
+**File path:** `docs/ai/planning/epic-{name}.md`
+
+**Frontmatter:**
+```yaml
+---
+beads_epic: {epic-id}
+requirement: {source_file or null}
+---
+```
+
+**If file already exists:**
+1. Backup to: `docs/ai/planning/archive/epic-{name}_{timestamp}.md`
+2. Notify user: "Previous version backed up to archive/"
+3. Overwrite main file
+
+**Write file:** Write(file_path=..., content=...)
+
+---
+
+## Step 4: Update Context File
+
+**Update:** `.beads/current-epic.json`
+
+Add:
+```json
+{
+  "epic_plan": "docs/ai/planning/epic-{name}.md",
+  "updated_at": "{ISO timestamp}"
+}
+```
+
+---
+
+## Step 5: Output Summary
+
+```
+✓ Created epic plan: docs/ai/planning/epic-{name}.md
+
+Epic: {epic-id} "{Epic Title}"
+Tasks: {count} ({ready} ready, {blocked} blocked)
+
+Sections created:
+  ✓ Overview
+  ✓ Architecture
+  ✓ Task Breakdown ({task count} tasks)
+  ✓ Data Flow
+  {✓ API Contracts (if included)}
+  ✓ Key Decisions
+  ✓ Risks & Mitigations
+  ✓ Dependencies
+
+Next steps:
+  1. Review and refine the epic plan
+  2. Run `/beads-next` to claim a task
+  3. Run `/create-plan` to create detailed plan for the claimed task
+```
+
+---
+
+## Notes
+
+- **High-level only**: Epic plan focuses on architecture and overview, NOT implementation details
+- **Not executable**: Use `/execute-plan` only on task-level plans (feature-*.md)
+- **Reference document**: Task plans reference this for architectural context
+- **Sync with Beads**: Task breakdown table should match Beads state
+- **Update manually**: Architecture decisions and risks should be updated as epic progresses
+
+### What Goes Where
+
+| Content | Epic Plan | Task Plan |
+|---------|-----------|-----------|
+| Architecture overview | ✓ | Reference only |
+| Data flow diagrams | ✓ | Detailed flow if needed |
+| Task list & dependencies | ✓ | Single task focus |
+| API contracts (overview) | ✓ | Detailed specs |
+| Implementation phases | ✗ | ✓ |
+| Pseudo-code | ✗ | ✓ |
+| File-level changes | ✗ | ✓ |
+| Acceptance criteria | High-level | Detailed per task |