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

package/docs/common/workflows/feature.md

@@ -1,123 +1,123 @@
-# Feature Development 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                    # from Backlog/Jira
-claude                                # AI auto-starts Gate 1
-```
-
-AI will **automatically**:
-1. Load ticket info from Backlog/Jira
-2. Read source code — understand architecture, related files, patterns
-3. Ask clarifying questions if anything is unclear (one at a time)
-4. Output `plan/[ticket-id]/requirement.md` containing:
-   - Requirements summary (AI's understanding)
-   - Source code analysis (related files, data flow)
-   - **Proposed solution** with options and recommendation
-   - **Impact analysis** — affected areas, risks
-   - **Effort estimate** (S/M/L/XL)
-   - Testing plan
-
-**PM needs to prepare on the ticket:**
-```markdown
-## Description
-Clear business requirement. Who uses it, and for what purpose.
-
-## Acceptance Criteria
-- [ ] [Condition for completion 1]
-- [ ] [Condition for completion 2]
-
-## Mockup / Wireframe
-[Link or UI description]
-
-## Context
-Constraints, business rules specially requiring attention.
-```
-
-**If ticket content is unclear:** AI will ask questions based on source code analysis — not just checking format.
-
-**When satisfied with the requirement document, type:**
-```
-APPROVED
-```
-
----
-
-## Step 2: Review Implementation Plan (Gate 2)
-
-AI generates a detailed implementation plan:
-- TDD task breakdown (test first → implement → verify)
-- Commit strategy (small, focused commits)
-- Test commands
-
-**When agreed, type:**
-```
-APPROVED
-```
-
-**CODE WILL NOT BE GENERATED BEFORE RECEIVING "APPROVED".**
-
----
-
-## Step 3: AI Generate Code (Gate 3)
-
-AI performs automatically:
-1. Complex feature (3+ files): `superpowers:subagent-driven-development`
-2. Write tests FIRST → run → confirm FAIL
-3. Implement → tests PASS
-4. Commit each small step
-
-Developer doesn't need to do anything at this step — just monitor.
-
----
-
-## Step 4: Review Summary (Gate 4)
-
-AI runs:
-1. `superpowers:verification-before-completion` — all tests PASS
-2. `impact-analysis` — no breaking changes outside of scope
-3. Review checklist — all items ticked
-4. Create `plan/[ticket-id]/summary.md`
-
-AI displays summary and waits for developer review.
-
-**If OK, type:**
-```
-APPROVED
-```
-
-**If there are bugs, type:**
-```
-BUG: [specific description]
-```
-- Coding bug → AI fixes → repeat Gate 4
-- Requirement bug → AI returns to Gate 1, update requirement doc
-
----
-
-## Step 5: Peer Review & PR (Gate 5)
-
-AI invokes `superpowers:requesting-code-review` and guides PR creation.
-
-```bash
-git push origin feature/PROJ-33-feature-name
-# Create PR with full description following the template in AIFLOW.md
-```
-
-Peer reviewer uses the `superpowers:receiving-code-review` skill during review.
-
----
-
-## Completion Checklist
-
-- [ ] Gate 1 APPROVED — requirement doc with solution, impact, estimate
-- [ ] Gate 2 APPROVED — implementation plan confirmed by developer
-- [ ] Gate 3 done — code + tests are green
-- [ ] Gate 4 APPROVED — summary + checklist complete
-- [ ] Gate 5 done — PR is peer-reviewed and merged
+# Feature Development 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                    # from Backlog/Jira
+claude                                # AI auto-starts Gate 1
+```
+
+AI will **automatically**:
+1. Load ticket info from Backlog/Jira
+2. Read source code — understand architecture, related files, patterns
+3. Ask clarifying questions if anything is unclear (one at a time)
+4. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` containing:
+   - Requirements summary (AI's understanding)
+   - Source code analysis (related files, data flow)
+   - **Proposed solution** with options and recommendation
+   - **Impact analysis** — affected areas, risks
+   - **Effort estimate** (S/M/L/XL)
+   - Testing plan
+
+**PM needs to prepare on the ticket:**
+```markdown
+## Description
+Clear business requirement. Who uses it, and for what purpose.
+
+## Acceptance Criteria
+- [ ] [Condition for completion 1]
+- [ ] [Condition for completion 2]
+
+## Mockup / Wireframe
+[Link or UI description]
+
+## Context
+Constraints, business rules specially requiring attention.
+```
+
+**If ticket content is unclear:** AI will ask questions based on source code analysis — not just checking format.
+
+**When satisfied with the requirement document, type:**
+```
+APPROVED
+```
+
+---
+
+## Step 2: Review Implementation Plan (Gate 2)
+
+AI generates a detailed implementation plan:
+- TDD task breakdown (test first → implement → verify)
+- Commit strategy (small, focused commits)
+- Test commands
+
+**When agreed, type:**
+```
+APPROVED
+```
+
+**CODE WILL NOT BE GENERATED BEFORE RECEIVING "APPROVED".**
+
+---
+
+## Step 3: AI Generate Code (Gate 3)
+
+AI performs automatically:
+1. Complex feature (3+ files): `superpowers:subagent-driven-development`
+2. Write tests FIRST → run → confirm FAIL
+3. Implement → tests PASS
+4. Commit each small step
+
+Developer doesn't need to do anything at this step — just monitor.
+
+---
+
+## Step 4: Review Summary (Gate 4)
+
+AI runs:
+1. `superpowers:verification-before-completion` — all tests PASS
+2. `impact-analysis` — no breaking changes outside of scope
+3. Review checklist — all items ticked
+4. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`
+
+AI displays summary and waits for developer review.
+
+**If OK, type:**
+```
+APPROVED
+```
+
+**If there are bugs, type:**
+```
+BUG: [specific description]
+```
+- Coding bug → AI fixes → repeat Gate 4
+- Requirement bug → AI returns to Gate 1, update requirement doc
+
+---
+
+## Step 5: Peer Review & PR (Gate 5)
+
+AI invokes `superpowers:requesting-code-review` and guides PR creation.
+
+```bash
+git push origin feature/PROJ-33-feature-name
+# Create PR with full description following the template in AIFLOW.md
+```
+
+Peer reviewer uses the `superpowers:receiving-code-review` skill during review.
+
+---
+
+## Completion Checklist
+
+- [ ] Gate 1 APPROVED — requirement doc with solution, impact, estimate
+- [ ] Gate 2 APPROVED — implementation plan confirmed by developer
+- [ ] Gate 3 done — code + tests are green
+- [ ] Gate 4 APPROVED — summary + checklist complete
+- [ ] Gate 5 done — PR is peer-reviewed and merged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.5-beta.0",
+  "version": "0.1.5",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/docs-repo.js

