ai-workflow-init 6.6.1 → 7.1.0

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

@@ -1,205 +0,0 @@
----
-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 |

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

@@ -1,248 +0,0 @@
----
-name: beads-done
-description: Closes current task, syncs to git, clears context, and shows next ready tasks.
----
-
-## Goal
-
-Mark the current Beads task as complete, sync changes to git, clear the task context, and show what tasks are now ready (including any that were unblocked).
-
-## Workflow Alignment
-
-- Provide brief status updates (1–3 sentences) before/after important actions.
-- Confirm before closing if there are uncommitted changes.
-- Always sync to git after closing.
-
----
-
-## Step 1: Load Current Task Context
-
-**Read:** `.beads/current-task.json`
-
-If exists:
-- Extract task_id, task_title, epic_id
-- Proceed to Step 2
-
-If not exists:
-- Ask user which task to close
-
-```
-AskUserQuestion(questions=[{
-  question: "No active task context found. Which task would you like to close?",
-  header: "Close Task",
-  options: [
-    { label: "Enter task ID", description: "e.g., bd-auth.1" },
-    { label: "Show in-progress tasks", description: "List tasks I'm working on" },
-    { label: "Cancel", description: "Don't close anything" }
-  ],
-  multiSelect: false
-}])
-```
-
-If "Show in-progress tasks":
-- Run: `bd list --status=in_progress`
-- Display list and ask user to select
-
----
-
-## Step 2: Pre-Close Checks
-
-### 2a: Check Git Status
-
-**Run:** `git status --porcelain`
-
-If uncommitted changes exist:
-
-```
-⚠️ Uncommitted changes detected:
-
-{list of modified/added files}
-
-These changes should be committed before closing the task.
-```
-
-```
-AskUserQuestion(questions=[{
-  question: "You have uncommitted changes. How would you like to proceed?",
-  header: "Git Status",
-  options: [
-    { label: "Commit changes first", description: "I'll commit, then run /beads-done again" },
-    { label: "Close anyway", description: "Close task without committing (changes will remain staged)" },
-    { label: "Cancel", description: "Don't close the task yet" }
-  ],
-  multiSelect: false
-}])
-```
-
-If "Commit changes first": Exit and let user commit.
-If "Cancel": Exit without closing.
-If "Close anyway": Proceed to Step 3.
-
-### 2b: Check Planning Doc Status
-
-**Read task details:** `bd show {task-id} --json`
-
-Check if plan doc exists (from notes or known path).
-
-If plan doc exists:
-- Read planning doc
-- Check if all phases are complete (all `[x]` checkboxes)
-- If incomplete phases exist, warn user:
-
-```
-⚠️ Planning doc has incomplete tasks:
-
-Phase 2: API Implementation
-  - [ ] Task 3: Incomplete
-  - [ ] Task 4: Incomplete
-
-Are you sure you want to close this task?
-```
-
-```
-AskUserQuestion(questions=[{
-  question: "Planning doc has incomplete tasks. Close anyway?",
-  header: "Incomplete",
-  options: [
-    { label: "Close anyway", description: "Mark task as complete despite incomplete plan items" },
-    { label: "Cancel", description: "Keep task open and finish the work" }
-  ],
-  multiSelect: false
-}])
-```
-
----
-
-## Step 3: Close Task
-
-### 3a: Ask for Close Reason (optional)
-
-```
-AskUserQuestion(questions=[{
-  question: "Add a closing note? (optional)",
-  header: "Close Note",
-  options: [
-    { label: "Completed successfully", description: "Task finished as planned" },
-    { label: "Completed with modifications", description: "Finished but deviated from original plan" },
-    { label: "Custom note", description: "Enter a custom closing note" },
-    { label: "No note", description: "Close without a note" }
-  ],
-  multiSelect: false
-}])
-```
-
-### 3b: Execute Close
-
-**Run:** `bd close {task-id} --reason "{close reason}"`
-
-Capture output for confirmation.
-
----
-
-## Step 4: Update Epic Plan (if exists)
-
-**Read:** `.beads/current-epic.json`
-
-If epic_plan exists:
-- Read epic plan file
-- Update Task Breakdown table:
-  - Change status from `in_progress` to `closed`
-  - Add plan doc path if created
-
-**Edit:** `docs/ai/planning/epic-{name}.md`
-
-Update the task row:
-```markdown
-| {task-id} | {title} | P{n} | closed | - | feature-{name}.md |
-```
-
----
-
-## Step 5: Sync to Git
-
-**Run:** `bd sync`
-
-This will:
-- Export Beads changes to JSONL
-- Commit Beads changes
-- Push to remote
-
-Display sync result.
-
----
-
-## Step 6: Clear Context
-
-**Delete:** `.beads/current-task.json`
-
-Context is cleared so `/create-plan` won't auto-link to this closed task.
-
----
-
-## Step 7: Show Next Ready Tasks
-
-**Run:** `bd ready --json`
-
-Check if any tasks were unblocked by closing this task.
-
-**Output:**
-
-```
-✓ Closed: {task-id} "{Task Title}"
-✓ Synced to git
-
-{If tasks were unblocked:}
-🔓 Unblocked by this completion:
-  - {unblocked-task-id} "{title}" [now ready]
-  - {unblocked-task-id} "{title}" [now ready]
-
-{Show ready tasks:}
-📋 Ready to work ({count}):
-  1. {task-id} "{title}" (P{n})
-  2. {task-id} "{title}" (P{n})
-
-{Show epic progress:}
-📊 Epic Progress: {epic-id}
-  Completed: {closed}/{total} tasks ({percentage}%)
-  Remaining: {open + in_progress} tasks
-
-Next steps:
-  - Run `/beads-next` to claim next task
-  - Run `/beads-status` to see full epic progress
-```
-
-**If all tasks in epic are complete:**
-
-```
-🎉 Epic Complete: {epic-id} "{Epic Title}"
-
-All {total} tasks have been completed!
-
-Next steps:
-  - Review epic plan for any follow-ups
-  - Close epic: `bd close {epic-id} --reason "All tasks complete"`
-  - Start new work: `/beads-breakdown`
-```
-
----
-
-## Notes
-
-- **Git sync required**: Always syncs to git after closing to persist state
-- **Context cleanup**: Clears current-task.json to prevent stale context
-- **Epic progress**: Shows progress after each task completion
-- **Unblocked tasks**: Highlights tasks that became ready after this completion
-
-### Close vs Cancel
-
-| Action | When to use |
-|--------|-------------|
-| Close (this command) | Task is complete, work is done |
-| Cancel (`bd update --status open`) | Task is abandoned, need to unclaim |
-
-### Error Recovery
-
-If close fails:
-- Check `bd doctor` for sync issues
-- Manually run `bd sync` to retry
-- Check git status for conflicts

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

