@relipa/ai-flow-kit 0.1.8 → 0.1.9

package/scripts/init.js

@@ -58,9 +58,58 @@ const AI_TOOL_FILES = {
     'cursor':   '.cursorrules',
     'gemini':   'GEMINI.md',
     'copilot':  '.github/copilot-instructions.md',
+    'codex':    'AGENTS.md',
     'generic':  '.aiflow/docs/AI_INSTRUCTIONS.md',
 };
 
+// Instruction-file layout per tool.
+//   'inline'  — the full workflow set is embedded in the tool file (default).
+//   'pointer' — the tool file stays small and links to .aiflow/instructions/ instead.
+//
+// Codex is 'pointer' because it caps the combined AGENTS.md chain at
+// project_doc_max_bytes (32 KiB default) and silently drops whatever exceeds it.
+// The assembled workflow set is ~115 KB, so inlining would truncate it mid-gate.
+const AI_TOOL_LAYOUT = {
+    'codex': 'pointer',
+};
+
+/** Return 'inline' or 'pointer' for a tool key. */
+function resolveToolLayout(tool) {
+    return AI_TOOL_LAYOUT[tool] || 'inline';
+}
+
+// Shared workflow templates copied to .aiflow/instructions/ for pointer-layout tools.
+// Keys are the destination basenames; gate workflow resolves per framework.
+const WORKFLOW_INSTRUCTION_FILES = [
+    { dest: 'create-spec-workflow.md',     src: 'create-spec-workflow.md' },
+    { dest: 'create-testcase-workflow.md', src: 'create-testcase-workflow.md' },
+];
+
+/**
+ * Write the full gate/spec/testcase workflows to .aiflow/instructions/ so
+ * pointer-layout tools (Codex) can read them on demand instead of having them
+ * inlined into an instruction file that would be truncated.
+ * Returns the list of project-relative paths written.
+ */
+async function writeWorkflowInstructions(projectDir, framework) {
+    const destDir = path.join(projectDir, '.aiflow', 'instructions');
+    await fs.ensureDir(destDir);
+
+    const files = [
+        { dest: 'gate-workflow.md', src: resolveWorkflowFile(framework) },
+        ...WORKFLOW_INSTRUCTION_FILES,
+    ];
+
+    const written = [];
+    for (const f of files) {
+        const src = path.join(PKG_DIR, 'custom', 'templates', 'shared', f.src);
+        if (!(await fs.pathExists(src))) continue;
+        await fs.copy(src, path.join(destDir, f.dest), { overwrite: true });
+        written.push(`.aiflow/instructions/${f.dest}`);
+    }
+    return written;
+}
+
 /**
  * Copy only docs/common/ to .aiflow/docs in the project.
  * Internal aiflow docs (changelog, architecture…) are never copied out.
@@ -366,10 +415,212 @@ async function setupClaudeCommands(projectDir) {
     }
 }
 
+// ── Codex (OpenAI) support ───────────────────────────────────────
+// Codex reads AGENTS.md + .codex/ from the workspace root. The same files serve
+// all three local surfaces — the Codex IDE extension (VS Code), Codex mode in
+// the ChatGPT desktop app, and the `codex` CLI — because they share CODEX_HOME
+// config, skills and MCP setup.
+
+const CODEX_MANAGED_HEADER = '# ai-flow-kit managed — regenerate with `ak sync-skills`';
+
+// Codex truncates the combined AGENTS.md chain at project_doc_max_bytes.
+// The 32 KiB default is enough for one pointer block, but a multi-framework
+// project appends one block per framework, so raise it.
+const CODEX_PROJECT_DOC_MAX_BYTES = 131072;
+
+/** Serialize a JS string as a TOML basic string. */
+function tomlString(value) {
+    return JSON.stringify(String(value));
+}
+
+/**
+ * Render one [mcp_servers.<id>] table from an .mcp.json server entry.
+ * Codex uses the same command/args/env shape as .mcp.json, just in TOML.
+ */
+function renderCodexMcpServer(id, cfg) {
+    const lines = [`[mcp_servers.${id}]`];
+    if (cfg.command) lines.push(`command = ${tomlString(cfg.command)}`);
+    if (Array.isArray(cfg.args) && cfg.args.length) {
+        lines.push(`args = [${cfg.args.map(tomlString).join(', ')}]`);
+    }
+    const env = cfg.env && Object.keys(cfg.env).length ? cfg.env : null;
+    if (env) {
+        const pairs = Object.entries(env).map(([k, v]) => `${k} = ${tomlString(v)}`);
+        lines.push(`env = { ${pairs.join(', ')} }`);
+    }
+    return lines.join('\n');
+}
 
