@relipa/ai-flow-kit 0.1.8 → 0.1.9

package/docs/common/INDEX.md

@@ -14,7 +14,8 @@
 | What is the Gate Workflow, how do Gates 1–5 fit together | [AIFLOW.md](./AIFLOW.md) (§ Workflow Overview) | |
 | Roles — PM / DEV / AI responsibilities | [AIFLOW.md](./AIFLOW.md) (§ Roles) | Table is intentionally brief — see "Unanswered topics" for a fuller PM-specific guide |
 | All CLI commands (`ak ...`), options, examples | [cli-reference.md](./cli-reference.md) | |
-| Switching between Claude Code / Cursor / Gemini CLI mid-task | [ai-integration.md](./ai-integration.md) | |
+| Switching between Claude Code / Codex / Cursor / Gemini CLI mid-task | [ai-integration.md](./ai-integration.md) | |
+| Using Codex — VS Code extension, ChatGPT desktop app, or CLI | [ai-integration.md](./ai-integration.md) (§ 4 Codex) | `ak init --env codex` → `AGENTS.md` + `.codex/`; no session-start hook, so start a new session after `ak use` |
 | Config levels (global / project / local state) | [configuration.md](./configuration.md) | |
 | Something isn't working (`command not found`, permission denied, etc.) | [troubleshooting.md](./troubleshooting.md) | |
 | Bug-fix / feature / refactor / investigation / impact-analysis / Figma workflows | [workflows/](./workflows/) | one file per task type |

package/docs/common/QUICK_START.md

@@ -136,6 +136,7 @@ Then open Claude and the AI will auto-detect the current gate and resume exactly
 > **Multi-Tool Support:**
 > - If using **Cursor**: Gate Workflow is enforced via `.cursorrules`.
 > - If using **Gemini CLI**: Rules are loaded from `GEMINI.md`.
+> - If using **Codex** (VS Code extension, ChatGPT desktop app, or CLI): rules are loaded from `AGENTS.md`. Codex has no session-start hook — start a **new** Codex session after `ak use`, then run `/ak-coding`.
 > - The AI will automatically detect if you are mid-task by reading `.aiflow/context/current.json`.
 
 ### Step 3: GATE 1 — AI Analyzes Requirement

package/docs/common/ai-integration.md

@@ -7,11 +7,20 @@
 | Tool | Instruction File | Support Level | Key Features |
 |------|------------------|---------------|--------------|
 | **Claude Code** | `CLAUDE.md` | Native (Best) | Auto-triggers, full MCP access, session hooks. |
+| **Codex** (VS Code extension, ChatGPT desktop app, CLI) | `AGENTS.md` | High | Auto-discovered skills (`.codex/skills/`), MCP via `.codex/config.toml`. |
 | **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. |
 
+Select which tools to configure with `--env`:
+
+```bash
+ak init --framework reactjs --env claude,codex
+```
+
+Omitting `--env` configures every tool except `generic`.
+
 ---
 
 ## Tool-Specific Setup
@@ -27,10 +36,65 @@ 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
+### 3. GitHub Copilot
 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.
 
+### 4. Codex (OpenAI)
+
+`ak init --env codex` sets up all three local Codex surfaces at once — they share the same
+`CODEX_HOME` config, skills and MCP setup, so one install covers every one of them:
+
+| Surface | How to use it |
+|---------|---------------|
+| **Codex IDE extension** (VS Code / Cursor / Windsurf) | Open the project folder → Codex panel → `/ak-coding` |
+| **ChatGPT desktop app** (Codex mode) | Point Codex at this project folder → `/ak-coding` |
+| **`codex` CLI** | `cd` into the project → `codex` → `/ak-coding` |
+
+What gets generated:
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Instruction file Codex reads automatically at the repo root |
+| `.codex/skills/` | All kit skills, auto-discovered and indexed by Codex |
+| `.codex/config.toml` | MCP servers (mirrored from `.mcp.json`) + `project_doc_max_bytes` |
+| `.aiflow/instructions/` | The full gate workflows, which `AGENTS.md` links to |
+
+**Why `AGENTS.md` links to the workflows instead of containing them.** Codex truncates the
+combined `AGENTS.md` chain at `project_doc_max_bytes` — **32 KiB by default**. The assembled
+workflow set is around 115 KB, so inlining it the way `CLAUDE.md` does would silently cut the
+instructions off mid-gate. `AGENTS.md` therefore stays around 20 KB and points at
+`.aiflow/instructions/gate-workflow.md` (plus the BA and QA workflows), which Codex reads on
+demand. `.codex/config.toml` also raises the limit to 128 KiB as a safety margin for
+multi-framework projects.
+
+**Entry-point skills.** Four skills wrap the workflows so you can start without remembering
+file paths:
+
+| Skill | Use it for |
+|-------|-----------|
+| `/ak-coding` | Start or resume the DEV 5-Gate coding workflow |
+| `/ak-create-spec` | BA spec creation |
+| `/ak-create-testcase` | QA testcase creation |
+| `/ak-ask` | Questions about ai-flow-kit itself |
+
+**Things to know:**
+
+- **No session-start hook.** Unlike Claude Code, Codex will not auto-load a ticket. After
+  `ak use <TICKET>`, start a **new** Codex session so it re-reads `AGENTS.md`, then run
+  `/ak-coding`.
+- **Restart after `ak update` / `ak sync-skills`.** Codex loads skill metadata at session
+  start, so new or changed skills need a fresh session.
+- **Project trust.** Codex only loads `.codex/config.toml` for projects you have trusted. If
+  MCP servers do not appear, trust the project in Codex first.
+- **Hand-edited config is never overwritten.** If `.codex/config.toml` exists without the
+  `# ai-flow-kit managed` header, the kit leaves it alone and writes the generated version to
+  `.aiflow/reference/codex-config.toml` for you to merge.
+
+Verify the whole setup with `ak doctor`, which checks `AGENTS.md` against the active byte
+budget, the skill mirror, the workflow files, and MCP drift between `.mcp.json` and
+`.codex/config.toml`.
+
 ---
 
 ## Cross-Tool State Resumption
