@relipa/ai-flow-kit 0.1.1 → 0.1.2-beta.0

package/docs/common/AIFLOW.md

@@ -1,512 +1,512 @@
-# AIFLOW — Software Development Workflow with AI
-
-**Version:** 2.0.0 | **Package:** ai-flow-kit
-
-> This workflow applies to all tasks: feature, bug-fix, refactor, investigation.
-> **Absolute Rule: Complete Gate N → Only then can you enter Gate N+1. No exceptions.**
-
----
-
-## Workflow Overview
-
-```
-PM writes ticket on Backlog/Jira
-        │
-        ▼
-⛩️ GATE 1 — AI Analyze Requirement          [AI + DEV]
-  AI loads ticket + reads source code
-  AI asks clarifying questions until clear
-  AI outputs: requirement.md
-    (requirements, solution, impact analysis, estimate)
-  DEV reviews → "APPROVED"
-        │ APPROVED
-        ▼
-⛩️ GATE 2 — Implementation Plan             [AI + DEV]
-  AI creates detailed coding plan (TDD steps)
-  DEV reviews → "APPROVED"
-        │ APPROVED
-        ▼
-⛩️ GATE 3 — Code Generation (TDD)           [AI]
-  AI writes tests first → implement → tests pass
-  Verify implementation works
-        │ Code done
-        ▼
-⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
-  AI runs: verification + impact-analysis + checklist
-  AI generates: task-summary.md
-  DEV reviews → "APPROVED" or "BUG: [description]"
-        │ APPROVED
-        ▼
-⛩️ GATE 5 — Peer Review & PR                [DEV + Peer]
-  requesting-code-review skill
-  Create Pull Request → merge
-        │
-        ▼
-       DONE
-```
-
----
-
-## Roles
-
-| Role | Responsibility |
-|------|---------------|
-| **PM** | Write ticket on Backlog/Jira with description, acceptance criteria, context |
-| **DEV** | Trigger workflow, review AI outputs at each gate, type APPROVED or provide feedback |
-| **AI** | Analyze requirements, propose solutions, generate code (TDD), self-review |
-
----
-
-## Task Management (Context Switching)
-
-AI Flow Kit allows you to manage multiple tasks in the same repository without losing gate progress.
-
-- **`aiflow task status`**: Show active and pending tasks.
-- **`aiflow task pause`**: Save current context and gate progress to `.aiflow/tasks/<taskId>/`.
-- **`aiflow task switch <id>`**: Pause current task and switch to another.
-- **`aiflow task resume <id>`**: Restore context and gate state. AI auto-resumes from the correct gate.
-- **`aiflow task next`**: Approve the current gate, generate `task-summary.md`, clear active context, and prepare the task for a fresh session (Recommended to avoid context pollution).
-
-### Pro-Tip: Fresh Session Workflow
-For the best AI performance, run `aiflow task next` after every gate approval, then open a **new chatbox** and type "continue". This clears out long chat history that might confuse the AI.
-
----
-
-## Gate Details
-
----
-
-### ⛩️ GATE 1 — AI Analyze Requirement
-
-**Who performs:** AI (analyze) + DEV (review & approve)
-
-**Trigger:**
-```bash
-aiflow use PROJ-33              # load ticket (fast mode, default)
-aiflow use PROJ-33 --full       # load ticket, force full analysis
-aiflow use --file task.md        # load task from local text/json file
-claude                           # open Claude → AI auto-starts Gate 1
-```
-
-> `aiflow prompt` is optional — use it only when pasting into Claude Desktop/Web.
->
-> **Tool Support:**
-> - **Claude Code:** AI auto-starts Gate 1 via SessionStart hook.
-> - **Cursor:** Instructions in `.cursorrules` enforce the Gate Workflow.
-> - **Gemini CLI:** Rules in `GEMINI.md` guide the session.
-> - **Copilot:** Instructions in `.github/copilot-instructions.md`.
-
-**Gate 1 Modes:**
-
-| Mode | Flag | When to use | Output |
-|------|------|-------------|--------|
-| `fast` (default) | _(none)_ | Standard tickets, clear intent | Lite 3-section doc (Summary, Files, Estimate). Target < 5 min |
-| `full` | `--full` | Complex tickets, force deep analysis | Full 6-section requirement doc |
-| `auto` | _(legacy)_ | Same as fast | |
-
-**What AI does (in order):**
-
-| Step | Action | Purpose |
-|------|--------|---------|
-| 1 | Load ticket from `.aiflow/context/current.json` | Get PM's requirements, comments |
-| 2 | Read `CLAUDE.md` + source code | Understand architecture, tech stack, patterns |
-| 3 | Investigate related files & data flow | Identify affected areas, dependencies |
-| 4 | Ask clarifying questions (one at a time) | Ensure full understanding |
-| 5 | Write `plan/[ticket-id]/requirement.md` | Structured requirement document |
-
-**AI asks questions when:**
-- Business requirements are vague or ambiguous
-- Acceptance criteria are not measurable
-- Edge cases are discovered in source code
-- Multiple approaches are possible and need input
-- Impact on existing features is unclear
-
-**Requirement Document Output (`plan/[ticket-id]/requirement.md`):**
-
-```
-├── 1. Requirements Summary
-│   ├── Description (AI's understanding in technical language)
-│   ├── Current behavior / Business goal
-│   ├── Acceptance Criteria (refined, measurable)
-│   └── Context & Constraints
-├── 2. Source Code Analysis
-│   ├── Related files & their roles
-│   ├── Data flow diagram
-│   ├── Existing patterns to follow
-│   └── Current test coverage
-├── 3. Proposed Solution & Approach
-│   ├── Option A (recommended) — pros/cons
-│   ├── Option B (alternative) — pros/cons
-│   ├── Chosen approach & rationale
-│   ├── Files to create/modify
-│   └── Database changes (if any)
-├── 4. Impact Analysis
-│   ├── Impact level (Low/Medium/High)
-│   ├── Affected areas
-│   ├── Breaking changes
-│   └── Risks & mitigations
-├── 5. Effort Estimate
-│   ├── Task breakdown with size (S/M/L/XL)
-│   └── Sub-task split for XL tasks
-└── 6. Testing Plan
-    ├── Unit tests
-    ├── Integration tests
-    └── Manual test cases
-```
-
-**Gate 1 Display:**
-
-```
-⏸️ GATE 1: REQUIREMENT DOCUMENT READY
-
-Summary:
-- Type: [feature / bug-fix / refactor]
-- Impact: [Low / Medium / High]
-- Estimate: [S / M / L / XL]
-- Approach: [brief description]
-- Files affected: [N] files
-
-→ Review: plan/[ticket-id]/requirement.md
-→ Type APPROVED to proceed
-→ Or provide feedback to update
-```
-
-**Gate 1 Output:**
-- `plan/[ticket-id]/requirement.md` approved by DEV
-- DEV has typed "APPROVED"
-
----
-
-### ⛩️ GATE 2 — Implementation Plan
-
-**Who performs:** AI (create plan) + DEV (review & approve)
-
-**What AI does:**
-
-1. Read the approved requirement document
-2. **Invoke** `superpowers:writing-plans` → create detailed implementation plan
-3. Break down into TDD tasks: test first → implement → verify
-4. Define verification strategy (evidence before claims)
-5. Present plan and wait for APPROVED
-
-**Implementation Plan Structure:**
-
-```
-├── Task Breakdown (TDD Order)
-│   ├── Task 1: Write test for [scenario]
-│   ├── Task 2: Implement [component]
-│   ├── Task 3: Write test for [next scenario]
-│   └── ...
-└── Test Commands
-```
-
-**Gate 2 Display:**
-
-```
-⏸️ GATE 2: IMPLEMENTATION PLAN READY
-
-Tasks: [N] | Verification: [N] | Test-first tasks: [N]
-
-→ Type APPROVED to start coding
-→ Or provide feedback to adjust
-```
-
-**Gate 2 Output:**
-- Implementation plan approved by DEV
-- DEV has typed "APPROVED"
-
----
-
-### ⛩️ GATE 3 — Code Generation
-
-**Who performs:** AI
-
-**Only runs after Gate 2 APPROVED.**
-
-**Mandatory Order:**
-
-#### Feature task:
-1. Complex feature (3+ files) → `superpowers:subagent-driven-development`
-2. `superpowers:test-driven-development` — write tests FIRST
-3. Run tests → confirm FAIL
-4. Implement code → tests PASS
-5. Verify implementation works
-
-#### Bug fix task (extra):
-1. `superpowers:systematic-debugging` — trace root cause, NO guessing
-2. `investigate-bug` skill — trace Controller→Service→Repository
-3. Then TDD: write test to reproduce bug → fix → tests PASS
-
-#### Refactor task (extra):
-1. Ensure tests cover current behavior
-2. Refactor in small steps — keep tests green continuously
-
-**Fast Mode (tdd-lean):**
-In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massive token costs:
-1. **Batch Red:** Write ALL tests at once. Run once. (Confirm all fail).
-2. **Batch Green:** Implement ALL code at once. Run once. (Confirm all pass).
-3. **Discipline:** After every run, discard full stack traces and keep ONLY the summary line.
-
-**Gate 3 Output:**
-- Code implementation finished
-- All tests PASS
-- Verified (evidence provided)
-
----
-
-### ⛩️ GATE 4 — AI Self-Review
-
-**Who performs:** AI (self-review) + DEV (final approve)
-
-**AI runs in mandatory order:**
-
-| Step | Action | Required Result |
-|------|--------|------------|
-| 1 | `superpowers:verification-before-completion` | All tests PASS |
-| 2 | `impact-analysis` skill | No breaking changes outside scope |
-| 3 | `custom/rules/review-checklist.md` | All items ticked |
-| 4 | Create `plan/[ticket-id]/summary.md` | File exists and is complete |
-
-**If any step fails → AI fixes it first, without showing DEV.**
-
-**Summary report output:**
-
-```
-plan/[ticket-id]/summary.md
-├── List of changed files + reasons
-├── Acceptance Criteria → results (Done/Not Done)
-├── Tests: quantity, coverage
-├── Impact Analysis: level (Low/Medium/High)
-└── Review Checklist: N/N items ✅
-```
-
-**Gate 4 Display:**
-```
-⏸️ GATE 4: WAITING FOR DEV REVIEW
-
-Tests: ✅ [N] passed
-Impact: [Low/Medium/High]
-Checklist: [N/N] ✅
-Summary: plan/[ticket-id]/summary.md
-
-Type APPROVED if OK
-Type BUG: [description] if there are issues
-```
-
-**DEV Response:**
-- `APPROVED` → move to Gate 5
-- `BUG: coding bug` → AI fixes → repeat Gate 4
-- `BUG: requirement bug` → AI updates requirement doc → back to Gate 1
-
-**Gate 4 Output:**
-- `plan/[ticket-id]/summary.md` completed
-- DEV has typed "APPROVED"
-
----
-
-### ⛩️ GATE 5 — Peer Review & Pull Request
-
-**Who performs:** DEV + Peer reviewer
-
-**Only runs after Gate 4 APPROVED.**
-
-**AI invokes:** `superpowers:requesting-code-review`
-
-**AI guides PR creation:**
-
-```markdown
-## Pull Request Template
-
-**Title:** [feat/fix/refactor]: [PROJ-XX] [Short description]
-
-**Description:**
-Closes [PROJ-XX]
-
-### Changes
-- [File A] — [what changed]
-- [File B] — [what changed]
-
-### Acceptance Criteria
-- [x] [Criteria 1]
-- [x] [Criteria 2]
-
-### Testing
-- Unit tests: [N] cases
-- Integration tests: [N] cases
-- Manual test: [tested manually?]
-
-### Impact
-[Low/Medium/High] — [short description]
-
-### Reviewer notes
-[Anything special for the reviewer to notice]
-```
-
-**Peer reviewer checks:**
-- Code logic matches requirement document
-- Tests are sufficient and meaningful
-- No security issues
-- Acceptable performance
-- Follows team conventions
-
-**Gate 5 Output:**
-- PR created with full description
-- Peer reviewer APPROVED
-- Merged into main/develop
-
----
-
-## Workflow by Task Type
-
-### Bug Fix
-```
-Gate 1 (AI analyzes bug: root cause hypothesis + solution + impact + estimate)
-→ Gate 2 (implementation plan: test reproduce bug → fix → verify)
-→ Gate 3 (systematic-debugging + investigate-bug + TDD fix)
-→ Gate 4 (verify fix + no regression)
-→ Gate 5 (peer review + PR)
-```
-
-### Feature
-```
-Gate 1 (AI analyzes feature: architecture + solution options + impact + estimate)
-→ Gate 2 (implementation plan: TDD task breakdown)
-→ Gate 3 (TDD: test first, implement, subagent if complex)
-→ Gate 4 (verify all AC done + impact check)
-→ Gate 5 (peer review + PR)
-```
-
-### Investigation
-```
-Gate 1 (AI investigates: analyze scope, trace code, document findings + recommendations)
-→ DEV reviews → APPROVED
-→ DONE (no Gates 2-5, create new ticket if action needed)
-```
-
-### Refactor
-```
-Gate 1 (AI analyzes: current state, target state, impact + estimate)
-→ Gate 2 (implementation plan: ensure tests cover behavior → refactor steps)
-→ Gate 3 (TDD: cover behavior → refactor → tests green)
-→ Gate 4 (verify no regressions)
-→ Gate 5 (peer review + PR)
-```
-
-### Impact Analysis
-```
-Gate 1 (AI analyzes: dependency map, risk level, breaking changes, recommendations)
-→ DEV reviews → APPROVED
-→ DONE (no Gates 2-5, implementation needs a separate ticket)
-```
-
----
-
-## Skills Used in Workflow
-
-| Skill | Gate | Purpose |
-|-------|------|---------|
-| `read-study-requirement` | Gate 1 | AI reads, analyzes, asks questions, outputs requirement doc |
-| `superpowers:systematic-debugging` | Gate 1 (bug) | Trace root cause hypothesis |
-| `generate-spec` | Gate 2 | Create implementation plan |
-| `superpowers:writing-plans` | Gate 2 | Detailed TDD task breakdown |
-| `investigate-bug` | Gate 3 (bug) | Trace data flow per framework |
-| `superpowers:test-driven-development` | Gate 3 | TDD workflow |
-| `superpowers:subagent-driven-development` | Gate 3 (complex) | Parallel implementation |
-| `review-plan` | Gate 4 | Orchestrate self-review |
-| `superpowers:verification-before-completion` | Gate 4 | Verify tests pass |
-| `impact-analysis` | Gate 4 | Check breaking changes |
-| `superpowers:requesting-code-review` | Gate 5 | Peer review workflow |
-
----
-
-## Commands Reference
-
-```bash
-# Setup (once per project)
-aiflow init --framework spring-boot --adapter backlog
-
-# Per task (2 commands only)
-aiflow use PROJ-33                    # load ticket context (full analysis)
-aiflow use PROJ-33 --fast             # fast mode: lite Gate 1 (< 5 min)
-aiflow use PROJ-33 --full             # force full Gate 1 analysis
-claude                                # AI auto-starts Gate 1
-
-# Optional: generate prompt for Claude Desktop/Web
-aiflow prompt bug-fix                 # generate prompt to paste
-aiflow prompt feature --output p.md   # save prompt to file
-
-# Task switching (multiple tasks in same repo)
-aiflow task status                    # view active + pending tasks
-aiflow task pause                     # pause current task
-aiflow task pause --note "waiting for PM"
-aiflow task switch PROJ-99            # pause current + switch
-aiflow task resume PROJ-33            # resume a paused task
-
-# Utilities
-aiflow context show                   # view active context
-aiflow memory save "key" "value"      # save team knowledge
-aiflow doctor                         # health check
-aiflow guide                          # view quickstart guide
-
-# Telemetry (team leads)
-aiflow telemetry status               # view status
-aiflow telemetry enable               # setup tracking
-aiflow telemetry disable              # disable tracking
-```
-
----
-
-## Multi-AI Environment Setup
-
-One of the core strengths of `ai-flow-kit` is that the **Gate Workflow** is tool-agnostic. Since state is saved in `.aiflow/context/current.json` and the `plan/` directory, you can switch tools mid-task.
-
-### How to Switch Tools
-1. **Analyze (Gate 1)** using Claude Code CLI (great for deep codebase scans).
-2. **Review** the `requirement.md` file.
-3. **Open Cursor** to perform the coding (Gate 3).
-4. Cursor will automatically read `.cursorrules`, detect the active ticket, and see that Gate 1 is already finished.
-5. Cursor will proceed to Gate 2 or 3 as appropriate.
-
-### Instruction Files Created
-| Tool | File Name | Purpose |
-|------|-----------|---------|
-| Claude Code | `CLAUDE.md` | Primary rules for the CLI tool. |
-| Cursor AI | `.cursorrules` | Project-wide rules for Cursor. |
-| Gemini CLI | `GEMINI.md` | Context for Gemini sessions. |
-| Copilot | `.github/copilot-instructions.md` | Custom instructions for Copilot. |
-
----
-
-## FAQ
-
-**Q: PM didn't write enough on the ticket, what happens?**
-A: AI at Gate 1 will read what's available, then ask clarifying questions one at a time until the requirement is clear enough to propose a solution.
-
-**Q: Does AI just check format or actually understand the requirement?**
-A: AI actively reads source code, traces data flow, identifies related files, and proposes solutions. It asks questions based on what it finds in the code — not just checking if fields exist.
-
-**Q: Gate 1 is taking too long for a simple ticket. What can I do?**
-A: Use `aiflow use TICKET-ID --fast` before opening Claude. Fast mode skips the Q&A loop and outputs a lean 3-section requirement doc. Best suited for tickets with ≥ 3 clear, measurable acceptance criteria and no ambiguity. Target: Gate 1 done in < 5 minutes.
-
-**Q: Can I skip Gate 2 for simple tasks?**
-A: No. Gate 2 can be brief (simple plan), but DEV must still type "APPROVED" to confirm the approach.
-
-**Q: AI reports test failures at Gate 4, what to do?**
-A: AI will try to fix them before showing DEV. If it can't, it will report the reason and ask for DEV's support.
-
-**Q: What's the difference between a requirement bug and a coding bug?**
-A: Requirement bug = wrong/missing in requirement doc → back to Gate 1. Coding bug = wrong code but correct requirement → fix at Gate 4.
-
-**Q: Who performs peer review (Gate 5)?**
-A: Another developer in the team. Not the code author. The reviewer uses the `superpowers:receiving-code-review` skill.
-
-**Q: Can I work on two tasks in the same repo at the same time?**
-A: Yes. Use `aiflow task pause` to save your current progress, then `aiflow use <new-ticket>` to start the new task. Resume later with `aiflow task resume <ticket-id>`. The gate progress is saved automatically — Claude will resume from the correct gate instead of restarting Gate 1.
-
-**Q: If I resume a task, will Claude know which gate to start at?**
-A: Yes. The SessionStart hook reads `.aiflow/tasks/<taskId>/task-state.json` and injects gate-aware instructions. If Gate 1 was already approved, Claude will skip to Gate 2, and so on.
-**Q: Can I resume a Gate 3 (Code Generation) task in a new chatbox?**
-A: Yes. Gate 3 progress is saved via `[x]` checkboxes in `plan/[id]/plan.md`. If you open a new chatbox and say "continue", the AI will automatically skip completed tasks and pick up exactly where it left off.
-
-**Q: How does AI estimate effort?**
-A: AI analyzes the scope of changes (files affected, complexity, test requirements) and categorizes: S (< 1h), M (1-4h), L (4-8h), XL (8h+, should split).
+# AIFLOW — Software Development Workflow with AI
+
+**Version:** 2.0.0 | **Package:** ai-flow-kit
+
+> This workflow applies to all tasks: feature, bug-fix, refactor, investigation.
+> **Absolute Rule: Complete Gate N → Only then can you enter Gate N+1. No exceptions.**
+
+---
+
+## Workflow Overview
+
+```
+PM writes ticket on Backlog/Jira
+        │
+        ▼
+⛩️ GATE 1 — AI Analyze Requirement          [AI + DEV]
+  AI loads ticket + reads source code
+  AI asks clarifying questions until clear
+  AI outputs: requirement.md
+    (requirements, solution, impact analysis, estimate)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Implementation Plan             [AI + DEV]
+  AI creates detailed coding plan (TDD steps)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 3 — Code Generation (TDD)           [AI]
+  AI writes tests first → implement → tests pass
+  Verify implementation works
+        │ Code done
+        ▼
+⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
+  AI runs: verification + impact-analysis + checklist
+  AI generates: task-summary.md
+  DEV reviews → "APPROVED" or "BUG: [description]"
+        │ APPROVED
+        ▼
+⛩️ GATE 5 — Peer Review & PR                [DEV + Peer]
+  requesting-code-review skill
+  Create Pull Request → merge
+        │
+        ▼
+       DONE
+```
+
+---
+
+## Roles
+
+| Role | Responsibility |
+|------|---------------|
+| **PM** | Write ticket on Backlog/Jira with description, acceptance criteria, context |
+| **DEV** | Trigger workflow, review AI outputs at each gate, type APPROVED or provide feedback |
+| **AI** | Analyze requirements, propose solutions, generate code (TDD), self-review |
+
+---
+
+## Task Management (Context Switching)
+
+AI Flow Kit allows you to manage multiple tasks in the same repository without losing gate progress.
+
+- **`aiflow task status`**: Show active and pending tasks.
+- **`aiflow task pause`**: Save current context and gate progress to `.aiflow/tasks/<taskId>/`.
+- **`aiflow task switch <id>`**: Pause current task and switch to another.
+- **`aiflow task resume <id>`**: Restore context and gate state. AI auto-resumes from the correct gate.
+- **`aiflow task next`**: Approve the current gate, generate `task-summary.md`, clear active context, and prepare the task for a fresh session (Recommended to avoid context pollution).
+
+### Pro-Tip: Fresh Session Workflow
+For the best AI performance, run `aiflow task next` after every gate approval, then open a **new chatbox** and type "continue". This clears out long chat history that might confuse the AI.
+
+---
+
+## Gate Details
+
+---
+
+### ⛩️ GATE 1 — AI Analyze Requirement
+
+**Who performs:** AI (analyze) + DEV (review & approve)
+
+**Trigger:**
+```bash
+aiflow use PROJ-33              # load ticket (fast mode, default)
+aiflow use PROJ-33 --full       # load ticket, force full analysis
+aiflow use --file task.md        # load task from local text/json file
+claude                           # open Claude → AI auto-starts Gate 1
+```
+
+> `aiflow prompt` is optional — use it only when pasting into Claude Desktop/Web.
+>
+> **Tool Support:**
+> - **Claude Code:** AI auto-starts Gate 1 via SessionStart hook.
+> - **Cursor:** Instructions in `.cursorrules` enforce the Gate Workflow.
+> - **Gemini CLI:** Rules in `GEMINI.md` guide the session.
+> - **Copilot:** Instructions in `.github/copilot-instructions.md`.
+
+**Gate 1 Modes:**
+
+| Mode | Flag | When to use | Output |
+|------|------|-------------|--------|
+| `fast` (default) | _(none)_ | Standard tickets, clear intent | Lite 3-section doc (Summary, Files, Estimate). Target < 5 min |
+| `full` | `--full` | Complex tickets, force deep analysis | Full 6-section requirement doc |
+| `auto` | _(legacy)_ | Same as fast | |
+
+**What AI does (in order):**
+
+| Step | Action | Purpose |
+|------|--------|---------|
+| 1 | Load ticket from `.aiflow/context/current.json` | Get PM's requirements, comments |
+| 2 | Read `CLAUDE.md` + source code | Understand architecture, tech stack, patterns |
+| 3 | Investigate related files & data flow | Identify affected areas, dependencies |
+| 4 | Ask clarifying questions (one at a time) | Ensure full understanding |
+| 5 | Write `plan/[ticket-id]/requirement.md` | Structured requirement document |
+
+**AI asks questions when:**
+- Business requirements are vague or ambiguous
+- Acceptance criteria are not measurable
+- Edge cases are discovered in source code
+- Multiple approaches are possible and need input
+- Impact on existing features is unclear
+
+**Requirement Document Output (`plan/[ticket-id]/requirement.md`):**
+
+```
+├── 1. Requirements Summary
+│   ├── Description (AI's understanding in technical language)
+│   ├── Current behavior / Business goal
+│   ├── Acceptance Criteria (refined, measurable)
+│   └── Context & Constraints
+├── 2. Source Code Analysis
+│   ├── Related files & their roles
+│   ├── Data flow diagram
+│   ├── Existing patterns to follow
+│   └── Current test coverage
+├── 3. Proposed Solution & Approach
+│   ├── Option A (recommended) — pros/cons
+│   ├── Option B (alternative) — pros/cons
+│   ├── Chosen approach & rationale
+│   ├── Files to create/modify
+│   └── Database changes (if any)
+├── 4. Impact Analysis
+│   ├── Impact level (Low/Medium/High)
+│   ├── Affected areas
+│   ├── Breaking changes
+│   └── Risks & mitigations
+├── 5. Effort Estimate
+│   ├── Task breakdown with size (S/M/L/XL)
+│   └── Sub-task split for XL tasks
+└── 6. Testing Plan
+    ├── Unit tests
+    ├── Integration tests
+    └── Manual test cases
+```
+
+**Gate 1 Display:**
+
+```
+⏸️ GATE 1: REQUIREMENT DOCUMENT READY
+
+Summary:
+- Type: [feature / bug-fix / refactor]
+- Impact: [Low / Medium / High]
+- Estimate: [S / M / L / XL]
+- Approach: [brief description]
+- Files affected: [N] files
+
+→ Review: plan/[ticket-id]/requirement.md
+→ Type APPROVED to proceed
+→ Or provide feedback to update
+```
+
+**Gate 1 Output:**
+- `plan/[ticket-id]/requirement.md` approved by DEV
+- DEV has typed "APPROVED"
+
+---
+
+### ⛩️ GATE 2 — Implementation Plan
+
+**Who performs:** AI (create plan) + DEV (review & approve)
+
+**What AI does:**
+
+1. Read the approved requirement document
+2. **Invoke** `superpowers:writing-plans` → create detailed implementation plan
+3. Break down into TDD tasks: test first → implement → verify
+4. Define verification strategy (evidence before claims)
+5. Present plan and wait for APPROVED
+
+**Implementation Plan Structure:**
+
+```
+├── Task Breakdown (TDD Order)
+│   ├── Task 1: Write test for [scenario]
+│   ├── Task 2: Implement [component]
+│   ├── Task 3: Write test for [next scenario]
+│   └── ...
+└── Test Commands
+```
+
+**Gate 2 Display:**
+
+```
+⏸️ GATE 2: IMPLEMENTATION PLAN READY
+
+Tasks: [N] | Verification: [N] | Test-first tasks: [N]
+
+→ Type APPROVED to start coding
+→ Or provide feedback to adjust
+```
+
+**Gate 2 Output:**
+- Implementation plan approved by DEV
+- DEV has typed "APPROVED"
+
+---
+
+### ⛩️ GATE 3 — Code Generation
+
+**Who performs:** AI
+
+**Only runs after Gate 2 APPROVED.**
+
+**Mandatory Order:**
+
+#### Feature task:
+1. Complex feature (3+ files) → `superpowers:subagent-driven-development`
+2. `superpowers:test-driven-development` — write tests FIRST
+3. Run tests → confirm FAIL
+4. Implement code → tests PASS
+5. Verify implementation works
+
+#### Bug fix task (extra):
+1. `superpowers:systematic-debugging` — trace root cause, NO guessing
+2. `investigate-bug` skill — trace Controller→Service→Repository
+3. Then TDD: write test to reproduce bug → fix → tests PASS
+
+#### Refactor task (extra):
+1. Ensure tests cover current behavior
+2. Refactor in small steps — keep tests green continuously
+
+**Fast Mode (tdd-lean):**
+In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massive token costs:
+1. **Batch Red:** Write ALL tests at once. Run once. (Confirm all fail).
+2. **Batch Green:** Implement ALL code at once. Run once. (Confirm all pass).
+3. **Discipline:** After every run, discard full stack traces and keep ONLY the summary line.
+
+**Gate 3 Output:**
+- Code implementation finished
+- All tests PASS
+- Verified (evidence provided)
+
+---
+
+### ⛩️ GATE 4 — AI Self-Review
+
+**Who performs:** AI (self-review) + DEV (final approve)
+
+**AI runs in mandatory order:**
+
+| Step | Action | Required Result |
+|------|--------|------------|
+| 1 | `superpowers:verification-before-completion` | All tests PASS |
+| 2 | `impact-analysis` skill | No breaking changes outside scope |
+| 3 | `custom/rules/review-checklist.md` | All items ticked |
+| 4 | Create `plan/[ticket-id]/summary.md` | File exists and is complete |
+
+**If any step fails → AI fixes it first, without showing DEV.**
+
+**Summary report output:**
+
+```
+plan/[ticket-id]/summary.md
+├── List of changed files + reasons
+├── Acceptance Criteria → results (Done/Not Done)
+├── Tests: quantity, coverage
+├── Impact Analysis: level (Low/Medium/High)
+└── Review Checklist: N/N items ✅
+```
+
+**Gate 4 Display:**
+```
+⏸️ GATE 4: WAITING FOR DEV REVIEW
+
+Tests: ✅ [N] passed
+Impact: [Low/Medium/High]
+Checklist: [N/N] ✅
+Summary: plan/[ticket-id]/summary.md
+
+Type APPROVED if OK
+Type BUG: [description] if there are issues
+```
+
+**DEV Response:**
+- `APPROVED` → move to Gate 5
+- `BUG: coding bug` → AI fixes → repeat Gate 4
+- `BUG: requirement bug` → AI updates requirement doc → back to Gate 1
+
+**Gate 4 Output:**
+- `plan/[ticket-id]/summary.md` completed
+- DEV has typed "APPROVED"
+
+---
+
+### ⛩️ GATE 5 — Peer Review & Pull Request
+
+**Who performs:** DEV + Peer reviewer
+
+**Only runs after Gate 4 APPROVED.**
+
+**AI invokes:** `superpowers:requesting-code-review`
+
+**AI guides PR creation:**
+
+```markdown
+## Pull Request Template
+
+**Title:** [feat/fix/refactor]: [PROJ-XX] [Short description]
+
+**Description:**
+Closes [PROJ-XX]
+
+### Changes
+- [File A] — [what changed]
+- [File B] — [what changed]
+
+### Acceptance Criteria
+- [x] [Criteria 1]
+- [x] [Criteria 2]
+
+### Testing
+- Unit tests: [N] cases
+- Integration tests: [N] cases
+- Manual test: [tested manually?]
+
+### Impact
+[Low/Medium/High] — [short description]
+
+### Reviewer notes
+[Anything special for the reviewer to notice]
+```
+
+**Peer reviewer checks:**
+- Code logic matches requirement document
+- Tests are sufficient and meaningful
+- No security issues
+- Acceptable performance
+- Follows team conventions
+
+**Gate 5 Output:**
+- PR created with full description
+- Peer reviewer APPROVED
+- Merged into main/develop
+
+---
+
+## Workflow by Task Type
+
+### Bug Fix
+```
+Gate 1 (AI analyzes bug: root cause hypothesis + solution + impact + estimate)
+→ Gate 2 (implementation plan: test reproduce bug → fix → verify)
+→ Gate 3 (systematic-debugging + investigate-bug + TDD fix)
+→ Gate 4 (verify fix + no regression)
+→ Gate 5 (peer review + PR)
+```
+
+### Feature
+```
+Gate 1 (AI analyzes feature: architecture + solution options + impact + estimate)
+→ Gate 2 (implementation plan: TDD task breakdown)
+→ Gate 3 (TDD: test first, implement, subagent if complex)
+→ Gate 4 (verify all AC done + impact check)
+→ Gate 5 (peer review + PR)
+```
+
+### Investigation
+```
+Gate 1 (AI investigates: analyze scope, trace code, document findings + recommendations)
+→ DEV reviews → APPROVED
+→ DONE (no Gates 2-5, create new ticket if action needed)
+```
+
+### Refactor
+```
+Gate 1 (AI analyzes: current state, target state, impact + estimate)
+→ Gate 2 (implementation plan: ensure tests cover behavior → refactor steps)
+→ Gate 3 (TDD: cover behavior → refactor → tests green)
+→ Gate 4 (verify no regressions)
+→ Gate 5 (peer review + PR)
+```
+
+### Impact Analysis
+```
+Gate 1 (AI analyzes: dependency map, risk level, breaking changes, recommendations)
+→ DEV reviews → APPROVED
+→ DONE (no Gates 2-5, implementation needs a separate ticket)
+```
+
+---
+
+## Skills Used in Workflow
+
+| Skill | Gate | Purpose |
+|-------|------|---------|
+| `read-study-requirement` | Gate 1 | AI reads, analyzes, asks questions, outputs requirement doc |
+| `superpowers:systematic-debugging` | Gate 1 (bug) | Trace root cause hypothesis |
+| `generate-spec` | Gate 2 | Create implementation plan |
+| `superpowers:writing-plans` | Gate 2 | Detailed TDD task breakdown |
+| `investigate-bug` | Gate 3 (bug) | Trace data flow per framework |
+| `superpowers:test-driven-development` | Gate 3 | TDD workflow |
+| `superpowers:subagent-driven-development` | Gate 3 (complex) | Parallel implementation |
+| `review-plan` | Gate 4 | Orchestrate self-review |
+| `superpowers:verification-before-completion` | Gate 4 | Verify tests pass |
+| `impact-analysis` | Gate 4 | Check breaking changes |
+| `superpowers:requesting-code-review` | Gate 5 | Peer review workflow |
+
+---
+
+## Commands Reference
+
+```bash
+# Setup (once per project)
+aiflow init --framework spring-boot --adapter backlog
+
+# Per task (2 commands only)
+aiflow use PROJ-33                    # load ticket context (full analysis)
+aiflow use PROJ-33 --fast             # fast mode: lite Gate 1 (< 5 min)
+aiflow use PROJ-33 --full             # force full Gate 1 analysis
+claude                                # AI auto-starts Gate 1
+
+# Optional: generate prompt for Claude Desktop/Web
+aiflow prompt bug-fix                 # generate prompt to paste
+aiflow prompt feature --output p.md   # save prompt to file
+
+# Task switching (multiple tasks in same repo)
+aiflow task status                    # view active + pending tasks
+aiflow task pause                     # pause current task
+aiflow task pause --note "waiting for PM"
+aiflow task switch PROJ-99            # pause current + switch
+aiflow task resume PROJ-33            # resume a paused task
+
+# Utilities
+aiflow context show                   # view active context
+aiflow memory save "key" "value"      # save team knowledge
+aiflow doctor                         # health check
+aiflow guide                          # view quickstart guide
+
+# Telemetry (team leads)
+aiflow telemetry status               # view status
+aiflow telemetry enable               # setup tracking
+aiflow telemetry disable              # disable tracking
+```
+
+---
+
+## Multi-AI Environment Setup
+
+One of the core strengths of `ai-flow-kit` is that the **Gate Workflow** is tool-agnostic. Since state is saved in `.aiflow/context/current.json` and the `plan/` directory, you can switch tools mid-task.
+
+### How to Switch Tools
+1. **Analyze (Gate 1)** using Claude Code CLI (great for deep codebase scans).
+2. **Review** the `requirement.md` file.
+3. **Open Cursor** to perform the coding (Gate 3).
+4. Cursor will automatically read `.cursorrules`, detect the active ticket, and see that Gate 1 is already finished.
+5. Cursor will proceed to Gate 2 or 3 as appropriate.
+
+### Instruction Files Created
+| Tool | File Name | Purpose |
+|------|-----------|---------|
+| Claude Code | `CLAUDE.md` | Primary rules for the CLI tool. |
+| Cursor AI | `.cursorrules` | Project-wide rules for Cursor. |
+| Gemini CLI | `GEMINI.md` | Context for Gemini sessions. |
+| Copilot | `.github/copilot-instructions.md` | Custom instructions for Copilot. |
+
+---
+
+## FAQ
+
+**Q: PM didn't write enough on the ticket, what happens?**
+A: AI at Gate 1 will read what's available, then ask clarifying questions one at a time until the requirement is clear enough to propose a solution.
+
+**Q: Does AI just check format or actually understand the requirement?**
+A: AI actively reads source code, traces data flow, identifies related files, and proposes solutions. It asks questions based on what it finds in the code — not just checking if fields exist.
+
+**Q: Gate 1 is taking too long for a simple ticket. What can I do?**
+A: Use `aiflow use TICKET-ID --fast` before opening Claude. Fast mode skips the Q&A loop and outputs a lean 3-section requirement doc. Best suited for tickets with ≥ 3 clear, measurable acceptance criteria and no ambiguity. Target: Gate 1 done in < 5 minutes.
+
+**Q: Can I skip Gate 2 for simple tasks?**
+A: No. Gate 2 can be brief (simple plan), but DEV must still type "APPROVED" to confirm the approach.
+
+**Q: AI reports test failures at Gate 4, what to do?**
+A: AI will try to fix them before showing DEV. If it can't, it will report the reason and ask for DEV's support.
+
+**Q: What's the difference between a requirement bug and a coding bug?**
+A: Requirement bug = wrong/missing in requirement doc → back to Gate 1. Coding bug = wrong code but correct requirement → fix at Gate 4.
+
+**Q: Who performs peer review (Gate 5)?**
+A: Another developer in the team. Not the code author. The reviewer uses the `superpowers:receiving-code-review` skill.
+
+**Q: Can I work on two tasks in the same repo at the same time?**
+A: Yes. Use `aiflow task pause` to save your current progress, then `aiflow use <new-ticket>` to start the new task. Resume later with `aiflow task resume <ticket-id>`. The gate progress is saved automatically — Claude will resume from the correct gate instead of restarting Gate 1.
+
+**Q: If I resume a task, will Claude know which gate to start at?**
+A: Yes. The SessionStart hook reads `.aiflow/tasks/<taskId>/task-state.json` and injects gate-aware instructions. If Gate 1 was already approved, Claude will skip to Gate 2, and so on.
+**Q: Can I resume a Gate 3 (Code Generation) task in a new chatbox?**
+A: Yes. Gate 3 progress is saved via `[x]` checkboxes in `plan/[id]/plan.md`. If you open a new chatbox and say "continue", the AI will automatically skip completed tasks and pick up exactly where it left off.
+
+**Q: How does AI estimate effort?**
+A: AI analyzes the scope of changes (files affected, complexity, test requirements) and categorizes: S (< 1h), M (1-4h), L (4-8h), XL (8h+, should split).