-async function generateSkillRegistry(projectDir) {
+/**
+ * Write .codex/config.toml — project-scoped Codex config mirroring .mcp.json.
+ *
+ * The file is fully kit-managed: it is only written when absent or when it still
+ * carries our header. A hand-edited config is left alone and the generated
+ * version is saved to .aiflow/reference/ for the developer to merge.
+ */
+async function setupCodexConfig(projectDir) {
+    const configPath = path.join(projectDir, '.codex', 'config.toml');
+
+    const mcpPath = path.join(projectDir, '.mcp.json');
+    let servers = {};
+    if (await fs.pathExists(mcpPath)) {
+        const mcp = await fs.readJson(mcpPath).catch(() => ({}));
+        servers = mcp.mcpServers || {};
+    }
+
+    const sections = [
+        CODEX_MANAGED_HEADER,
+        '# Project-scoped Codex config. Applies to the Codex IDE extension,',
+        '# Codex mode in the ChatGPT desktop app, and the `codex` CLI.',
+        '',
+        '# AGENTS.md is assembled per framework and can exceed the 32 KiB default.',
+        `project_doc_max_bytes = ${CODEX_PROJECT_DOC_MAX_BYTES}`,
+    ];
+
+    const serverIds = Object.keys(servers);
+    for (const id of serverIds) {
+        sections.push('', renderCodexMcpServer(id, servers[id]));
+    }
+    const content = sections.join('\n') + '\n';
+
+    if (await fs.pathExists(configPath)) {
+        const existing = await fs.readFile(configPath, 'utf-8');
+        if (!existing.includes(CODEX_MANAGED_HEADER)) {
+            const refPath = path.join(projectDir, '.aiflow', 'reference', 'codex-config.toml');
+            await fs.ensureDir(path.dirname(refPath));
+            await fs.writeFile(refPath, content);
+            console.log(chalk.yellow('  ⚠ .codex/config.toml exists and is hand-managed — left untouched.'));
+            console.log(chalk.gray('    Generated version saved to .aiflow/reference/codex-config.toml — merge manually.'));
+            return { written: false, servers: serverIds };
+        }
+    }
+
+    await fs.ensureDir(path.dirname(configPath));
+    await fs.writeFile(configPath, content);
+    const mcpNote = serverIds.length ? ` (MCP: ${serverIds.join(', ')})` : '';
+    console.log(chalk.green(`✓ Codex config written → .codex/config.toml${mcpNote}`));
+    return { written: true, servers: serverIds };
+}
+
+/**
+ * Mirror the kit's skills into .codex/skills/ and add the four entry-point
+ * skills that wrap the shared workflows.
+ *
+ * Codex discovers project skills as any directory under .codex/skills containing
+ * a SKILL.md with name/description frontmatter — the same layout .claude/skills
+ * already uses, so the canonical copy is reused verbatim.
+ */
+async function setupCodexSkills(projectDir) {
+    const claudeSkills = path.join(projectDir, '.claude', 'skills');
+    const codexSkills  = path.join(projectDir, '.codex', 'skills');
+
+    if (!(await fs.pathExists(claudeSkills))) {
+        console.log(chalk.yellow('  ! .claude/skills not found — Codex skills not installed.'));
+        return;
+    }
+
+    await fs.emptyDir(codexSkills);
+    await fs.copy(claudeSkills, codexSkills, { overwrite: true });
+    const count = (await fs.readdir(codexSkills)).length;
+    console.log(chalk.green(`✓ Mirrored ${count} skills → .codex/skills/`));
+
+    // Entry-point skills. Small workflows are inlined; the two large ones point at
+    // .aiflow/instructions/ so skill metadata scanning stays cheap.
+    const entryPoints = [
+        {
+            name: 'ak-coding',
+            description: 'Start or resume the DEV 5-Gate coding workflow for the ticket loaded by `ak use`. Trigger when the developer says start / Gate 1 / analyze ticket, or when a ticket was loaded while this session was already open. Do not trigger for BA spec or QA testcase work.',
+            src: 'coding-workflow.md',
+        },
+        {
+            name: 'ak-ask',
+            description: 'Answer a question about ai-flow-kit itself — install, roles, folder structure, CLI commands, memory draft/submit, troubleshooting. Trigger on an AKQ:/[AKQ]: prefix or a kit-usage question, even with no ticket loaded. Do not trigger for the developer\'s actual ticket work.',
+            src: 'ak-ask-workflow.md',
+        },
+        {
+            name: 'ak-create-spec',
+            description: 'BA 4-Gate Spec Creation Workflow — turn a raw requirement (Jira/Backlog/file) into a complete UC Spec: Gate 1 analysis & Q&A, Gate 2 Q&A loop until Confirmed, Gate 3 HTML/CSS prototype, Gate 4 full UC Spec. Trigger for BA spec work, not for coding or testcases.',
+            pointer: '.aiflow/instructions/create-spec-workflow.md',
+            subSkills: '.codex/skills/ba-skills/',
+        },
+        {
+            name: 'ak-create-testcase',
+            description: 'QA 4-Gate TestCase Creation Workflow — turn a requirement or spec (SRS/Backlog/Jira/Spec file) into an execution-ready test case set: Gate 1 requirement & risk analysis, Gate 2 scenarios, Gate 3 detailed cases, Gate 4 review & optimization. Trigger for QA testcase work, not for coding or BA specs.',
+            pointer: '.aiflow/instructions/create-testcase-workflow.md',
+            subSkills: '.codex/skills/test-skills/',
+        },
+    ];
+
+    for (const ep of entryPoints) {
+        let body;
+        if (ep.pointer) {
+            body = [
+                `Read \`${ep.pointer}\` **in full**, then follow it exactly, gate by gate.`,
+                '',
+                'That file is the authoritative workflow — do not work from a summary of it and',
+                'do not skip, shorten, or merge gates. Sub-skills it references live in',
+                `\`${ep.subSkills}\`.`,
+                '',
+                'Before starting, read `.aiflow/context/current.json` for ticket context if it exists.',
+            ].join('\n');
+        } else {
+            const src = path.join(PKG_DIR, 'custom', 'templates', 'shared', ep.src);
+            if (!(await fs.pathExists(src))) continue;
+            body = await fs.readFile(src, 'utf-8');
+        }
+
+        const skillDir = path.join(codexSkills, ep.name);
+        await fs.ensureDir(skillDir);
+        const content = `---\nname: ${ep.name}\ndescription: ${ep.description}\n---\n\n${body}`;
+        await fs.writeFile(path.join(skillDir, 'SKILL.md'), content);
+    }
+    console.log(chalk.green(`✓ Installed ${entryPoints.length} Codex entry-point skills (${entryPoints.map(e => e.name).join(', ')})`));
+}
+
+/**
+ * Full Codex setup: skill mirror + project config.
+ * Safe to call unconditionally — no-ops when 'codex' is not a selected AI tool.
+ */
+async function setupCodex(projectDir, selectedTools) {
+    if (!selectedTools || !selectedTools.includes('codex')) return;
+    await setupCodexSkills(projectDir);
+    await setupCodexConfig(projectDir);
+}
+
+/**
+ * Build the markdown skill registry table.
+ * Skills are always read from .claude/skills (the canonical copy). `skillsRoot`
+ * only rewrites the paths written into the table, so Codex can be pointed at its
+ * own .codex/skills mirror.
+ */
+/**
+ * Compact skill list for pointer-layout tools.
+ *
+ * Codex indexes .codex/skills/ itself — every SKILL.md's name and description are
+ * already in its skill index — so restating the full registry table in AGENTS.md
+ * would burn ~11 KB of the doc budget on every turn for nothing. Names only, so a
+ * workflow's "INVOKE: <skill>" step still resolves to a known path.
+ */
+async function generateSkillNameList(projectDir, skillsRoot = '.codex/skills') {
     const skillsDir = path.join(projectDir, '.claude', 'skills');
-    
+    if (!(await fs.pathExists(skillsDir))) return '';
+
+    const names = [];
+    for (const folder of await fs.readdir(skillsDir)) {
+        if (await fs.pathExists(path.join(skillsDir, folder, 'SKILL.md'))) names.push(folder);
+    }
+    if (!names.length) return '';
+
+    let out = `## Available skills\n\n`;
+    out += `Codex indexes these automatically from \`${skillsRoot}/\`. When a workflow step says `;
+    out += `**INVOKE:** \`<name>\`, read \`${skillsRoot}/<name>/SKILL.md\` in full and follow it:\n\n`;
+    out += names.sort().map(n => `\`${n}\``).join(' · ') + '\n';
+    return out;
+}
+
+async function generateSkillRegistry(projectDir, skillsRoot = '.claude/skills') {
+    const skillsDir = path.join(projectDir, '.claude', 'skills');
+
     if (!(await fs.pathExists(skillsDir))) return '';
 
     let registry = `## AI Skill Registry (Superpowers)\n\n`;
@@ -393,8 +644,8 @@ async function generateSkillRegistry(projectDir) {
                 description = lines[0] ? lines[0].trim() : 'No description available';
             }
 
-            // Path relative to project root
-            const relPath = path.relative(projectDir, skillFile).replace(/\\/g, '/');
+            // Path relative to project root, re-rooted for the target tool
+            const relPath = `${skillsRoot}/${folder}/SKILL.md`;
             registry += `| **${folder}** | ${description} | \`${relPath}\` |\n`;
         }
     }