@@ -43,9 +107,12 @@ The "Secret Sauce" of `ai-flow-kit` is its file-based state management:
 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.
+3. Switch to **Cursor** or **Codex** 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.
 
+When resuming in Codex, run `/ak-coding`: it reads `.aiflow/tasks/[taskId]/task-state.json`
+and picks up at the gate already in progress instead of restarting from Gate 1.
+
 ---
 
 ## Best Practices

package/docs/common/cli-reference.md

@@ -53,7 +53,7 @@ ak init --no-rtk                             # skip RTK setup
 **Options:**
 - `-f, --framework <types>` (alias: `--fw`) — Framework templates, comma-separated (e.g. `spring-boot,reactjs`)
 - `-a, --adapter <types>` — MCP adapters (jira, backlog, google-sheets)
-- `-e, --env <types>` — AI tools to configure (cursor, gemini, copilot, generic). Default excludes `generic`.
+- `-e, --env <types>` — AI tools to configure (claude, cursor, gemini, copilot, codex, generic). Default excludes `generic`. Selecting `codex` also writes `AGENTS.md`, `.codex/skills/`, `.codex/config.toml` and `.aiflow/instructions/` — see [ai-integration.md](./ai-integration.md#4-codex-openai).
 - `--with-rtk` — Force enable RTK token compression hook
 - `--no-rtk` — Skip RTK setup even if RTK is detected
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.com/"
+    "registry": "https://registry.npmjs.org/"
   },
   "license": "ISC",
   "type": "commonjs",

package/scripts/doctor.js

@@ -45,6 +45,82 @@ async function showTokenBreakdown(ticketId) {
     console.log(`  Total estimated: ~${total.toLocaleString()} tokens`);
 }
 