@@ -0,0 +1,49 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+
+// AK-Docs (per-project docs) and Shared-Docs (cross-project templates) are
+// fixed-name folders living directly under the workspace root — the folder
+// opened in the editor, which contains one or more source repos plus these
+// two docs repos as siblings. `ak` is run from that root, so projectDir
+// (process.cwd()) already IS the root — see docs/internal/Project-Structure.md.
+const DOC_REPOS = [
+    { name: 'AK-Docs', purpose: 'tài liệu dự án (Requirements, Specs, Test Cases, Coding docs...)' },
+    { name: 'Shared-Docs', purpose: 'template dùng chung cho tất cả dự án (Spec, QA, Test Case, Test Report...)' },
+];
+
+function resolveDocsRepoPath(projectDir, repoName) {
+    return path.join(projectDir, repoName);
+}
+
+async function syncDocsRepo(projectDir, repoName, purpose) {
+    const repoPath = resolveDocsRepoPath(projectDir, repoName);
+
+    if (!(await fs.pathExists(repoPath))) {
+        console.log(chalk.yellow(`⚠ ${repoName}/ chưa tồn tại tại ${repoPath} (${purpose}). Hãy clone repo này vào thư mục root.`));
+        return;
+    }
+
+    if (!(await fs.pathExists(path.join(repoPath, '.git')))) {
+        console.log(chalk.yellow(`⚠ ${repoName}/ tồn tại tại ${repoPath} nhưng không phải git repo — bỏ qua pull.`));
+        return;
+    }
+
+    console.log(chalk.cyan(`\n⟳ Pulling latest ${repoName}...`));
+    try {
+        execSync('git pull', { cwd: repoPath, stdio: 'inherit' });
+        console.log(chalk.green(`✓ ${repoName} đã cập nhật mới nhất.`));
+    } catch (err) {
+        console.log(chalk.red(`✗ Không thể pull ${repoName}: ${err.message}`));
+    }
+}
+
+async function syncDocsRepos(projectDir) {
+    console.log(chalk.blue('\nĐồng bộ AK-Docs / Shared-Docs...'));
+    for (const repo of DOC_REPOS) {
+        await syncDocsRepo(projectDir, repo.name, repo.purpose);
+    }
+}
+
+module.exports = { syncDocsRepos, resolveDocsRepoPath, DOC_REPOS };

