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

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
@@ -281,6 +281,51 @@ Write documentation based on approved outline.
 **INVOKE:** \`superpowers:verification-before-completion\`
 Verify docs match code. No outdated examples.
 Display: "GATE 3: Documentation complete. Type APPROVED."
+`,
+    },
+    'gen-doc': {
+        header: 'Generate Document',
+        instruction: 'Generate a document from source code / feature analysis as described below.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — Generate Document (2-Gate)
+
+> ⚡ gen-doc uses a **2-gate flow**: Gate 1 (Requirement) → APPROVED → Gate 2 (Generate + Auto Review).
+> Gate 2 runs immediately after APPROVED — no plan.md, no TDD, no extra coding gates.
+
+> gen-doc reuses the same \`AK-Docs/04.Coding/\` folders as the standard Dev workflow (see \`custom/rules/project-conventions.md\`) — only Gate 1–2, no separate section.
+
+### GATE 1 — AI Analyze & Plan Document
+**INVOKE:** \`read-study-requirement\` skill
+1. Load ticket context + read source code / files to understand scope
+2. Confirm \`functionId\` (BẮT BUỘC — see "functionId & ticketId" in \`project-conventions.md\`; if it can't be derived for an ad-hoc task, ask directly) and ensure AK-Docs is on branch \`feature/[functionId]/[ticketId]\` (create via \`ak docs branch [functionId] [ticketId] --yes\` only after explicit user confirmation)
+3. Understand the document goal, target audience, and output format
+4. If unclear → ask ONE question at a time, wait for reply
+5. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
+   - Document scope and target audience
+   - Content outline (sections to cover)
+   - Source references (files, features, flows to analyze)
+   - Output format: Markdown or Excel (note template path if applicable)
+   - Effort estimate
+6. Display "GATE 1: Document plan ready" → wait for **APPROVED**
+
+> **Telemetry:** Run \`ak gate 1 start --ticket [ticket-id]\` when starting.
+> Run \`ak gate 1 approved --ticket [ticket-id]\` immediately when APPROVED is received.
+
+### GATE 2 — Generate Document + Auto Review (runs immediately after APPROVED)
+
+**DO NOT create plan.md. DO NOT run TDD. Proceed directly to document generation.**
+
+1. Re-read \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` (the approved outline)
+2. Read source code, trace data flows, analyze features as needed
+3. Generate the output document:
+   - **Markdown:** Save to \`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md\` (or the custom path/format noted in the requirement doc — still write a short pointer + summary into this file)
+4. Self-review: verify content completeness against the approved requirement outline
+5. Create \`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md\` with a brief summary of what was generated
+6. Submit AK-Docs via Merge Request: show the commit/MR title+description, wait for explicit user confirmation, then run \`ak docs submit --title "..." --description "..." --yes\` — PM reviews & merges into \`main\` (never merge it yourself)
+7. Run: \`ak gate 2 approved --ticket [ticket-id]\` to close the task
+8. Display: \`GATE 2 DONE: Document generated at [path]\`
+
+**Do NOT wait for extra approval before generating the document — only the branch/MR confirmations above gate on the user; run the gate 2 approved command immediately after.**
 `,
     },
 };

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
@@ -216,7 +218,7 @@ 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} gate doc file(s) (04.Coding/ + legacy plan/) for ${taskId}?`,
+        message: `Also delete ${planFiles.length} gate doc file(s) (AK-Docs/04.Coding/ + legacy plan/) for ${taskId}?`,
         default: false,
     });
 
@@ -329,17 +331,22 @@ async function nextGate(taskId) {
     const nextGateNum = currentGate + 1;
 
     // Save context snapshot if current task is active
+    let taskType = null;
     if (await fs.pathExists(CURRENT_FILE)) {
         const ctx = await fs.readJson(CURRENT_FILE).catch(() => null);
         if (ctx && ctx.taskId === resolvedId) {
+            taskType = ctx.taskType || null;
             await fs.writeJson(path.join(taskDir, 'context.json'), ctx, { spaces: 2 });
         }
     }
 
+    const isGenDoc = taskType === 'gen-doc';
+    const maxGate = isGenDoc ? 2 : 5;
+
     const taskState = {
         ...existing,
         taskId:        resolvedId,
-        status:        'pending',
+        status:        nextGateNum > maxGate ? 'done' : 'pending',
         updatedAt:     now,
         pausedAt:      now,
         currentGate:   nextGateNum,
@@ -352,20 +359,26 @@ async function nextGate(taskId) {
 
     // 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);
+    const summaryContent = await generateMarkdownSummary(taskState, taskType);
     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: .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 the Gate 2 plan doc (04.Coding/02.Plans/).`));