@@ -1,260 +0,0 @@
----
-name: beads-next
-description: Shows ready tasks, allows claiming a task, and sets context for /create-plan.
----
-
-## Goal
-
-Show available Beads tasks (in_progress and ready), let user claim a task, and set context so `/create-plan` knows which Beads task to link.
-
-## Workflow Alignment
-
-- Provide brief status updates (1–3 sentences) before/after important actions.
-- Always show in_progress tasks first (user may have work in progress from previous session).
-- Set context file for seamless integration with `/create-plan`.
-
----
-
-## Step 1: Check Current State
-
-### 1a: Load Epic Context (if exists)
-
-**Read:** `.beads/current-epic.json`
-
-If exists:
-- Use epic_id to filter tasks
-- Show only tasks from current epic
-
-If not exists:
-- Show all tasks across all epics
-
-### 1b: Get In-Progress Tasks
-
-**Run:** `bd list --status=in_progress --json`
-
-Parse output to get tasks currently being worked on.
-
-### 1c: Get Ready Tasks
-
-**Run:** `bd ready --json`
-
-Parse output to get tasks with no blockers.
-
----
-
-## Step 2: Display Task Overview
-
-**Format output:**
-
-```
-## Beads Task Overview
-
-{If epic context exists:}
-**Current Epic**: {epic-id} "{Epic Title}"
-**Epic Plan**: {epic-plan path or "Not created yet"}
-
----
-
-### 🔄 In Progress ({count})
-
-{If in_progress tasks exist:}
-| Task ID | Title | Epic | Plan Doc |
-|---------|-------|------|----------|
-| {task-id} | {title} | {epic-id} | {plan path or "-"} |
-
-{If no in_progress:}
-No tasks in progress.
-
----
-
-### ✅ Ready to Start ({count})
-
-{If ready tasks exist:}
-| # | Task ID | Title | Priority | Epic |
-|---|---------|-------|----------|------|
-| 1 | {task-id} | {title} | P{n} | {epic-id} |
-| 2 | {task-id} | {title} | P{n} | {epic-id} |
-| 3 | {task-id} | {title} | P{n} | {epic-id} |
-
-{If no ready tasks:}
-No tasks ready. Check blocked tasks with `bd blocked`.
-
----
-
-### 🚫 Blocked ({count})
-
-{task-id}: blocked by {blocker-id} "{blocker-title}"
-```
-
----
-
-## Step 3: Ask User Action
-
-**If in_progress tasks exist:**
-
-```
-AskUserQuestion(questions=[{
-  question: "You have tasks in progress. What would you like to do?",
-  header: "Action",
-  options: [
-    { label: "Continue {task-id}", description: "Resume working on '{task-title}'" },
-    { label: "Claim new task", description: "Pick a different task from ready list" },
-    { label: "View task details", description: "Show full details of a specific task" }
-  ],
-  multiSelect: false
-}])
-```
-
-**If no in_progress, but ready tasks exist:**
-
-```
-AskUserQuestion(questions=[{
-  question: "Which task would you like to claim?",
-  header: "Claim Task",
-  options: [
-    { label: "{task-1-id}: {title}", description: "Priority: P{n}" },
-    { label: "{task-2-id}: {title}", description: "Priority: P{n}" },
-    { label: "{task-3-id}: {title}", description: "Priority: P{n}" },
-    { label: "View details first", description: "Show full details before claiming" }
-  ],
-  multiSelect: false
-}])
-```
-
-**If no tasks available:**
-
-```
-No tasks available to work on.
-
-Options:
-  - Run `bd blocked` to see what's blocking tasks
-  - Run `/beads-breakdown` to create new tasks
-  - Run `bd list` to see all tasks
-```
-
----
-
-## Step 4: Handle User Selection
-
-### If "Continue {task-id}" (resume in_progress):
-
-1. Load task details: `bd show {task-id} --json`
-2. Check if plan doc exists (from notes or epic plan table)
-3. Set context file (Step 5)
-4. Output next steps
-
-### If user selects a ready task to claim:
-
-1. **Claim task:**
-   ```bash
-   bd update {task-id} --status in_progress
-   ```
-
-2. **Load task details:** `bd show {task-id} --json`
-
-3. **Set context file** (Step 5)
-
-4. **Output confirmation:**
-   ```
-   ✓ Claimed: {task-id} "{Task Title}"
-
-   Task Details:
-     Priority: P{n}
-     Epic: {epic-id}
-     Blocked by: {none or list}
-     Blocks: {list of dependent tasks}
-
-   Next steps:
-     1. Run `/create-plan` to create detailed implementation plan
-     2. After planning, run `/execute-plan` to implement
-   ```
-
-### If "View details first":
-
-```
-AskUserQuestion(questions=[{
-  question: "Which task details would you like to see?",
-  header: "View Task",
-  options: [
-    { label: "{task-1-id}", description: "{title}" },
-    { label: "{task-2-id}", description: "{title}" },
-    { label: "{task-3-id}", description: "{title}" }
-  ],
-  multiSelect: false
-}])
-```
-
-Then run: `bd show {selected-task-id}`
-
-Display full details and return to Step 3 for claiming.
-
----
-
-## Step 5: Set Context for /create-plan
-
-**Create/Update:** `.beads/current-task.json`
-
-```json
-{
-  "task_id": "{task-id}",
-  "task_title": "{Task Title}",
-  "epic_id": "{epic-id}",
-  "epic_title": "{Epic Title}",
-  "epic_plan": "{docs/ai/planning/epic-xxx.md or null}",
-  "priority": {priority number},
-  "blocked_by": [],
-  "blocks": ["{dependent-task-ids}"],
-  "claimed_at": "{ISO timestamp}"
-}
-```
-
-This file is read by `/create-plan` to:
-- Auto-populate beads metadata in frontmatter
-- Reference epic plan for architecture context
-- Link task to plan doc when created
-
----
-
-## Step 6: Final Output
-
-```
-✓ Context set for: {task-id} "{Task Title}"
-
-Ready for:
-  /create-plan              → Create detailed implementation plan
-  /create-plan "{title}"    → Create plan with custom title
-
-To view task details anytime:
-  bd show {task-id}
-
-To unclaim this task:
-  bd update {task-id} --status open
-```
-
----
-
-## Notes
-
-- **Session persistence**: Context file (`.beads/current-task.json`) persists across sessions
-- **One task at a time**: Only one task should be in_progress per developer
-- **Epic filtering**: If working on an epic, only shows tasks from that epic
-- **Parallel work**: Multiple developers can claim different tasks (Beads handles this)
-
-### Task Status Flow
-
-```
-open → in_progress → closed
-         ↓
-       (unclaim)
-         ↓
-        open
-```
-
-### Context File Lifecycle
-
-```
-/beads-next (claim)     → Creates .beads/current-task.json
-/create-plan            → Reads context, links plan doc
-/execute-plan           → Uses plan doc (context optional)
-/beads-done             → Deletes .beads/current-task.json
-```