@@ -432,11 +683,51 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
     const workflowContent = [gateWorkflowContent, createSpecContent, createTestcaseContent].filter(Boolean).join('\n\n---\n\n');
 
     const separator = `\n\n---\n\n`;
-    const skillRegistry = await generateSkillRegistry(projectDir);
+    const skillRegistry  = await generateSkillRegistry(projectDir);
+    const codexSkillList = await generateSkillNameList(projectDir, '.codex/skills');
 
     const markerStart = '<!-- aiflow-kit-start -->';
     const markerEnd   = '<!-- aiflow-kit-end -->';
 
+    // Pointer-layout tools need the workflows on disk instead of inlined.
+    const needsPointer = selectedTools.some(t => resolveToolLayout(t) === 'pointer');
+    const instructionPaths = needsPointer
+        ? await writeWorkflowInstructions(projectDir, framework)
+        : [];
+
+    /**
+     * Assemble the marker block for one tool.
+     * 'inline' tools get the whole workflow set embedded; 'pointer' tools get a
+     * short "installed workflow files" list and read the workflows from disk.
+     */
+    async function buildToolBlock(tool, blockMarkerStart, blockMarkerEnd) {
+        const pointer = resolveToolLayout(tool) === 'pointer';
+        let body = '';
+
+        const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
+        if (await fs.pathExists(toolTemplatePath)) {
+            body += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
+        }
+
+        if (frameworkContent) body += frameworkContent + '\n\n';
+
+        const registry = pointer ? codexSkillList : skillRegistry;
+        if (registry) body += registry + '\n\n';
+
+        if (pointer) {
+            if (instructionPaths.length) {
+                body += `## Installed workflow files\n\n`;
+                body += `Generated for framework \`${framework}\` by ai-flow-kit v${PKG_VERSION}. `;
+                body += `Read the relevant file in full before starting a gate:\n\n`;
+                body += instructionPaths.map(p => `- \`${p}\``).join('\n') + '\n\n';
+            }
+        } else if (workflowContent) {
+            body += workflowContent + '\n\n';
+        }
+
+        return `${blockMarkerStart}\n${body.trim()}\n${blockMarkerEnd}`;
+    }
+
     const written = [];
     const skipped = [];
 