package/scripts/hooks/session-start.js

@@ -215,14 +215,16 @@ function buildContextPrompt(ctx, taskState) {
 
         if (currentGate === 2) {
             lines.push('Gate 1 is already APPROVED. The requirement document is at:');
-            lines.push(`  plan/${ctx.taskId}/requirement.md`);
+            lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  ([functionId] — look it up in AK-Docs/04.Coding/00.Overview/_Index.md or the folder containing ${ctx.taskId}.md)`);
             lines.push('');
             lines.push('Proceed to Gate 2: create the implementation plan.');
             lines.push(buildModeInstruction(mode, 2));
         } else if (currentGate === 3) {
             lines.push('Gates 1 and 2 are already APPROVED. Plans are at:');
-            lines.push(`  plan/${ctx.taskId}/requirement.md`);
-            lines.push(`  plan/${ctx.taskId}/plan.md`);
+            lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  AK-Docs/04.Coding/02.Plans/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  ([functionId] — look it up in AK-Docs/04.Coding/00.Overview/_Index.md)`);
             lines.push('');
             lines.push('Proceed to Gate 3: implement code following the plan (TDD).');
             lines.push(buildModeInstruction(mode, 3));
@@ -246,17 +248,19 @@ function buildContextPrompt(ctx, taskState) {
 
         if (mode === 'fast') {
             lines.push('**MODE: fast** — Use the FAST TRACK path in the skill:');
+            lines.push('- Pre-flight: determine functionId first (from context / input UC Spec file / ask DEV to confirm) — see the DEV workflow Pre-flight step');
             lines.push('- Read ticket + identify changed files only (no deep source scan)');
             lines.push('- Skip Q&A unless there is a critical blocking ambiguity');
-            lines.push('- Output a lite requirement doc (Sections 1, 3, 5 only)');
+            lines.push('- Output a lite requirement doc (Sections 1, 3, 5 only) to AK-Docs/04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
             lines.push('- Target: Gate 1 complete in < 5 minutes');
         } else {
             lines.push('Gate 1 process:');
+            lines.push('0. Pre-flight: determine functionId (from context / input UC Spec file / ask DEV to confirm) + ensure AK-Docs/04.Coding/ tree exists — see the DEV workflow Pre-flight step. DO NOT continue without functionId.');
             lines.push('1. Read the ticket context above');
             lines.push('2. Read CLAUDE.md — understand project architecture and conventions');
             lines.push('3. Read source code — identify related files, data flow, patterns');
             lines.push('4. If anything is unclear — ask ONE question at a time');
-            lines.push('5. Output plan/' + ctx.taskId + '/requirement.md');
+            lines.push('5. Output AK-Docs/04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
             lines.push('6. Display GATE 1 prompt and wait for APPROVED');
         }
 

package/scripts/init.js

@@ -3,6 +3,7 @@ const path = require('path');
 const os = require('os');
 const chalk = require('chalk');
 const { input, checkbox, confirm } = require('@inquirer/prompts');
+const { syncDocsRepos } = require('./docs-repo');
 
 const PKG_DIR = path.join(__dirname, '..');
 const GLOBAL_AIFLOW_DIR = path.join(os.homedir(), '.aiflow');
@@ -752,7 +753,6 @@ async function ensureAiflowGitignored(projectDir) {
     const gitignorePath = path.join(projectDir, '.gitignore');
     const entries = [
         '.aiflow/',
-        'plan/',
         '.claude/',
         '.rules/',
         '.mcp.json',
@@ -1048,6 +1048,9 @@ async function init(options) {
     try {
         console.log(chalk.blue(`Initializing ai-flow-kit (v${PKG_VERSION})...`));
 
+        // ── Sync AK-Docs / Shared-Docs sibling repos ──────────────────
+        await syncDocsRepos(projectDir);
+
         // ── Auto-detect or prompt for framework if not supplied ──────
         if (frameworks.length === 0) {
             const stateFilePath = path.join(aiflowDir, 'state.json');

package/scripts/prompt.js

@@ -25,7 +25,7 @@ AI must:
 1. Load ticket context + read source code related to the bug
 2. Trace data flow to form root cause hypothesis (\`superpowers:systematic-debugging\`)
 3. If unclear → ask ONE question at a time, wait for reply
-4. Output \`plan/[ticket-id]/requirement.md\` with:
+4. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Bug analysis (current vs expected behavior)
    - Root cause hypothesis with evidence from source code
    - Proposed fix approach (options if multiple)
@@ -52,7 +52,7 @@ Only runs after Gate 2 APPROVED.
 1. \`superpowers:verification-before-completion\` — all tests PASS (including old tests)
 2. \`impact-analysis\` skill — fix doesn't cause new bugs elsewhere
 3. Tick \`custom/rules/review-checklist.md\`
-4. Create \`plan/[ticket-id]/summary.md\`
+4. Create \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
 - Display: "GATE 4: type APPROVED or BUG: [description]"
 - Coding bug → fix → repeat Gate 4
 - Requirement bug → back to Gate 1
@@ -77,7 +77,7 @@ AI must:
 2. Investigate related files, data flow, existing patterns
 3. Propose 2-3 solution approaches using Q&A if the problem is complex
 4. If unclear → ask ONE question at a time, wait for reply
-5. Output \`plan/[ticket-id]/requirement.md\` with:
+5. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Requirements summary (AI's understanding in technical language)
    - Source code analysis (related files, data flow, patterns)
    - Proposed solution with options (recommended + alternatives)
@@ -104,7 +104,7 @@ Only runs after Gate 2 APPROVED.
 1. \`superpowers:verification-before-completion\` — all tests PASS
 2. \`impact-analysis\` skill — no regressions
 3. Tick \`custom/rules/review-checklist.md\`
-4. Create \`plan/[ticket-id]/summary.md\`
+4. Create \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
 - Display: "GATE 4: type APPROVED or BUG: [description]"
 - Coding bug → fix → repeat Gate 4
 - Requirement bug → back to Gate 1
@@ -129,7 +129,7 @@ AI must:
 2. **INVOKE:** \`superpowers:systematic-debugging\` — trace through all layers
 3. **INVOKE:** \`investigate-bug\` skill — trace data flow through all layers
 4. If unclear → ask ONE question at a time
-5. Output \`plan/[ticket-id]/requirement.md\` with:
+5. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Investigation scope and approach
    - Source code analysis (all related files traced)
    - Findings with evidence (log output, code references)
@@ -156,7 +156,7 @@ AI must:
 1. Load ticket context + read source code to understand current state
 2. **INVOKE:** \`impact-analysis\` skill — map ALL callers and dependants
 3. If unclear → ask ONE question at a time
-4. Output \`plan/[ticket-id]/requirement.md\` with:
+4. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Current state analysis (what exists, what's wrong)
    - Target state (what it should look like after refactor)
    - Proposed approach (step-by-step refactor strategy)
@@ -182,7 +182,7 @@ Only runs after Gate 2 APPROVED.
 1. \`superpowers:verification-before-completion\` — all tests PASS
 2. \`impact-analysis\` skill — verify no regressions
 3. Tick \`custom/rules/review-checklist.md\`
-4. Create \`plan/[ticket-id]/summary.md\`
+4. Create \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
 - Display: "GATE 4: type APPROVED or BUG: [description]"
 
 ### GATE 5 — Peer Review & Done
@@ -203,7 +203,7 @@ AI must:
 1. Load ticket context + read source code thoroughly
 2. Map all dependencies, callers, services, jobs, tests
 3. If unclear → ask ONE question at a time
-4. Output \`plan/[ticket-id]/requirement.md\` with:
+4. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Change description and scope
    - Dependency map (all callers, services, jobs, tests)
    - Impact level: 🟢 Low / 🟡 Medium / 🔴 High / 🔥 Critical
@@ -229,7 +229,7 @@ AI must:
 1. Load ticket context + read source code thoroughly
 2. Understand what needs to be tested (unit, integration, e2e)
 3. If unclear → ask ONE question at a time
-4. Output \`plan/[ticket-id]/requirement.md\` with:
+4. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Test scope and strategy
    - Test cases to cover (happy path + edge cases + failure cases)
    - Source code references
@@ -239,7 +239,7 @@ AI must:
 ### GATE 2 — Implementation Plan
 **INVOKE:** \`generate-spec\` skill, then \`superpowers:writing-plans\`
 - Create detailed TDD test implementation plan.
-- Output \`plan/[ticket-id]/plan.md\`.
+- Output \`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md\`.
 - Display: "GATE 2 PAUSED: type APPROVED to start coding".
 
 ### GATE 3 — Write Tests (TDD)
@@ -265,7 +265,7 @@ AI must:
 1. Load ticket context + read source code
 2. Understand what needs to be documented and for whom
 3. If unclear → ask ONE question at a time
-4. Output \`plan/[ticket-id]/requirement.md\` with:
+4. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
    - Documentation scope and target audience
    - Content outline (sections to cover)
    - Source code references

package/scripts/task.js

@@ -2,12 +2,14 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 const { confirm } = require('@inquirer/prompts');
+const { resolveDocsRepoPath } = require('./docs-repo');
 
 const PROJECT_DIR   = process.cwd();
 const AIFLOW_DIR    = path.join(PROJECT_DIR, '.aiflow');
 const CONTEXT_DIR   = path.join(AIFLOW_DIR, 'context');
 const CURRENT_FILE  = path.join(CONTEXT_DIR, 'current.json');
 const TASKS_DIR     = path.join(AIFLOW_DIR, 'tasks');
+const CODING_DIR    = path.join(resolveDocsRepoPath(PROJECT_DIR, 'AK-Docs'), '04.Coding');
 
 // ──────────────────────────────────────────────────────────────
 // Entry point
@@ -206,12 +208,8 @@ async function resetTask(taskId) {
     }
 
     const taskState = await fs.readJson(statePath);
-    const planDir   = path.join(PROJECT_DIR, 'plan', taskId);
-    const planFiles = [];
-    if (await fs.pathExists(planDir)) {
-        const entries = await fs.readdir(planDir);
-        for (const f of entries) planFiles.push(path.join('plan', taskId, f));
-    }
+    const docPaths  = await findTaskDocs(taskId);
+    const planFiles = docPaths.map(p => path.relative(PROJECT_DIR, p));
 
     // Show what will happen
     console.log(chalk.cyan(`\nReset task: ${taskId}\n`));
@@ -220,12 +218,12 @@ async function resetTask(taskId) {
     console.log(chalk.gray(`    Gate: ${taskState.currentGate} → 1  |  Approvals cleared  |  Status: active`));
 
     const deletePlan = planFiles.length > 0 && await confirm({
-        message: `Also delete ${planFiles.length} plan file(s) in plan/${taskId}/?`,
+        message: `Also delete ${planFiles.length} gate doc file(s) (AK-Docs/04.Coding/ + legacy plan/) for ${taskId}?`,
         default: false,
     });
 
     if (deletePlan) {
-        console.log(chalk.gray('\n  Plan files to delete:'));
+        console.log(chalk.gray('\n  Gate doc files to delete:'));
         for (const f of planFiles) console.log(chalk.gray(`  • ${f}`));
     }
 
@@ -252,10 +250,13 @@ async function resetTask(taskId) {
         await fs.copy(ctxPath, CURRENT_FILE, { overwrite: true });
     }
 
-    if (deletePlan) await fs.remove(planDir);
+    if (deletePlan) {
+        for (const p of docPaths) await fs.remove(p);
+        await fs.remove(path.join(PROJECT_DIR, 'plan', taskId));
+    }
 
     console.log(chalk.green(`✓ Task ${taskId} reset to Gate 1.`));
-    if (deletePlan) console.log(chalk.gray(`  Deleted plan/${taskId}/`));
+    if (deletePlan) console.log(chalk.gray(`  Deleted ${planFiles.length} gate doc file(s).`));
     console.log(chalk.gray('  Open Claude to start Gate 1: claude'));
 }
 
@@ -271,9 +272,9 @@ async function removeTask(taskId) {
 
     const isActive  = await fs.pathExists(CURRENT_FILE) &&
         ((await fs.readJson(CURRENT_FILE).catch(() => ({}))).taskId === taskId);
-    const planDir   = path.join(PROJECT_DIR, 'plan', taskId);
-    const hasPlan   = await fs.pathExists(planDir);
-    const planFiles = hasPlan ? await fs.readdir(planDir) : [];
+    const docPaths  = await findTaskDocs(taskId);
+    const hasPlan   = docPaths.length > 0;
+    const planFiles = docPaths.map(p => path.relative(PROJECT_DIR, p));
 
     // Show what will be deleted
     console.log(chalk.cyan(`\nRemove task: ${taskId}\n`));
@@ -281,8 +282,8 @@ async function removeTask(taskId) {
     console.log(chalk.gray(`  • .aiflow/tasks/${taskId}/  (context snapshot + gate state)`));
     if (isActive) console.log(chalk.gray(`  • .aiflow/context/current.json  (this is the active task)`));
     if (hasPlan) {
-        console.log(chalk.gray(`  • plan/${taskId}/  (${planFiles.length} file(s)):`));
-        for (const f of planFiles) console.log(chalk.gray(`      - plan/${taskId}/${f}`));
+        console.log(chalk.gray(`  • Gate docs (${planFiles.length} file(s)):`));
+        for (const f of planFiles) console.log(chalk.gray(`      - ${f}`));
     }
 
     console.log();
@@ -294,7 +295,10 @@ async function removeTask(taskId) {
 
     await fs.remove(taskDir);
     if (isActive) await fs.remove(CURRENT_FILE);
-    if (hasPlan)  await fs.remove(planDir);
+    if (hasPlan) {
+        for (const p of docPaths) await fs.remove(p);
+        await fs.remove(path.join(PROJECT_DIR, 'plan', taskId));
+    }
 
     console.log(chalk.green(`✓ Task ${taskId} removed.`));
 }
@@ -348,23 +352,21 @@ async function nextGate(taskId) {
     // Clear current context so no task is "active"
     await fs.remove(CURRENT_FILE);
 
-    // Generate cumulative task-summary.md
-    const planDir = path.join(PROJECT_DIR, 'plan', resolvedId);
-    await fs.ensureDir(planDir);
-    const summaryPath = path.join(planDir, 'task-summary.md');
+    // Generate cumulative task-summary.md (task-internal state — lives in .aiflow/, not gate docs)
+    const summaryPath = path.join(TASKS_DIR, resolvedId, 'task-summary.md');
     const summaryContent = await generateMarkdownSummary(taskState);
     await fs.writeFile(summaryPath, summaryContent, 'utf-8');
 
     const taskType = existing.taskType || 'feature';
     console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
-    console.log(chalk.gray(`  Summary saved to: plan/${resolvedId}/task-summary.md`));
+    console.log(chalk.gray(`  Summary saved to: .aiflow/tasks/${resolvedId}/task-summary.md`));
     const nextLabel = gateLabel(nextGateNum, taskType);
     console.log(chalk.white(`\n  Next: Gate ${nextGateNum} — ${nextLabel}`));
     console.log(chalk.cyan(`\n  To continue in a fresh session (Recommended to avoid context pollution):`));
     console.log(chalk.gray(`    1. Open a NEW chatbox or terminal session.`));
     console.log(chalk.gray(`    2. Run: aiflow task resume ${resolvedId} (to load context).`));
     console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
-    console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in plan.md.`));
+    console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in the Gate 2 plan doc (AK-Docs/04.Coding/02.Plans/).`));
     console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
     console.log();
 }
@@ -373,6 +375,37 @@ async function nextGate(taskId) {
 // Internal helpers
 // ──────────────────────────────────────────────────────────────
 
+/**
+ * Find gate output docs for a task under AK-Docs/04.Coding/<section>/<functionId>/<taskId>.md
+ * (new convention) plus the legacy plan/<taskId>/ folder. Returns absolute paths.
+ */
+async function findTaskDocs(taskId) {
+    const results = [];
+
+    if (await fs.pathExists(CODING_DIR)) {
+        const sections = await fs.readdir(CODING_DIR, { withFileTypes: true }).catch(() => []);
+        for (const section of sections) {
+            if (!section.isDirectory()) continue;
+            const sectionDir = path.join(CODING_DIR, section.name);
+            const featureDirs = await fs.readdir(sectionDir, { withFileTypes: true }).catch(() => []);
+            for (const feature of featureDirs) {
+                if (!feature.isDirectory()) continue;
+                const docPath = path.join(sectionDir, feature.name, `${taskId}.md`);
+                if (await fs.pathExists(docPath)) results.push(docPath);
+            }
+        }
+    }
+
+    // Legacy convention: plan/<taskId>/
+    const legacyDir = path.join(PROJECT_DIR, 'plan', taskId);
+    if (await fs.pathExists(legacyDir)) {
+        const entries = await fs.readdir(legacyDir).catch(() => []);
+        for (const f of entries) results.push(path.join(legacyDir, f));
+    }
+
+    return results;
+}
+
 async function deactivateOtherTasks(exceptTaskId) {
     if (!(await fs.pathExists(TASKS_DIR))) return;
     const entries = await fs.readdir(TASKS_DIR, { withFileTypes: true });
@@ -410,6 +443,21 @@ async function detectCurrentGate(taskId) {
         if (state.currentGate) return state.currentGate;
     }
 
+    // New convention: AK-Docs/04.Coding/<section>/<functionId>/<taskId>.md
+    const hasDocInSection = async (section) => {
+        const dir = path.join(CODING_DIR, section);
+        if (!(await fs.pathExists(dir))) return false;
+        const features = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const f of features) {
+            if (f.isDirectory() && await fs.pathExists(path.join(dir, f.name, `${taskId}.md`))) return true;
+        }
+        return false;
+    };
+    if (await hasDocInSection('04.Reviews'))      return 5;
+    if (await hasDocInSection('02.Plans'))        return 3;
+    if (await hasDocInSection('01.Requirements')) return 2;
+
+    // Legacy convention: plan/<taskId>/
     const planDir = path.join(PROJECT_DIR, 'plan', taskId);
     if (!(await fs.pathExists(planDir))) return 1;
     if (await fs.pathExists(path.join(planDir, 'summary.md')))     return 5;