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

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 `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 `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-beta.1",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

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(`  04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  ([functionId] — look it up in 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(`  04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  04.Coding/02.Plans/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  ([functionId] — look it up in 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 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 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 04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
             lines.push('6. Display GATE 1 prompt and wait for APPROVED');
         }
 

package/scripts/task.js

@@ -206,12 +206,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 +216,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) (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 +248,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 +270,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 +280,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 +293,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 +350,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 (04.Coding/02.Plans/).`));
     console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
     console.log();
 }
@@ -373,6 +373,38 @@ async function nextGate(taskId) {
 // Internal helpers
 // ──────────────────────────────────────────────────────────────
 
+/**
+ * Find gate output docs for a task under 04.Coding/<section>/<functionId>/<taskId>.md
+ * (new convention) plus the legacy plan/<taskId>/ folder. Returns absolute paths.
+ */
+async function findTaskDocs(taskId) {
+    const results = [];
+
+    const codingDir = path.join(PROJECT_DIR, '04.Coding');
+    if (await fs.pathExists(codingDir)) {
+        const sections = await fs.readdir(codingDir, { withFileTypes: true }).catch(() => []);
+        for (const section of sections) {
+            if (!section.isDirectory()) continue;
+            const sectionDir = path.join(codingDir, 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 +442,21 @@ async function detectCurrentGate(taskId) {
         if (state.currentGate) return state.currentGate;
     }
 
+    // New convention: 04.Coding/<section>/<functionId>/<taskId>.md
+    const hasDocInSection = async (section) => {
+        const dir = path.join(PROJECT_DIR, '04.Coding', 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;