-    console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
+
+    if (isGenDoc && currentGate >= maxGate) {
+        console.log(chalk.green('\n  ✅ Document workflow complete. Task is done.'));
+    } else {
+        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".`));
+        if (!isGenDoc) {
+            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();
 }
 
@@ -374,18 +387,17 @@ async function nextGate(taskId) {
 // ──────────────────────────────────────────────────────────────
 
 /**
- * Find gate output docs for a task under 04.Coding/<section>/<functionId>/<taskId>.md
+ * 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 = [];
 
-    const codingDir = path.join(PROJECT_DIR, '04.Coding');
-    if (await fs.pathExists(codingDir)) {
-        const sections = await fs.readdir(codingDir, { withFileTypes: true }).catch(() => []);
+    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(codingDir, section.name);
+            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;
@@ -442,9 +454,9 @@ async function detectCurrentGate(taskId) {
         if (state.currentGate) return state.currentGate;
     }
 
-    // New convention: 04.Coding/<section>/<functionId>/<taskId>.md
+    // New convention: AK-Docs/04.Coding/<section>/<functionId>/<taskId>.md
     const hasDocInSection = async (section) => {
-        const dir = path.join(PROJECT_DIR, '04.Coding', 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) {
@@ -465,9 +477,9 @@ async function detectCurrentGate(taskId) {
     return 1;
 }
 
-async function generateMarkdownSummary(taskState) {
-    const taskType = taskState.taskType || 'feature';
-    const maxGate  = taskType === 'testing' ? 4 : 5;
+async function generateMarkdownSummary(taskState, taskType = null) {
+    taskType = taskType || taskState.taskType || 'feature';
+    const maxGate = taskType === 'testing' ? 4 : (taskType === 'gen-doc' ? 2 : 5);
     const lines = [];
     lines.push(`# Task Summary: ${taskState.taskId}`);
     lines.push(`**Title:** ${taskState.title}`);
@@ -491,7 +503,7 @@ async function generateMarkdownSummary(taskState) {
     return lines.join('\n');
 }
 
-function gateLabel(n, taskType) {
+function gateLabel(n, taskType = null) {
     if (taskType === 'testing') {
         const labels = {
             1: 'Phân tích & Confirm',
@@ -501,6 +513,10 @@ function gateLabel(n, taskType) {
         };
         return labels[n] || `Gate ${n}`;
     }
+    if (taskType === 'gen-doc') {
+        if (n === 2) return 'Generate Document';
+        if (n >= 3) return 'Done';
+    }
     const labels = {
         1: 'AI Analyze Requirement',
         2: 'Implementation Plan',

package/scripts/update.js

@@ -2,6 +2,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 const { confirm, select } = require('@inquirer/prompts');
+const { syncDocsRepos } = require('./docs-repo');
 
 const PKG_DIR = path.join(__dirname, '..');
 const PKG_VERSION = require('../package.json').version;
@@ -25,6 +26,9 @@ module.exports = async function update(options = {}) {
         return;
     }
 
+    // ── Sync AK-Docs / Shared-Docs sibling repos ──────────────────
+    await syncDocsRepos(projectDir);
+
     const state = await fs.readJson(stateFile);
     const currentVersion = state.current_version;
 

package/scripts/use.js

@@ -234,7 +234,7 @@ async function loadFromBacklog(issueKey, options = {}) {
       options.cto != null ||
       options.commentsTo != null ||
       options["comments-to"] != null;
-    
+
     if (loadComments) {
       console.log(chalk.gray("  ℹ Comments requested..."));
     }
@@ -349,13 +349,13 @@ async function fetchBacklogComments(domain, apiKey, issueKey) {
       if (minId) {
         url += `&minId=${minId}`;
       }
-      
+
       const batch = await backlogGet(url);
       if (!batch || batch.length === 0) break;
-      
+
       all.push(...batch);
       if (batch.length < 100) break;
-      
+
       // Use the last ID as minId for the next batch
       minId = batch[batch.length - 1].id;
     }
@@ -467,7 +467,7 @@ async function loadFromJira(issueKey, options = {}) {
       options.cto != null ||
       options.commentsTo != null ||
       options["comments-to"] != null;
-    
+
     if (loadComments) {
       console.log(chalk.gray("  ℹ Comments requested..."));
     }
@@ -709,6 +709,7 @@ async function manualContext(prefillId = "") {
       { name: td("🔍 Investigation",    "Analysis", "Investigate, analyze root cause"),                   value: "investigation" },
       { name: td("📊 Impact Analysis",  "Analysis", "Assess scope and risk of changes"),                  value: "impact-analysis" },
       { name: td("📖 Documentation",    "Document", "Write docs, README, API reference"),                 value: "documentation" },
+      { name: td("📝 Generate Doc 2 Gate", "Document", "Generate new documentation"),                      value: "gen-doc" },
     ],
     default: existing.taskType || undefined,
   });