+/**
+ * Verify the Codex side of the install: AGENTS.md, the skill mirror, the
+ * workflow files it points at, and the project config.
+ */
+async function checkCodex(projectDir, errors, warnings) {
+    console.log('');
+    console.log(chalk.bold('Codex (AGENTS.md — VS Code extension / ChatGPT desktop app / CLI):'));
+
+    const agentsPath = path.join(projectDir, 'AGENTS.md');
+    if (!(await fs.pathExists(agentsPath))) {
+        errors.push('Missing AGENTS.md — Codex has no instructions. Run `ak sync-skills`.');
+    } else {
+        const size = (await fs.stat(agentsPath)).size;
+        const kib  = (size / 1024).toFixed(1);
+        // Codex reads config from .codex/config.toml; without a raised limit it
+        // truncates the AGENTS.md chain at 32 KiB.
+        const configPath = path.join(projectDir, '.codex', 'config.toml');
+        let limit = 32 * 1024;
+        if (await fs.pathExists(configPath)) {
+            const cfg = await fs.readFile(configPath, 'utf-8').catch(() => '');
+            const m = cfg.match(/^\s*project_doc_max_bytes\s*=\s*(\d+)/m);
+            if (m) limit = parseInt(m[1], 10);
+        }
+        if (size > limit) {
+            errors.push(`AGENTS.md is ${kib} KiB but Codex truncates at ${(limit / 1024).toFixed(0)} KiB — instructions are being cut off. Run \`ak sync-skills\`.`);
+        } else {
+            console.log(chalk.green(`  ✓ AGENTS.md exists (${kib} KiB / ${(limit / 1024).toFixed(0)} KiB budget)`));
+        }
+    }
+
+    const codexSkills = path.join(projectDir, '.codex', 'skills');
+    if (!(await fs.pathExists(codexSkills))) {
+        warnings.push('Missing .codex/skills/ — Codex cannot load kit skills. Run `ak sync-skills`.');
+    } else {
+        const entries = await fs.readdir(codexSkills);
+        const entryPoints = ['ak-coding', 'ak-create-spec', 'ak-create-testcase', 'ak-ask'];
+        const missing = entryPoints.filter(e => !entries.includes(e));
+        if (missing.length) {
+            warnings.push(`.codex/skills/ is missing entry-point skill(s): ${missing.join(', ')}. Run \`ak sync-skills\`.`);
+        } else {
+            console.log(chalk.green(`  ✓ .codex/skills/ — ${entries.length} skills incl. all 4 entry points`));
+        }
+    }
+
+    const instructionsDir = path.join(projectDir, '.aiflow', 'instructions');
+    const required = ['gate-workflow.md', 'create-spec-workflow.md', 'create-testcase-workflow.md'];
+    const missingWorkflows = [];
+    for (const f of required) {
+        if (!(await fs.pathExists(path.join(instructionsDir, f)))) missingWorkflows.push(f);
+    }
+    if (missingWorkflows.length) {
+        errors.push(`AGENTS.md points at .aiflow/instructions/ but these are missing: ${missingWorkflows.join(', ')}. Run \`ak sync-skills\`.`);
+    } else {
+        console.log(chalk.green('  ✓ .aiflow/instructions/ — all 3 workflow files present'));
+    }
+
+    const configPath = path.join(projectDir, '.codex', 'config.toml');
+    if (!(await fs.pathExists(configPath))) {
+        warnings.push('Missing .codex/config.toml — Codex has no MCP servers and keeps the 32 KiB doc limit. Run `ak sync-skills`.');
+    } else {
+        const cfg = await fs.readFile(configPath, 'utf-8').catch(() => '');
+        const servers = [...cfg.matchAll(/^\[mcp_servers\.([^\]]+)\]/gm)].map(m => m[1]);
+        const mcpPath = path.join(projectDir, '.mcp.json');
+        let claudeServers = [];
+        if (await fs.pathExists(mcpPath)) {
+            const mcp = await fs.readJson(mcpPath).catch(() => ({}));
+            claudeServers = Object.keys(mcp.mcpServers || {});
+        }
+        const drift = claudeServers.filter(s => !servers.includes(s));
+        console.log(chalk.green(`  ✓ .codex/config.toml — ${servers.length} MCP server(s)${servers.length ? `: ${servers.join(', ')}` : ''}`));
+        if (drift.length) {
+            warnings.push(`.codex/config.toml is out of sync with .mcp.json — missing: ${drift.join(', ')}. Run \`ak sync-skills\`.`);
+        }
+    }
+}
+
 module.exports = async function doctor(options = {}) {
     const projectDir = process.cwd();
     const errors = [];
@@ -87,13 +163,20 @@ module.exports = async function doctor(options = {}) {
 
     // ── Version tracking ───────────────────────────────────────
     const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+    let selectedTools = [];
     if (!(await fs.pathExists(stateFile))) {
         errors.push('Missing `.aiflow/state.json`. Version tracking is broken.');
     } else {
         const state = await fs.readJson(stateFile);
+        selectedTools = state.aiTools || [];
         console.log(chalk.green(`✓ Version tracking active (v${state.current_version})`));
     }
 
+    // ── Codex (OpenAI) ─────────────────────────────────────────
+    if (selectedTools.includes('codex')) {
+        await checkCodex(projectDir, errors, warnings);
+    }
+
     // ── SessionStart hook ──────────────────────────────────────
     const settingsPath = path.join(projectDir, '.claude', 'settings.json');
     if (await fs.pathExists(settingsPath)) {

package/scripts/guide.js

@@ -146,7 +146,7 @@ function showCommands() {
             group: 'Setup',
             items: [
                 ['aiflow init', '--framework <fw> --adapter <ad>', 'Initialize project'],
-                ['aiflow init', '--env <tools>', 'AI tools: cursor,gemini,copilot'],
+                ['aiflow init', '--env <tools>', 'AI tools: claude,cursor,gemini,copilot,codex'],
                 ['aiflow init', '--with-rtk | --no-rtk', 'RTK bash compression (60–90% saving)'],
                 // ['aiflow init', '--with-gitnexus', 'GitNexus code intelligence (waits for index)'],
                 // ['aiflow init', '--with-gitnexus --no-wait', 'GitNexus: index in background'],