ai-workflow-init 6.6.1 → 7.1.0

package/.claude/commands/clarify-requirements.md

@@ -405,8 +405,9 @@ Create `docs/ai/requirements/req-{name}.md` with:
 ## Next Steps
 
 1. Review this requirement document
-2. Run `/create-plan req-{name}` to generate implementation plan
-3. Address open questions before implementation
+2. Address open questions before implementation
+3. Run `/create-plan` to generate implementation plan (small feature)
+4. Run `/manage-epic` to break into feature plans (large feature)
 ```
 
 ### File Naming & Versioning
@@ -457,8 +458,9 @@ AskUserQuestion(questions=[{
   question: "What would you like to do next?",
   header: "Next",
   options: [
+    { label: "Create plan (small feature)", description: "Run /create-plan — single feature plan" },
+    { label: "Create epic (large feature)", description: "Run /manage-epic — break into multiple feature plans" },
     { label: "View full document", description: "Display the consolidated requirement" },
-    { label: "Create plan", description: "Run /create-plan for this requirement" },
     { label: "Continue refining", description: "Run more Q&A or agent passes" }
   ],
   multiSelect: false

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

@@ -15,51 +15,11 @@ Generate a single planning doc at `docs/ai/planning/feature-{name}.md` using the
 
 ---
 
-## Step 0: Check Beads Context (Optional Integration)
-
-> **Purpose**: Detect if this plan is for a Beads task. If so, link to epic and inherit context.
-
-**Read:** `.beads/current-task.json`
-
-**If file exists (Beads workflow active):**
-
-```json
-{
-  "task_id": "bd-auth.1",
-  "task_title": "Setup JWT infrastructure",
-  "epic_id": "bd-auth",
-  "epic_title": "User Authentication System",
-  "epic_plan": "docs/ai/planning/epic-auth-system.md"
-}
-```
-
-Set internal flags:
-- `BEADS_MODE = true`
-- `beads_task = task_id`
-- `beads_epic = epic_id`
-- `suggested_title = task_title`
-- `epic_plan_path = epic_plan`
-
-**If epic_plan exists:**
-- Read epic plan for architecture context
-- Extract relevant sections:
-  - Architecture overview (for codebase context)
-  - Key decisions (for constraints)
-  - Data flow (for understanding)
-- Use as additional context in Step 3 (Explore)
-
-**If file does not exist:**
-- `BEADS_MODE = false`
-- Proceed with normal workflow (no Beads integration)
-
-**Output:** Internal state set. No user-visible output for this step.
-
----
-
 ## Step 1: Analyze User Prompt
 
 **Parse user request to identify:**
 - **Requirement doc reference:** Check if user provided path to `docs/ai/requirements/req-{name}.md`
+- **Epic reference:** Check if user provided path to `docs/ai/planning/epic-{name}.md`
 - **Feature type:** UI/Page, API/Service, Data/Database, Full-stack, Other
 - **Explicit requirements:** Framework, libraries, constraints mentioned
 - **Design context:**
@@ -68,6 +28,13 @@ Set internal flags:
   - No design source? → Flag for Step 5 (theme selection)
 - **Scope hints:** MVP mentions, deadlines, specific exclusions
 
+**If Epic Reference Provided:**
+- Read the epic doc: `Read(file_path="docs/ai/planning/epic-{name}.md")`
+- Extract: requirement link, feature plan list, which plan to create next
+- Read the linked requirement doc (from epic's `requirement` frontmatter)
+- Set `epic_plan` and `requirement` frontmatter in the generated feature plan
+- After creating the feature plan, update the epic's Feature Plans table (status → `open`)
+
 **If Requirement Doc Provided:**
 - Read the requirement doc: `Read(file_path="docs/ai/requirements/req-{name}.md")`
 - Extract and map to planning sections:
@@ -285,8 +252,11 @@ Produce a Markdown doc following `docs/ai/planning/feature-template.md`.
    - Epic ID and title
    - Link to epic plan
 
-0. **Requirements Reference** (if requirement doc was provided):
-   - Link to requirement doc: `[req-{name}.md](../requirements/req-{name}.md)`
+0. **Related Documents** (ONLY if requirement doc or epic was provided — skip entirely if neither exists):
+   - Link to requirement doc: `[req-{name}.md](../requirements/req-{name}.md)` (if exists)
+   - Link to epic: `[epic-{name}.md](epic-{name}.md)` (if exists)
+   - Set `epic_plan` and `requirement` in frontmatter accordingly
+   - If standalone (no req, no epic): set both frontmatter to null and **omit this section**
 
 1. **Codebase Context** (if exploration was done):
    - Similar features found
@@ -327,50 +297,65 @@ Produce a Markdown doc following `docs/ai/planning/feature-template.md`.
 **For each phase:**
 - Phase name: Descriptive (e.g., "API Endpoints", "UI Components")
 - Tasks list: `[ ] [ACTION] path/to/file — Summary`
-- Pseudo-code: 3-5 lines, natural language, show inputs → logic → outputs
+- Pseudo-code: Structured format with these sections:
   ```
   Example:
