@relipa/ai-flow-kit 0.1.5-beta.0 → 0.1.5-beta.1

package/custom/templates/tools/cursor.md

@@ -1,12 +1,12 @@
-# Cursor AI Project Rules
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** Always check `.aiflow/context/current.json` and the `plan/` directory before starting any task to understand current context and progress.
-
-If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+# Cursor AI Project Rules
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** Always check `.aiflow/context/current.json` and the `04.Coding/` docs directory before starting any task to understand current context and progress.
+
+If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/gemini.md

@@ -1,22 +1,22 @@
-# Gemini AI System Instructions
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `plan/` directory for existing progress.
-
-If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
-- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
-
-## Telemetry Command (detect once, use everywhere)
-
-Before the first gate, run this to detect the correct `ak` command for your environment:
-```bash
-command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
-```
-Use whichever prints (e.g. `ak` on native Linux/Mac/Windows, `ak.cmd` on WSL without ak installed).
-All `ak gate ...` examples below assume the detected command. Substitute accordingly.
+# Gemini AI System Instructions
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `04.Coding/` docs directory for existing progress.
+
+If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
+
+## Telemetry Command (detect once, use everywhere)
+
+Before the first gate, run this to detect the correct `ak` command for your environment:
+```bash
+command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
+```
+Use whichever prints (e.g. `ak` on native Linux/Mac/Windows, `ak.cmd` on WSL without ak installed).
+All `ak gate ...` examples below assume the detected command. Substitute accordingly.

package/custom/templates/tools/generic.md

@@ -1,17 +1,17 @@
-# AI System Instructions
-
-You are an expert AI assistant. Follow the project's Gate Workflow and Team Rules strictly.
-
-## Context Awareness
-- **Ticket context**: `.aiflow/context/current.json`
-- **Task progress**: `plan/[ticket-id]/`
-- **Rules**: `.rules/`
-
-Follow the gated workflow and rules defined below.
-
-If Gate 1 does not start automatically, please start it when the developer types **"Gate 1"**.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+# AI System Instructions
+
+You are an expert AI assistant. Follow the project's Gate Workflow and Team Rules strictly.
+
+## Context Awareness
+- **Ticket context**: `.aiflow/context/current.json`
+- **Task progress**: `04.Coding/<section>/[functionId]/[ticketId].md`
+- **Rules**: `.rules/`
+
+Follow the gated workflow and rules defined below.
+
+If Gate 1 does not start automatically, please start it when the developer types **"Gate 1"**.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/docs/common/AIFLOW.md

@@ -112,7 +112,7 @@ claude                           # open Claude → AI auto-starts Gate 1
 | 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 |
+| 5 | Write `04.Coding/01.Requirements/[functionId]/[ticketId].md` | Structured requirement document |
 
 **AI asks questions when:**
 - Business requirements are vague or ambiguous
@@ -121,7 +121,7 @@ claude                           # open Claude → AI auto-starts Gate 1
 - Multiple approaches are possible and need input
 - Impact on existing features is unclear
 
-**Requirement Document Output (`plan/[ticket-id]/requirement.md`):**
+**Requirement Document Output (`04.Coding/01.Requirements/[functionId]/[ticketId].md`):**
 
 ```
 ├── 1. Requirements Summary
@@ -166,13 +166,13 @@ Summary:
 - Approach: [brief description]
 - Files affected: [N] files
 
-→ Review: plan/[ticket-id]/requirement.md
+→ Review: 04.Coding/01.Requirements/[functionId]/[ticketId].md
 → Type APPROVED to proceed
 → Or provide feedback to update
 ```
 
 **Gate 1 Output:**
-- `plan/[ticket-id]/requirement.md` approved by DEV
+- `04.Coding/01.Requirements/[functionId]/[ticketId].md` approved by DEV
 - DEV has typed "APPROVED"
 
 ---
@@ -265,14 +265,14 @@ In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massi
 | 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 |