@@ -472,15 +763,7 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
             await fs.ensureDir(path.dirname(targetPath));
 
             // Build content for this tool
-            let finalContent = '';
-            const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
-            if (await fs.pathExists(toolTemplatePath)) {
-                finalContent += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
-            }
-            finalContent += frameworkContent + '\n\n';
-            if (skillRegistry) finalContent += skillRegistry + '\n\n';
-            if (workflowContent) finalContent += workflowContent + '\n\n';
-            finalContent = `${markerStart}\n${finalContent.trim()}\n${markerEnd}`;
+            const finalContent = await buildToolBlock(tool, markerStart, markerEnd);
 
             // Backup existing file before overwriting
             if (await fs.pathExists(targetPath)) {
@@ -513,27 +796,13 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
 
         await fs.ensureDir(path.dirname(targetPath));
 
-        let finalContent = '';
+        // Multi-framework projects get one self-contained, per-framework marker block
+        // per tool file so re-running init/update can find-and-replace each framework's
+        // block in place instead of blindly appending it again on every run.
+        const blockMarkerStart = multi ? `<!-- aiflow-kit-start:${framework} -->` : markerStart;
+        const blockMarkerEnd   = multi ? `<!-- aiflow-kit-end:${framework} -->`   : markerEnd;
 
-        const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
-        if (await fs.pathExists(toolTemplatePath)) {
-            finalContent += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
-        }
-
-        // Include framework conventions for single-framework projects
-        if (!multi && frameworkContent) {
-            finalContent += frameworkContent + '\n\n';
-        }
-
-        if (skillRegistry) {
-            finalContent += skillRegistry + '\n\n';
-        }
-
-        if (workflowContent) {
-            finalContent += workflowContent + '\n\n';
-        }
-
-        finalContent = `${markerStart}\n${finalContent.trim()}\n${markerEnd}`;
+        const finalContent = await buildToolBlock(tool, blockMarkerStart, blockMarkerEnd);
 
         const fileExists = await fs.pathExists(targetPath);
 
@@ -593,7 +862,15 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
             }
         } else {
             if (fileExists) {
-                await fs.appendFile(targetPath, separator + frameworkContent);
+                const existingContent = await fs.readFile(targetPath, 'utf-8');
+                const hasBlock = existingContent.includes(blockMarkerStart) && existingContent.includes(blockMarkerEnd);
+                if (hasBlock) {
+                    const regex = new RegExp(`${blockMarkerStart}[\\s\\S]*?${blockMarkerEnd}`, 'g');
+                    const updatedContent = existingContent.replace(regex, finalContent);
+                    await fs.writeFile(targetPath, updatedContent);
+                } else {
+                    await fs.appendFile(targetPath, separator + finalContent);
+                }
             } else {
                 await fs.writeFile(targetPath, finalContent);
             }
@@ -802,6 +1079,8 @@ async function ensureAiflowGitignored(projectDir) {
         '.mcp.json',
         'CLAUDE.md',
         'GEMINI.md',
+        'AGENTS.md',
+        '.codex/',
         '.cursorrules',
         '.github/copilot-instructions.md'
     ];
@@ -1185,6 +1464,11 @@ async function init(options) {
         // ── Optional: GitNexus code intelligence ─────────────────────
         await maybeSetupGitNexus(projectDir, options.withGitnexus || false, options.wait || false);
 
+        // ── Codex assets ─────────────────────────────────────────────
+        // After adapters + GitNexus: .codex/config.toml mirrors .mcp.json, so it
+        // has to be written once every MCP server is registered.
+        await setupCodex(projectDir, selectedTools);
+
         // ── Ensure all aiflow files are gitignored ───────────────────
         await ensureAiflowGitignored(projectDir);
 
@@ -1201,6 +1485,9 @@ async function init(options) {
 
         console.log(`  ${chalk.green('claude')}                ${chalk.gray('← Claude Code CLI (recommended)')}`);
         console.log(`  ${chalk.green('Cursor / Gemini')}       ${chalk.gray('← Instructions in .cursorrules / GEMINI.md')}`);
+        if (selectedTools.includes('codex')) {
+            console.log(`  ${chalk.green('Codex')}                 ${chalk.gray('← AGENTS.md + .codex/ (VS Code extension, ChatGPT desktop app, codex CLI)')}`);
+        }
         console.log(chalk.blue('─'.repeat(62)));
         console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Commands: ${chalk.green('aiflow guide --commands')}`));
         console.log(chalk.blue('─'.repeat(62)) + '\n');
@@ -1211,6 +1498,15 @@ async function init(options) {
 
 module.exports = init;
 module.exports.AI_TOOL_FILES = AI_TOOL_FILES;
+module.exports.AI_TOOL_LAYOUT = AI_TOOL_LAYOUT;
+module.exports.resolveToolLayout = resolveToolLayout;
+module.exports.writeWorkflowInstructions = writeWorkflowInstructions;
+module.exports.setupCodex = setupCodex;
+module.exports.setupCodexSkills = setupCodexSkills;
+module.exports.setupCodexConfig = setupCodexConfig;
+module.exports.renderCodexMcpServer = renderCodexMcpServer;
+module.exports.generateSkillNameList = generateSkillNameList;
+module.exports.CODEX_PROJECT_DOC_MAX_BYTES = CODEX_PROJECT_DOC_MAX_BYTES;
 module.exports.detectRtk = detectRtk;
 module.exports.isRtkHookConfigured = isRtkHookConfigured;
 module.exports.isGitNexusConfigured = isGitNexusConfigured;

package/scripts/prompt.js

@@ -51,8 +51,7 @@ Only runs after Gate 2 APPROVED.
 **INVOKE:** \`review-plan\` skill
 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 \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
+3. 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
@@ -103,8 +102,7 @@ Only runs after Gate 2 APPROVED.
 **INVOKE:** \`review-plan\` skill
 1. \`superpowers:verification-before-completion\` — all tests PASS
 2. \`impact-analysis\` skill — no regressions
-3. Tick \`custom/rules/review-checklist.md\`
-4. Create \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
+3. 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
@@ -181,8 +179,7 @@ Only runs after Gate 2 APPROVED.
 **INVOKE:** \`review-plan\` skill
 1. \`superpowers:verification-before-completion\` — all tests PASS
 2. \`impact-analysis\` skill — verify no regressions
-3. Tick \`custom/rules/review-checklist.md\`
-4. Create \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
+3. Create \`AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md\`
 - Display: "GATE 4: type APPROVED or BUG: [description]"
 
 ### GATE 5 — Peer Review & Done