-  - Parse username + password from request
-  - Validate password strength → Hash with bcrypt
-  - Store user in database → Return success + user ID
+  Function: POST /api/auth/register(email, password, name)
+
+  Input validation:
+    - email: Valid format (regex), max 255 chars, lowercase
+    - password: Min 8 chars, 1 uppercase, 1 number, 1 special
+    - name: 2-50 chars, alphanumeric + spaces only
+
+  Logic flow:
+    1. Check if email exists in users table → If exists: return 409 Conflict
+    2. Hash password using bcrypt (salt rounds: 10)
+    3. Generate UUID for user_id
+    4. Insert into users table: { id: UUID, email, password_hash, name, created_at: NOW() }
+    5. Create JWT token with payload: { user_id, email } → Expiry: 24h, Secret: from env.JWT_SECRET
+
+  Return:
+    - Success (201): { user_id, email, name, token }
+    - Error: { status: 409/400/500, message, error_code }
+
+  Edge cases:
+    - Email already exists → 409 "Email already registered"
+    - Invalid email format → 400 "Invalid email"
+    - Weak password → 400 "Password must meet requirements"
+    - DB connection error → 500 "Registration failed, try again"
+    - Missing env.JWT_SECRET → 500 (log critical error)
+
+  Dependencies:
+    - bcrypt library (hash password)
+    - jsonwebtoken library (generate JWT)
+    - Database: users table (insert)
   ```
 
+  **Pseudo-code must include:**
+  - Function signature or endpoint route
+  - Input validation rules (types, constraints, formats)
+  - Logic flow with specific values/thresholds
+  - Return types for success + error cases
+  - Edge cases with handlers (HTTP status codes, error messages)
+  - Dependencies (external modules, APIs, DB tables)
+
 Create the file automatically:
 
 - `docs/ai/planning/feature-{name}.md` - Use complete structure from `feature-template.md`
 
-**If BEADS_MODE = true:**
-- Add frontmatter with Beads metadata:
-  ```yaml
-  ---
-  beads_task: {task_id}
-  beads_epic: {epic_id}
-  epic_plan: {epic_plan_path}
-  ---
-  ```
-- Update Beads task with plan doc reference:
-  ```bash
-  bd update {task_id} --notes "plan: docs/ai/planning/feature-{name}.md"
-  ```
-
 **Notify user:** "Created plan with X phases: [Phase 1], [Phase 2], ..."
 
 ## Step 8: Next Actions
 
-**If BEADS_MODE = true:**
+**Suggest next command:**
+
 ```
 ✓ Created plan: docs/ai/planning/feature-{name}.md
-✓ Linked to Beads task: {task_id}
 
 Next steps:
-  /execute-plan    → Implement this task
-  /beads-status    → View epic progress
+  /execute-plan    → Implement this feature
 ```
 
-**If normal mode:**
-
-Suggest: `/execute-plan` to begin implementation.
-
 Implementation will be driven from `docs/ai/planning/feature-{name}.md`.
 
 Note: Test documentation will be created separately using the `writing-test` command.
@@ -385,10 +370,35 @@ Note: Test documentation will be created separately using the `writing-test` com
 **Requirement Doc** (`req-template.md`) focuses on **WHAT**:
 - Problem, Users, Business Rules, Functional Requirements
 
+**Epic Doc** (`epic-template.md`) focuses on **TRACKING**:
+- Links requirement to multiple feature plans
+- Tracks status and dependencies between plans
+
 **Planning Doc** (`feature-template.md`) focuses on **HOW**:
 - Codebase Context, Design, Implementation Phases, Pseudo-code
 
+### Cross-Linking Flow
+
+```
+req-{name}.md  ←→  epic-{name}.md  ←→  feature-{name}.md
+   (WHAT)          (TRACKING)            (HOW)
+```
+
+**Standalone (no epic, no req):**
+- feature-template: `requirement` → null, `epic_plan` → null
+- **Remove** Section 0 "Related Documents" entirely
+
+**With requirement only (no epic):**
+- feature-template: `requirement` → req doc, `epic_plan` → null
+- Include Section 0 with requirement link only
+
+**With epic (and req from epic):**
+- feature-template: `requirement` → req doc, `epic_plan` → epic doc
+- Include Section 0 with both links
+- After creation, update epic's Feature Plans table
+
 When requirement doc exists, planning doc should:
-1. Link to requirement doc (Section 0)
+1. Link to requirement doc and epic (Section 0: Related Documents)
 2. Not duplicate requirement content - reference it instead
 3. Focus on technical implementation details
+4. After creation, update epic's Feature Plans table (if epic exists)

package/.claude/commands/execute-plan.md

@@ -40,36 +40,6 @@ Expected speedup: 30-40% for context loading phase.
 
 ---
 
-## Step 0: Check Beads Context (Optional Integration)
-
-> **Purpose**: Detect if this plan is for a Beads task. If so, track for final suggestions.
-
-**Read:** `.beads/current-task.json`
-
-**If file exists (Beads workflow active):**
-
-```json
-{
-  "task_id": "bd-auth.1",
-  "task_title": "Setup JWT infrastructure",
-  "epic_id": "bd-auth",
-  "epic_title": "User Authentication System"
-}
-```
-
-Set internal flags:
-- `BEADS_MODE = true`
-- `beads_task_id = task_id`
-- `beads_task_title = task_title`
-
-**If file does not exist:**
-- `BEADS_MODE = false`
-- Proceed with normal workflow (no Beads integration)
-
-**Output:** Internal state set. No user-visible output for this step.
-
----
-
 ## Step 1: Gather Context
 
 **Tools:**
@@ -254,31 +224,20 @@ Only run after ALL phases are marked complete. If incomplete phases remain, skip
 
 ## Step 6: Next Actions
 
-**If BEADS_MODE = true AND all phases complete:**
+**If all phases complete:**
 
 ```
-✓ All phases complete for Beads task: {beads_task_id} "{beads_task_title}"
+✓ All phases complete!
 
 Next steps:
-  /beads-done           → Close task, sync to git, see next ready tasks
-  /beads-status         → View epic progress
-
-Optional quality checks:
   /code-review          → Verify against standards
   /writing-test         → Add test coverage
   /check-implementation → Validate alignment with plan
 ```
 
-**If BEADS_MODE = false AND all phases complete:**
-
-- Suggest running `code-review` to verify against standards
-- Suggest running `writing-test` if edge cases need coverage
-- Suggest running `check-implementation` to validate alignment with planning entries
-
-**If phases remain (both modes):**
+**If phases remain:**
 
 - User runs `/execute-plan` again; Phase detection (Step 1d) will resume correctly
-- **If BEADS_MODE = true:** Remind user task is still in_progress in Beads
 
 ## Notes
 

package/.claude/commands/manage-epic.md

@@ -0,0 +1,227 @@
+---
+name: manage-epic
+description: Create or update epic - tracks feature plans for a requirement.
+---
+
+## Goal
+
+Manage epic documents that link requirements to feature plans. An epic is a simple tracking document that lists all feature plans needed to fulfill a requirement.
+
+**When to use:**
+- A requirement is too large for a single feature plan
+- You need to break a requirement into multiple feature plans
+- You need to update an epic with new feature plans or status changes
+
+---
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- For medium/large tasks, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
+- Update todos immediately after progress; mark completed upon finish.
+
+---
+
+## Step 1: Detect Mode
+
+**Parse user input to determine mode:**
+
+| Input | Mode | Action |
+|-------|------|--------|
+| Requirement doc path provided | **Create** | Create new epic from requirement |
+| Epic doc path provided | **Update** | Update existing epic |
+| Feature plan path + epic path | **Link** | Add feature plan to epic |
+| No specific path | **Ask** | Ask user what they want to do |
+
+**If unclear, ask:**
+
+```
+AskUserQuestion(questions=[{
+  question: "What would you like to do with the epic?",
+  header: "Mode",
+  options: [
+    { label: "Create new epic", description: "Break a requirement into feature plans" },
+    { label: "Update epic", description: "Add feature plan or update status" },
+    { label: "Sync status", description: "Update status of all linked documents" }
+  ],
+  multiSelect: false
+}])
+```
+
+---
+
+## Step 2: Create Mode
+
+### 2a: Read Requirement
+
+```
+Read(file_path="docs/ai/requirements/req-{name}.md")
+```
+
+Extract:
+- Feature name
+- Functional requirements (FR table)
+- Implementation guidance / suggested phases
+- Complexity level
+
+### 2b: Break into Feature Plans
+
+Analyze the requirement and propose how to break it into feature plans.
+
+**Guidelines:**
+- Each feature plan should be independently implementable
+- Group by: feature area, layer (frontend/backend), or dependency order
+- Aim for 2-6 feature plans per epic
+- Each plan should map to specific FRs from the requirement
+
+**Ask user to confirm breakdown:**
+
+```
+AskUserQuestion(questions=[{
+  question: "Here's the proposed breakdown. Does this look right?",
+  header: "Breakdown",
+  options: [
+    { label: "Looks good", description: "Create epic with this breakdown" },
+    { label: "Adjust", description: "I want to modify the breakdown" },
+    { label: "Fewer plans", description: "Merge some plans together" }
+  ],
+  multiSelect: false
+}])
+```
+
+### 2c: Load Template & Generate Epic
+
+```
+Read(file_path="docs/ai/planning/epic-template.md")
+```
+
+Generate `docs/ai/planning/epic-{name}.md` with:
+- `requirement` frontmatter pointing to the req doc
+- Overview: 1-3 sentences from requirement's executive summary
+- Feature Plans table: proposed feature plans with descriptions
+- Dependency graph: show dependencies between feature plans
+- Related Documents: link back to requirement
+
+**Auto-name:** Derive from requirement name (kebab-case).
+- Example: `req-user-authentication.md` → `epic-user-authentication.md`
+
+**If file already exists:**
+1. Backup to `docs/ai/planning/archive/epic-{name}_{timestamp}.md`
+2. Overwrite main file
+3. Notify user of backup
+
+### 2d: Update Requirement Doc
+
+After creating epic, update the requirement doc's frontmatter and Related Plans section:
+- Set `epic_plan` in frontmatter
+- Update Related Plans table with epic link
+
+---
+
+## Step 3: Update Mode
+
+### 3a: Read Current Epic
+
+```
+Read(file_path="docs/ai/planning/epic-{name}.md")
+```
+
+### 3b: Determine Update Type
+
+| Trigger | Action |
+|---------|--------|
+| New feature plan created | Add row to Feature Plans table |
+| Feature plan completed | Update status to `completed` |
+| Feature plan started | Update status to `in_progress` |
+| Dependency changed | Update dependency graph |
+
+### 3c: Apply Update
+
+Edit the epic document with the change. Keep all other content intact.
+
+---
+
+## Step 4: Link Mode
+
+When a new feature plan is created (e.g., via `/create-plan`), link it to the epic:
+
+1. Read the epic document
+2. Add the feature plan to the Feature Plans table
+3. Update the feature plan's `epic_plan` frontmatter to point to the epic
+4. Update dependency graph if needed
+
+---
+
+## Step 5: Sync Status
+
+Scan all linked documents and synchronize status:
+
+1. Read the epic document
+2. For each feature plan in the table:
+   - Read the feature plan
+   - Check if implementation tasks are completed
+   - Update status in epic table
+3. Update requirement doc if all feature plans are completed
+
+---
+
+## Step 6: Summary & Next Steps
+
+```markdown
+## Epic Updated
+
+**File**: docs/ai/planning/epic-{name}.md
+
+### Feature Plans
+| # | Plan | Status |
+|---|------|--------|
+| 1 | feature-{name}-part1.md | {status} |
+| 2 | feature-{name}-part2.md | {status} |
+
+### Next Steps
+- `/create-plan` → Create a feature plan listed in this epic
+- `/execute-plan` → Implement a feature plan
+- `/manage-epic` → Update status or add feature plans
+```
+
+---
+
+## Cross-Linking Rules
+
+When creating or updating documents, ensure cross-links are maintained.
+**Only add links when they exist — never add placeholder/null links.**
+
+### Creating Epic from Requirement (`/manage-epic`)
+1. Epic: set `requirement` frontmatter → req doc path
+2. Req doc: add "Related Plans" section with epic link (this section doesn't exist by default)
+
+### Adding Feature Plan to Epic (`/create-plan` with epic context)
+1. Epic: add row to Feature Plans table
+2. Feature plan: set `epic_plan` frontmatter → epic path
+3. Feature plan: set `requirement` frontmatter → req doc path (from epic)
+4. Feature plan: include Section 0 "Related Documents" with both links
+
+### Creating Feature Plan standalone (`/create-plan` without epic or req)
+1. Feature plan: frontmatter `epic_plan` = null, `requirement` = null
+2. Feature plan: **remove** Section 0 "Related Documents" entirely
+3. No cross-linking needed
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Requirement doc not found | Ask user for path or create requirement first |
+| Epic already exists | Ask: update existing or create new (backup old) |
+| Feature plan not found | Skip link, warn user |
+| Template not found | Use minimal structure from this command |
+
+---
+
+## Notes
+
+- Epic is purely a tracking document — no architecture or implementation details
+- Feature plans contain all implementation details (via `/create-plan`)
+- Requirement doc contains all WHAT details (via `/clarify-requirements`)
+- Epic bridges the gap: tracks WHICH feature plans implement WHICH requirement

package/README.md

@@ -6,7 +6,7 @@ A standardized AI workflow system for modern AI coding assistants. Initialize st
 
 - **Multi-Platform Support**: Works with Cursor, GitHub Copilot, Claude Code, OpenCode, and Factory Droid
 - **Structured Workflows**: Plan → Implement → Test → Review methodology
-- **14 Pre-built Commands**: Create plans, execute tasks, run tests, code reviews, and more
+- **9 Pre-built Commands**: Create plans, execute tasks, run tests, code reviews, and more
 - **7 Reusable Skills**: Design fundamentals, accessibility, theme generation, quality checks
 - **Universal Standards**: `AGENTS.md` works across all AI tools
 - **Smart Installation**: Protected files, selective updates, no data loss
@@ -297,80 +297,9 @@ User: /sync-workflow
 
 ---
 
-## Beads Integration (Optional)
-
-[Beads](https://github.com/steveyegge/beads) is a lightweight issue tracker with first-class dependency support. This workflow integrates seamlessly with Beads for multi-session task management.
-
-### Setup Beads
-
-1. **Install Beads**: Follow the official docs at https://github.com/steveyegge/beads
-
-2. **Setup for Claude Code**:
-   ```bash
-   bd setup claude
-   ```
-
-3. **Verify installation**:
-   ```bash
-   bd doctor
-   ```
-
-### Beads Commands
-
-| Command | Description |
-|---------|-------------|
-| `/beads-breakdown` | Analyze feature → create epic with tasks and dependencies |
-| `/beads-create-epic-plan` | Create high-level epic plan document |
-| `/beads-next` | Show ready tasks, claim a task, set context |
-| `/beads-done` | Close task, sync to git, show next ready tasks |
-| `/beads-status` | Show epic progress, metrics, dependency graph |
-
----
-
 ## Workflow Examples
 
-### Workflow A: With Beads (Multi-session, Dependencies)
-
-Best for: Large features, team collaboration, work that spans multiple sessions.
-
-```
-┌──────────────┐    ┌───────────────────┐    ┌─────────────┐
-│ /beads-      │ → │ /beads-create-    │ → │ /beads-next │
-│ breakdown    │    │ epic-plan         │    │             │
-└──────────────┘    └───────────────────┘    └──────┬──────┘
-                                                    │
-┌──────────────┐    ┌───────────────────┐    ┌──────▼──────┐
-│ /beads-done  │ ← │ /execute-plan     │ ← │ /create-plan│
-│              │    │                   │    │             │
-└──────────────┘    └───────────────────┘    └─────────────┘
-       │
-       └──────→ Loop back to /beads-next for next task
-```
-
-```bash
-# 1. Break down feature into epic with tasks
-/beads-breakdown "User authentication with JWT"
-
-# 2. Create high-level epic plan (architecture, data flow)
-/beads-create-epic-plan
-
-# 3. Claim a ready task
-/beads-next
-
-# 4. Create detailed plan for claimed task
-/create-plan
-
-# 5. Implement the task
-/execute-plan jwt-infrastructure
-
-# 6. Complete task, sync, see next ready tasks
-/beads-done
-
-# 7. Repeat from step 3 for remaining tasks
-/beads-next
-```
-
-### Workflow B: Without Beads (Single-session)
+### Standard Workflow (Single-session)
 
 Best for: Small features, quick fixes, solo work.
 
@@ -396,20 +325,7 @@ Best for: Small features, quick fixes, solo work.
 /code-review
 ```
 
-### When to Use Which Workflow?
-
-| Scenario | Recommended Workflow |
-|----------|---------------------|
-| Feature takes < 1 session | **Without Beads** |
-| Feature spans multiple sessions | **With Beads** |
-| Multiple developers on same feature | **With Beads** |
-| Tasks have dependencies | **With Beads** |
-| Quick bug fix | **Without Beads** |
-| Complex epic with 5+ tasks | **With Beads** |
-
----
-
-### Example: Complex Requirements (Without Beads)
+### Example: Complex Requirements
 
 ```bash
 # 1. Clarify requirements first
@@ -425,7 +341,7 @@ Best for: Small features, quick fixes, solo work.
 /check-implementation checkout-flow
 ```
 
-### Example: Bug Fix with Tests (Without Beads)
+### Example: Bug Fix with Tests
 
 ```bash
 # 1. Quick plan for the fix