+| 4 | Create `04.Coding/04.Reviews/[functionId]/[ticketId].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
+04.Coding/04.Reviews/[functionId]/[ticketId].md
 ├── List of changed files + reasons
 ├── Acceptance Criteria → results (Done/Not Done)
 ├── Tests: quantity, coverage
@@ -287,7 +287,7 @@ plan/[ticket-id]/summary.md
 Tests: ✅ [N] passed
 Impact: [Low/Medium/High]
 Checklist: [N/N] ✅
-Summary: plan/[ticket-id]/summary.md
+Summary: 04.Coding/04.Reviews/[functionId]/[ticketId].md
 
 Type APPROVED if OK
 Type BUG: [description] if there are issues
@@ -299,7 +299,7 @@ Type BUG: [description] if there are issues
 - `BUG: requirement bug` → AI updates requirement doc → back to Gate 1
 
 **Gate 4 Output:**
-- `plan/[ticket-id]/summary.md` completed
+- `04.Coding/04.Reviews/[functionId]/[ticketId].md` completed
 - DEV has typed "APPROVED"
 
 ---
@@ -458,7 +458,7 @@ 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.
+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 `04.Coding/` docs directory, you can switch tools mid-task.
 
 ### How to Switch Tools
 1. **Analyze (Gate 1)** using Claude Code CLI (great for deep codebase scans).
@@ -506,7 +506,7 @@ A: Yes. Use `aiflow task pause` to save your current progress, then `aiflow use
 **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.
