ai-workflow-init 6.6.1 → 7.1.0

package/docs/ai/planning/epic-template.md

@@ -3,153 +3,44 @@
 Note: All content in this document must be written in English.
 
 ---
-beads_epic: {bd-xxx or null}
 requirement: {docs/ai/requirements/req-xxx.md or null}
 ---
 
 ## 1. Overview
 
-### Problem Statement
-[Brief description of the problem this epic solves]
-
-### Goals
-- [Primary goal]
-- [Secondary goal]
-
-### Success Metrics
-- [How we measure success]
+[1-3 sentences: what this epic delivers and why it needs to be broken into multiple feature plans]
 
 ---
 
-## 2. Architecture
-
-> **Note**: High-level architecture overview. Detailed implementation goes in task-level plans.
-
-### System Diagram
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Component  │────▶│  Component  │────▶│  Component  │
-└─────────────┘     └─────────────┘     └─────────────┘
-```
+## 2. Feature Plans
 
-### Key Components
-| Component | Responsibility | Location |
-|-----------|----------------|----------|
-| {Name} | {What it does} | {path/to/} |
+| # | Feature Plan | Priority | Status | Description |
+|---|-------------|----------|--------|-------------|
+| 1 | [feature-{name}-part1.md](feature-{name}-part1.md) | P{0-4} | open | {Brief description} |
+| 2 | [feature-{name}-part2.md](feature-{name}-part2.md) | P{0-4} | open | {Brief description} |
 
-### Technology Decisions
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| {Area} | {Technology} | {Why this choice} |
+**Status values:** `open` | `in_progress` | `completed`
 
 ---
 
-## 3. Task Breakdown
+## 3. Dependency Graph
 
-> **Note**: If using Beads, this table syncs with Beads via `bd` commands. If not using Beads, manage tasks manually.
-
-| # | Task | Priority | Status | Blocked By | Plan Doc |
-|---|------|----------|--------|------------|----------|
-| 1 | {Task title} | P{0-4} | {open/in_progress/closed} | {dependencies or -} | {feature-xxx.md or -} |
-| 2 | {Task title} | P{0-4} | {status} | Task 1 | {-} |
-
-<!-- If using Beads, replace # with Task ID (e.g., bd-xxx.1) -->
-
-### Dependency Graph
 ```
-Task 1 ──────────────────────┐
-                             ▼
-Task 3 ───▶ Task 2 ───▶ Task 4
+Feature 1 ──────────────────┐
+                            ▼
+Feature 3 ───▶ Feature 2 ───▶ Feature 4
 ```
 
-<!-- If using Beads, replace Task # with bd-xxx.# -->
-
----
-
-## 4. Data Flow
-
-### Primary Flow: {Flow Name}
-1. [Step 1]: {description}
-2. [Step 2]: {description}
-3. [Step 3]: {description}
-
-### Alternative Flow: {Flow Name} (Optional)
-1. [Step 1]: {description}
-
-### Error Handling
-- {Error case}: {How it's handled}
-
----
-
-## 5. API Contracts (Optional)
-
-> **Note**: Include if epic involves API changes. Keep high-level; details in task plans.
-
-### Endpoints Overview
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | /api/v1/{resource} | {What it does} |
-| GET | /api/v1/{resource}/:id | {What it does} |
-
-### Key Data Models
-```
-{ModelName}:
-  - field1: type
-  - field2: type
-```
-
----
-
-## 6. Key Decisions & Trade-offs
-
-| Decision | Options Considered | Choice | Trade-off |
-|----------|-------------------|--------|-----------|
-| {Decision area} | {Option A, Option B} | {Chosen} | {What we gain/lose} |
-
----
-
-## 7. Risks & Mitigations
-
-| Risk | Impact | Probability | Mitigation |
-|------|--------|-------------|------------|
-| {Risk description} | High/Medium/Low | High/Medium/Low | {How to mitigate} |
-
----
-
-## 8. Dependencies
-
-### External
-- {External service/API}: {What we need from it}
-
-### Internal
-- {Internal service/team}: {What we need from it}
-
-### Blockers
-- [ ] {Blocker that must be resolved before starting}
-
----
-
-## 9. Milestones (Optional)
-
-> **Note**: Focus on task groupings and sequence, not time estimates.
-
-| Milestone | Tasks | Description |
-|-----------|-------|-------------|
-| {Milestone 1} | Task 1, Task 2 | {What this milestone delivers} |
-| {Milestone 2} | Task 3, Task 4 | {What this milestone delivers} |
-
 ---
 
-## 10. References
+## 4. Related Documents
 
-- **Requirement Doc**: [req-{name}.md](../requirements/req-{name}.md)
-- **Related Epics**: {links to related epic plans}
-- **External Docs**: {links to external resources}
+- **Requirement**: [req-{name}.md](../requirements/req-{name}.md)
 
 ---
 
 ## Changelog
 
-| Date | Author | Change |
-|------|--------|--------|
-| {YYYY-MM-DD} | {name} | Initial epic plan created |
+| Date | Change |
+|------|--------|
+| {YYYY-MM-DD} | Epic created |

package/docs/ai/planning/feature-template.md

@@ -3,27 +3,18 @@
 Note: All content in this document must be written in English.
 
 ---
-beads_task: {bd-xxx.n or null}
-beads_epic: {bd-xxx or null}
-epic_plan: {docs/ai/planning/epic-xxx.md or null}
+epic_plan: null
+requirement: null
 ---
 
-## 0. Beads Context (Optional)
+## 0. Related Documents (Optional — remove if no linked docs)
 
-> **Note**: This section is auto-generated when plan is created via `/beads-next` → `/create-plan` workflow. Delete if not using Beads.
+| Type | Document |
+|------|----------|
+| Requirement | [req-{name}.md](../requirements/req-{name}.md) |
+| Epic | [epic-{name}.md](epic-{name}.md) |
 
-- **Epic**: {epic-id} "{Epic Title}"
-- **Task**: {task-id} "{Task Title}"
-- **Epic Plan**: [epic-{name}.md](epic-{name}.md)
-- **Status**: in_progress
-- **Blocked by**: {list or "none"}
-- **Blocks**: {list of dependent tasks or "none"}
-
----
-
-## 0. Requirements Reference (Optional)
-
-- **Requirement Doc**: [req-{feature-name}.md](../requirements/req-{feature-name}.md)
+> **Note**: Remove this entire section if no requirement or epic is linked. This section is added by `/manage-epic` or `/create-plan` when context is provided.
 
 ---
 
@@ -277,30 +268,75 @@ epic_plan: {docs/ai/planning/epic-xxx.md or null}
 
 - [ ] [ACTION] path/to/file — Summary of change
   ```