+A: Yes. Gate 3 progress is saved via `[x]` checkboxes in `04.Coding/02.Plans/[functionId]/[ticketId].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).

package/docs/common/CHANGELOG.md

@@ -14,9 +14,14 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Brainstorming Skill Integration** — Injected `superpowers:brainstorming` into Gate 1 of the BA Create Spec workflow, allowing the AI to actively clarify and brainstorm raw requirements from the backlog.
 - **Mandatory `functionId` Check** — Enforced mandatory `functionId` checks at Gate 1 of all BA and QA workflows (e.g., `create-spec-workflow.md`, `create-testcase-workflow.md`). If missing in the ticket or backlog description, the AI stops and prompts the user to input the ID.
 - **`/coding` slash command** — New `.claude/commands/coding.md`, installed alongside `/create-spec` and `/create-testcase`. Manually loads `.aiflow/context/current.json` and starts (or resumes) the `[DEV] 5-Gate Development Workflow` for `bug-fix` / `feature` / `refactor` / `investigation` / `documentation` tickets. Fixes a gap where those task types had no slash-command fallback: they relied solely on the `SessionStart` hook's auto-start message, which does not re-fire if a ticket is loaded with `ak use` while a Claude Code chat session is already open — leaving phrases like `"start"` with no effect since the AI was never given the ticket context. `ak use`'s "Next Steps" hint and the `gate-workflow.md` / `session-start.js` auto-start tips now also mention `/coding` as the manual fallback.
+- **DEV workflow `functionId` Pre-flight (Gate 1 — Bước 0)** — The `[DEV] 5-Gate Development Workflow` now runs the same mandatory Pre-flight as the BA/QA workflows before writing any output. `functionId` is project-defined with no enforced format (`F-001_User-Login`, `AD06`, `UC-LOGIN` are all valid) and is resolved in priority order: (1) `functionId`/`screenId` field in `.aiflow/context/current.json`; (2) **inferred from the input** — when the task input includes a BA-delivered UC Spec file, the AI reads its content or its containing folder path (e.g. `02.BA-Specs/04.UC-Specs/[functionId]/`) and can consult `04.Coding/00.Overview/_Index.md` / `00.Project-Overview/Function-List.md`, then asks the DEV to **confirm** the candidate ("functionId của task này có phải là [X] không?"); (3) only when nothing can be inferred does it ask the DEV to provide the ID directly. The workflow MUST NOT continue without a `functionId`.
 
 ### Changed
 
+- **DEV 5-Gate output migration: `plan/[ticket-id]/` → `04.Coding/`** — All coding/documentation task outputs now follow the `Coding-Structure.md` convention: `04.Coding/<section>/[functionId]/[ticketId].md` (folder per feature, file per ticket — one feature spans multiple tickets). Gate mapping: Gate 1 → `01.Requirements/`, Gate 2 → `02.Plans/`, Gate 3 → `03.TDD-Notes/` (new artifact: test list written before code + implementation notes), Gate 4 → `04.Reviews/` (replaces `summary.md`), Gate 5 → `05.Pull-Requests/` (new artifact: PR description with links to UC Spec / Test Case / Dev Plan, pushed to remote before creating the PR). Each gate also updates the `04.Coding/00.Overview/_Index.md` tracker (`F-ID | Ticket | Dev | Gate | PR`). The legacy `plan/[ticket-id]/` convention is deprecated. Updated across: `gate-workflow.md` (DEV section), `custom/rules/project-conventions.md` (mandatory override table), skills (`read-study-requirement`, `generate-spec`, `review-plan`, `gate-review`), all 5 tool templates (`claude.md`, `cursor.md`, `copilot.md`, `gemini.md`, `generic.md`), and docs (`AIFLOW.md`, `ai-integration.md`, `workflows/bug-fix.md`, `workflows/feature.md`). ML workflows (`ml-gate-workflow.md`, `ml-conventions.md`) are intentionally NOT migrated yet.
+- **SessionStart hook no longer injects legacy `plan/` paths** — `scripts/hooks/session-start.js` used to inject `Output plan/TASK-xxx/requirement.md` into every auto-start / resume message, overriding whatever the instruction file said (the root cause of outputs still landing in `plan/` even after template updates). The injected Gate 1 instructions (fast + full mode) now include the functionId Pre-flight step and point to `04.Coding/01.Requirements/[functionId]/<taskId>.md`; Gate 2/3 resume messages reference the new paths via the `04.Coding/00.Overview/_Index.md` tracker lookup.
+- **CLI task commands follow the new doc layout** — `scripts/task.js`: new `findTaskDocs()` helper scans `04.Coding/*/*/<taskId>.md` (plus the legacy `plan/<taskId>/` folder) so `ak task reset` / `ak task remove` list and delete gate docs correctly; `detectCurrentGate()` now detects gate progress from the `04.Coding/` sections (with legacy fallback); `ak task next`'s cumulative `task-summary.md` moved from `plan/<taskId>/` to `.aiflow/tasks/<taskId>/` (it is internal task state, not a gate artifact).
+
 - **Testing Skills Consolidation** — Consolidated all 11 testing/QA skills (previously at the root of `custom/skills/`) into the dedicated subfolder `custom/skills/test-skills/`. The skills moved are: `automation-testing`, `coverage-check`, `evidence-aggregation`, `execute-flow`, `generate-test-report`, `generate-testcase`, `log-bug`, `retest-orchestration`, `script-sync`, `test-analysis`, and `pr-impact-analysis`.
 - **English Kebab-Case Naming Standard** — Standardized all skill filenames in `custom/skills/ba-skills/` and `custom/skills/test-skills/` to use English kebab-case naming conventions.
 - **Output Directory Structure Migration** — Standardized output file templates, specs, and generated artifacts to use the new numbered directory architecture: `02.BA-Specs/`, `03.Testing/`, and `04.Coding/`.

package/docs/common/ai-integration.md

@@ -1,53 +1,53 @@
-# Multi-AI Environment Integration
-
-`ai-flow-kit` is designed to be tool-agnostic. While it works best with Claude Code CLI due to deep MCP integration, you can use it with any AI tool.
-
-## Supported Environments
-
-| Tool | Instruction File | Support Level | Key Features |
-|------|------------------|---------------|--------------|
-| **Claude Code** | `CLAUDE.md` | Native (Best) | Auto-triggers, full MCP access, session hooks. |
-| **Cursor** | `.cursorrules` | High | Project-wide rules, `@Codebase` context. |
-| **Gemini CLI** | `GEMINI.md` | Medium | System instructions support. |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | Medium | Inline suggestions, custom instructions. |
-| **OpenCode / Generic** | `AI_INSTRUCTIONS.md` | General | Manual context loading. |
-
----
-
-## Tool-Specific Setup
-
-### 1. Cursor AI
-When you run `aiflow init`, it generates a `.cursorrules` file. 
-- Cursor will automatically read this file to understand the **Gate Workflow**.
-- Use `@Codebase` when you need the AI to search across your whole project.
-- **Resumption**: If you start a task in Claude Code and switch to Cursor, Cursor will see the generated `plan/` files and resume from where you left off.
-
-### 2. Gemini CLI
-Pass `GEMINI.md` as system instructions to your Gemini session.
-- **Tip**: Always ensure the AI reads `.aiflow/context/current.json` first to load the ticket context.
-- Gemini is excellent for large context analysis during Gate 1.
-
-### 3. GitHub Copilot / Codex
-Copilot uses `.github/copilot-instructions.md` to guide its suggestions.
-- This ensures that Copilot's inline completions follow your project's architecture and team rules.
-
----
-
-## Cross-Tool State Resumption
-The "Secret Sauce" of `ai-flow-kit` is its file-based state management:
-
-1. **Context**: Saved in `.aiflow/context/current.json`.
-2. **Progress**: Saved as Markdown docs in `plan/[ticket-id]/`.
-3. **Rules**: Saved in `.rules/`.
-
-Because these are standard files, any AI tool can read them. You can:
-1. Start **Gate 1** (Analysis) in Claude Code.
-2. Review and **Approve** the requirement doc.
-3. Switch to **Cursor** for **Gate 3** (Coding) because you prefer the IDE integrations.
-4. Switch back to **Claude Code** for **Gate 4** (Self-Review) to use its automated testing power.
-
----
-
-## Best Practices
-- **Always Approve Docs**: Ensure `requirement.md` and `plan.md` are approved (you can just type "APPROVED" in the chat or edit the file to say so).
-- **Update Status**: If you make progress in a tool that doesn't have hooks, manually update the `summary.md` or the ticket status.
+# Multi-AI Environment Integration
+
+`ai-flow-kit` is designed to be tool-agnostic. While it works best with Claude Code CLI due to deep MCP integration, you can use it with any AI tool.
+
+## Supported Environments
+
+| Tool | Instruction File | Support Level | Key Features |
+|------|------------------|---------------|--------------|
+| **Claude Code** | `CLAUDE.md` | Native (Best) | Auto-triggers, full MCP access, session hooks. |
+| **Cursor** | `.cursorrules` | High | Project-wide rules, `@Codebase` context. |
+| **Gemini CLI** | `GEMINI.md` | Medium | System instructions support. |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Medium | Inline suggestions, custom instructions. |
+| **OpenCode / Generic** | `AI_INSTRUCTIONS.md` | General | Manual context loading. |
+
+---
+
+## Tool-Specific Setup
+
+### 1. Cursor AI
+When you run `aiflow init`, it generates a `.cursorrules` file. 
+- Cursor will automatically read this file to understand the **Gate Workflow**.
+- Use `@Codebase` when you need the AI to search across your whole project.
+- **Resumption**: If you start a task in Claude Code and switch to Cursor, Cursor will see the generated `04.Coding/` docs and resume from where you left off.
+
+### 2. Gemini CLI
+Pass `GEMINI.md` as system instructions to your Gemini session.
+- **Tip**: Always ensure the AI reads `.aiflow/context/current.json` first to load the ticket context.
+- Gemini is excellent for large context analysis during Gate 1.
+
+### 3. GitHub Copilot / Codex
+Copilot uses `.github/copilot-instructions.md` to guide its suggestions.
+- This ensures that Copilot's inline completions follow your project's architecture and team rules.
+
+---
+
+## Cross-Tool State Resumption
+The "Secret Sauce" of `ai-flow-kit` is its file-based state management:
+
+1. **Context**: Saved in `.aiflow/context/current.json`.
+2. **Progress**: Saved as Markdown docs in `04.Coding/<section>/[functionId]/[ticketId].md`.
+3. **Rules**: Saved in `.rules/`.
+
+Because these are standard files, any AI tool can read them. You can:
+1. Start **Gate 1** (Analysis) in Claude Code.
+2. Review and **Approve** the requirement doc.
+3. Switch to **Cursor** for **Gate 3** (Coding) because you prefer the IDE integrations.
+4. Switch back to **Claude Code** for **Gate 4** (Self-Review) to use its automated testing power.
+
+---
+
+## Best Practices
+- **Always Approve Docs**: Ensure `requirement.md` and `plan.md` are approved (you can just type "APPROVED" in the chat or edit the file to say so).
+- **Update Status**: If you make progress in a tool that doesn't have hooks, manually update the `summary.md` or the ticket status.

package/docs/common/workflows/bug-fix.md

@@ -1,126 +1,126 @@
-# Bug Fix Workflow
-
-> See the full workflow at [AIFLOW.md](../../AIFLOW.md)
-> **Gates must pass in order: 1 → 2 → 3 → 4 → 5**
-
----
-
-## Step 1: Load ticket & AI analyzes (Gate 1)
-
-```bash
-aiflow use PROJ-33 --with-comments    # get both comments — important for bugs
-claude                                # AI auto-starts Gate 1
-```
-
-AI will **automatically**:
-1. Load ticket info + comments from Backlog/Jira
-2. Read source code — trace data flow related to the bug
-3. Use `superpowers:systematic-debugging` to form root cause hypothesis
-4. Ask clarifying questions if reproduction steps are unclear
-5. Output `plan/[ticket-id]/requirement.md` containing:
-   - Bug analysis (current vs expected behavior)
-   - **Root cause hypothesis** with evidence from source code
-   - **Proposed fix approach** (with alternatives if applicable)
-   - **Impact analysis** — will the fix break anything else?
-   - **Effort estimate** (S/M/L/XL)
-   - Testing plan (reproduce bug + verify fix)
-
-**PM needs to prepare on the ticket:**
-```markdown
-## Description
-Bug description: current behavior vs expected.
-
-## Acceptance Criteria
-- [ ] Bug no longer occurs
-- [ ] [Other specific conditions]
-
-## Reproduction Steps
-1. [Step 1]
-2. [Step 2]
-3. Actual result: [what error, what screen]
-4. Expected result: [...]
-
-## Context
-Error log (if any), environment (browser, OS, app version).
-```
-
-**If reproduction steps are unclear:** AI will ask based on what it found in the code.
-
-**When satisfied with the requirement document, type:**
-```
-APPROVED
-```
-
----
-
-## Step 2: Review Implementation Plan (Gate 2)
-
-AI generates:
-- TDD plan: write test to reproduce bug → implement fix → verify
-- Minimal fix approach (only edit the bug location)
-
-**When agreed, type:**
-```
-APPROVED
-```
-
----
-
-## Step 3: AI Fix Code (Gate 3)
-
-AI performs in the following order:
-1. `superpowers:systematic-debugging` — confirm root cause
-2. `investigate-bug` skill — trace Controller→Service→Repository to identify the bug layer
-3. Write test to reproduce bug → run → confirm FAIL
-4. Implement fix → tests PASS
-5. Commit
-
-**Principle:** Minimal fix — only edit the bug location, no extra changes.
-
----
-
-## Step 4: Review Summary (Gate 4)
-
-AI runs:
-1. `superpowers:verification-before-completion` — all tests PASS (including old tests)
-2. `impact-analysis` — fix doesn't cause new bugs elsewhere
-3. Create `plan/[ticket-id]/summary.md`
-
-**If OK, type:**
-```
-APPROVED
-```
-
-**If the fix is incorrect:**
-```
-BUG: [describe specifically what is wrong]
-```
-
----
-
-## Step 5: Peer Review & PR (Gate 5)
-
-```bash
-git push origin fix/PROJ-33-description
-# PR title: fix: [PROJ-33] Short description
-```
-
-Commit message format:
-```
-fix: [PROJ-33] Payment processing timeout
-
-Root cause: API timeout too short (5s), needs at least 10s
-Fix: Increase timeout + add retry logic
-
-Closes PROJ-33
-```
-
----
-
-## Completion Checklist
-
-- [ ] Gate 1 APPROVED — requirement doc with root cause, fix approach, impact, estimate
-- [ ] Gate 2 APPROVED — implementation plan confirmed
-- [ ] Gate 3 done — test reproduce bug + fix → green
-- [ ] Gate 4 APPROVED — no regression
-- [ ] Gate 5 done — PR merged
+# Bug Fix Workflow
+
+> See the full workflow at [AIFLOW.md](../../AIFLOW.md)
+> **Gates must pass in order: 1 → 2 → 3 → 4 → 5**
+
+---
+
+## Step 1: Load ticket & AI analyzes (Gate 1)
+
+```bash
+aiflow use PROJ-33 --with-comments    # get both comments — important for bugs
+claude                                # AI auto-starts Gate 1
+```
+
+AI will **automatically**:
+1. Load ticket info + comments from Backlog/Jira
+2. Read source code — trace data flow related to the bug
+3. Use `superpowers:systematic-debugging` to form root cause hypothesis
+4. Ask clarifying questions if reproduction steps are unclear
+5. Output `04.Coding/01.Requirements/[functionId]/[ticketId].md` containing:
+   - Bug analysis (current vs expected behavior)
+   - **Root cause hypothesis** with evidence from source code
+   - **Proposed fix approach** (with alternatives if applicable)
+   - **Impact analysis** — will the fix break anything else?
+   - **Effort estimate** (S/M/L/XL)
+   - Testing plan (reproduce bug + verify fix)
+
+**PM needs to prepare on the ticket:**
+```markdown
+## Description
+Bug description: current behavior vs expected.
+
+## Acceptance Criteria
+- [ ] Bug no longer occurs
+- [ ] [Other specific conditions]
+
+## Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. Actual result: [what error, what screen]
+4. Expected result: [...]
+
+## Context
+Error log (if any), environment (browser, OS, app version).
+```
+
+**If reproduction steps are unclear:** AI will ask based on what it found in the code.
+
+**When satisfied with the requirement document, type:**
+```
+APPROVED
+```
+
+---
+
+## Step 2: Review Implementation Plan (Gate 2)
+
+AI generates:
+- TDD plan: write test to reproduce bug → implement fix → verify
+- Minimal fix approach (only edit the bug location)
+
+**When agreed, type:**
+```
+APPROVED
+```
+
+---
+
+## Step 3: AI Fix Code (Gate 3)
+
+AI performs in the following order:
+1. `superpowers:systematic-debugging` — confirm root cause
+2. `investigate-bug` skill — trace Controller→Service→Repository to identify the bug layer
+3. Write test to reproduce bug → run → confirm FAIL
+4. Implement fix → tests PASS
+5. Commit
+
+**Principle:** Minimal fix — only edit the bug location, no extra changes.
+
+---
+
+## Step 4: Review Summary (Gate 4)
+
+AI runs:
+1. `superpowers:verification-before-completion` — all tests PASS (including old tests)
+2. `impact-analysis` — fix doesn't cause new bugs elsewhere
+3. Create `04.Coding/04.Reviews/[functionId]/[ticketId].md`
+
+**If OK, type:**
+```
+APPROVED
+```
+
+**If the fix is incorrect:**
+```
+BUG: [describe specifically what is wrong]
+```
+
+---
+
+## Step 5: Peer Review & PR (Gate 5)
+
+```bash
+git push origin fix/PROJ-33-description
+# PR title: fix: [PROJ-33] Short description
+```
+
+Commit message format:
+```
+fix: [PROJ-33] Payment processing timeout
+
+Root cause: API timeout too short (5s), needs at least 10s
+Fix: Increase timeout + add retry logic
+
+Closes PROJ-33
+```
+
+---
+
+## Completion Checklist
+
+- [ ] Gate 1 APPROVED — requirement doc with root cause, fix approach, impact, estimate
+- [ ] Gate 2 APPROVED — implementation plan confirmed
+- [ ] Gate 3 done — test reproduce bug + fix → green
+- [ ] Gate 4 APPROVED — no regression
+- [ ] Gate 5 done — PR merged