-  Pseudo-code:
-  - Step 1: describe what will be done
-  - Step 2: validation or key logic
-  - Step 3: output or return value
+  Function: functionName(param1: type, param2: type) OR Endpoint: METHOD /path
+
+  Input validation:
+    - param1: [validation rules, constraints, format]
+    - param2: [validation rules, constraints, format]
+
+  Logic flow:
+    1. [Step with specific values/thresholds]
+    2. [Branching: if X then Y, else Z]
+    3. [External calls: DB queries, API calls with params]
+    4. [Data transformations with format]
+
+  Return: { field1: type, field2: type } | Error(code, message)
+
+  Edge cases:
+    - [Scenario] → [Handler/Response]
+    - [Error case] → [HTTP status + message OR error handling]
+
+  Dependencies: [Other functions/modules/APIs called]
   ```
 
 - [ ] [ACTION] path/to/file — Summary of change
   ```
-  Pseudo-code:
-  - ...
+  Function: ...
+
+  Input validation:
+    - ...
+
+  Logic flow:
+    1. ...
+
+  Return: ...
+
+  Edge cases:
+    - ...
+
+  Dependencies: ...
   ```
 
 ### Phase 2: [Phase Name]
 
 - [ ] [ACTION] path/to/file — Summary of change
   ```
-  Pseudo-code:
-  - ...
+  Function: ...
+
+  Input validation:
+    - ...
+
+  Logic flow:
+    1. ...
+
+  Return: ...
+
+  Edge cases:
+    - ...
+
+  Dependencies: ...
   ```
 
 Notes:
 - ACTION must be one of: ADDED | MODIFIED | DELETED | RENAMED
 - For MODIFIED files, use sub-bullets for each distinct logic change and include line ranges
-- Pseudo-code shows logic structure and key steps, not actual implementation code
+- Pseudo-code format uses structured sections for clarity:
+  - **Function/Endpoint**: Signature or route definition
+  - **Input validation**: All validation rules, data types, constraints
+  - **Logic flow**: Step-by-step with specific values, branches, external calls
+  - **Return**: Success response structure + error formats
+  - **Edge cases**: Error scenarios with handlers (HTTP status, messages, fallbacks)
+  - **Dependencies**: External modules, APIs, database tables
 - Each phase groups related tasks; phases execute sequentially
 - Use only one phase for small features (≤ 5 tasks); use multiple phases for larger features
 

package/docs/ai/requirements/req-template.md

@@ -240,4 +240,5 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 1. [ ] Review this requirement document
 2. [ ] Address open questions
-3. [ ] Run `/create-plan` to generate implementation plan
+3. [ ] Run `/create-plan` to generate implementation plan (small feature)
+4. [ ] Run `/manage-epic` to break into feature plans (large feature)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-init",
-  "version": "6.6.1",
+  "version": "7.1.0",
   "description": "Initialize AI workflow docs & commands into any repo with one command",
   "bin": {
     "ai-workflow-init": "./cli.js"

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

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