@hanhnd/agent-kit 1.0.22 → 1.0.24

package/README.md

@@ -1,30 +1,35 @@
 # Agent-Kit
 
-**Super Engineer** — a team of specialized AI agents for software development. Brainstorm ideas, plan implementations, write code, and review PRs using a structured multi-agent workflow powered by Claude Code.
+**Super Engineer** — a team of specialized AI agents for software development. Brainstorm ideas, plan implementations, write code, and review PRs using a structured multi-agent workflow.
 
 ## What It Does
 
 ### Commands
 
-| Command                           | Description                                                          |
-| --------------------------------- | -------------------------------------------------------------------- |
-| `/ak:brainstorm [idea]`           | Strategic architectural analysis                                     |
-| `/ak:clarify <file or task>`      | Clarify requirements                                                 |
-| `/ak:plan [file or idea]`         | Create an implementation blueprint                                   |
-| `/ak:code [file or task]`         | Implement from a plan                                                |
-| `/ak:code-simplify`               | Simplify modified code for readability                               |
-| `/ak:code-refactor`               | Refactor modified code for readability                               |
-| `/ak:validate [artifact]`         | Validate artifacts against expectations (or append `with /validate`) |
-| `/ak:research [topic]`            | Research a topic                                                     |
-| `/ak:review-pr [PR URL]`          | Review a pull request                                                |
-| `/ak:review`                      | Review uncommitted local changes                                     |
-| `/ak:debate [subject]`            | Run adversarial debate (Gilfoyle vs Dinesh vs Judge)                 |
-| `/ak:ticket [ID]`                 | Fetch a Jira ticket and plan from it                                 |
-| `/ak:git`                         | Git commit, branch, and PR workflow                                  |
-| `/ak:init`                        | Create the project overview file                                     |
-| `/ak:orchestrate [file or idea]`  | Orchestrate agents to solve problems span across multiple projects   |
-| `/ak:delegate <agent> <task>`     | Delegate a task to Gemini or Claude CLI                              |
-| `/ak:wiki [compile\|query\|lint]` | Maintain a persistent, compounding project knowledge wiki            |
+Agent Kit ships these workflows as skills. In Claude Code, invoke them as slash commands such as `/plan ...`. In Codex or Gemini, ask the agent to use Agent Kit or the named skill, for example: `Use Agent Kit plan for this change`.
+
+| Skill / Command                  | Description                                                        |
+| -------------------------------- | ------------------------------------------------------------------ |
+| `/brainstorm [idea]`             | Turn a raw idea into an engineer-ready design brief                |
+| `/scenario [artifact]`           | Stress-test requirements, plans, tickets, or reviews for risks     |
+| `/clarify <file or task>`        | Resolve requirement gaps using codebase evidence                   |
+| `/plan [file or idea]`           | Create a detailed implementation blueprint                         |
+| `/investigate [issue]`           | Trace bugs, errors, or unexpected behavior to root cause           |
+| `/code [plan or report]`         | Implement from a WBS plan or investigation report                  |
+| `/test [intent]`                 | Add or update focused tests after implementation intent exists     |
+| `/code-review [diff or target]`  | Review diffs, PRs, or commits with evidence-backed findings        |
+| `/review [base]`                 | Review local staged and unstaged changes                           |
+| `/review-pr [PR URL]`            | Fetch PR/Jira context, check out the branch, and run code review   |
+| `/code-simplify [target]`        | Improve readability without changing behavior or public shape      |
+| `/code-refactor [target]`        | Analyze structural refactors and produce a refactor proposal       |
+| `/validate [artifact]`           | Validate artifacts directly or by appending `with /validate`       |
+| `/research [topic]`              | Produce source-backed technical research                           |
+| `/debate [subject]`              | Run adversarial validation of an analysis, review, or plan         |
+| `/ticket [ID]`                   | Fetch a Jira ticket and route it into the planning pipeline        |
+| `/init`                          | Extract project DNA for downstream coding and planning workflows   |
+| `/orchestrate [file or idea]`    | Decompose cross-service work into scoped handoff briefs            |
+| `/delegate <agent> <task>`       | Delegate to Gemini, Claude, or Codex CLI with optional handoff     |
+| `/wiki [compile\|query\|lint]`   | Maintain and query the persistent project knowledge wiki           |
 
 ---
 
@@ -46,9 +51,9 @@ You don't need to run the wiki manually. Five hooks keep it fed automatically:
 
 | Command                          | Description                                                           |
 | -------------------------------- | --------------------------------------------------------------------- |
-| `/ak:wiki` or `/ak:wiki compile` | Ingest raw inbox + conversation exports → build/update wiki pages     |
-| `/ak:wiki query {question}`      | Search the wiki and synthesize a cited answer                         |
-| `/ak:wiki lint`                  | Health-check: broken links, orphan pages, contradictions, stale inbox |
+| `/wiki` or `/wiki compile` | Ingest raw inbox + conversation exports → build/update wiki pages     |
+| `/wiki query {question}`      | Search the wiki and synthesize a cited answer                         |
+| `/wiki lint`                  | Health-check: broken links, orphan pages, contradictions, stale inbox |
 
 ### Directory Structure
 
@@ -58,7 +63,7 @@ You don't need to run the wiki manually. Five hooks keep it fed automatically:
 │   ├── inbox.md          # Auto-appended by PostToolUse hook (handoff logs)
 │   └── conv_*.md         # Exported by PreCompact hook (conversation transcripts)
 ├── compiled/
-│   └── *.md              # Structured wiki pages built by /ak:wiki compile
+│   └── *.md              # Structured wiki pages built by /wiki compile
 └── archive/
     └── *.md              # Old raw files moved here after compilation
 ```
@@ -69,12 +74,27 @@ You don't need to run the wiki manually. Five hooks keep it fed automatically:
 
 ### Option 1: Install via GitHub (Recommended)
 
+Claude Code:
+
 ```bash
 claude plugin marketplace add https://github.com/hanh-nd/agent-kit
 claude plugin install agent-kit
 ```
 
-The plugin fetches from GitHub, registers the MCP server automatically, and makes all commands available immediately.
+Codex:
+
+```bash
+codex plugin marketplace add https://github.com/hanh-nd/agent-kit.git
+codex
+/plugins # then choose agent-kit
+```
+
+For Codex hooks, add this to `~/.codex/config.toml`:
+
+```toml
+[features]
+hooks = true
+```
 
 **Add credentials** to `~/.claude/credentials` (like `~/.aws/credentials`):
 
@@ -114,14 +134,29 @@ npm run build
 
 **2. Register the plugin**
 
+Claude Code:
+
 ```bash
 claude plugin marketplace add /absolute/path/to/agent-kit
 claude plugin install agent-kit
 ```
 
-This registers the MCP server automatically (pointing to your local build). Do **not** manually add a `kit-agents` entry to `settings.json` — the plugin handles that.
+Codex:
+
+```bash
+codex plugin marketplace add /absolute/path/to/agent-kit
+codex
+/plugins # then choose agent-kit
+```
+
+For Codex hooks, add this to `~/.codex/config.toml`:
+
+```toml
+[features]
+hooks = true
+```
 
-**3. Add credentials** to `~/.claude/credentials`:
+**3. Add credentials** to `~/.claude/credentials` for MCP integrations:
 
 ```bash
 touch ~/.claude/credentials && chmod 600 ~/.claude/credentials
@@ -140,14 +175,14 @@ BITBUCKET_DEFAULT_WORKSPACE = your-default-workspace-slug
 **4. Verify**
 
 ```
-/ak:brainstorm test idea
+/brainstorm test idea
 ```
 
 ---
 
 ### Option 3: Install as Gemini Extension (Optional)
 
-If you want to reuse the commands with [Gemini CLI](https://geminicli.com) (for `/ak:delegate` to Gemini), install it using:
+If you want to reuse the commands with [Gemini CLI](https://geminicli.com) (for `/delegate` to Gemini), install it using:
 
 ```bash
 git clone https://github.com/hanh-nd/agent-kit.git
@@ -167,14 +202,14 @@ npm run build
 npm run dev
 ```
 
-The MCP server source is in `src/`. Agent personas are in `agents/`. Skill modules are in `skills/`.
+The MCP server source is in `src/`. Agent personas are in `agents/`. Canonical skill modules are in `skills/`; `npm run build:skills` generates provider-safe copies into `.claude/skills/`, `.codex/skills/`, and `.gemini/skills/`.
 
 ---
 
 ## Requirements
 
 - Node.js 18+
-- Claude Code (latest)
+- Claude Code, Codex, or Gemini CLI
 
 ---
 
@@ -184,7 +219,7 @@ Credentials are stored in `~/.claude/credentials` (INI format). Keys can also be
 
 ### Jira (via Atlassian REST API)
 
-Used by `/ak:ticket` and `/ak:review-pr`.
+Used by `/ticket` and `/review-pr`.
 
 | Key                    | Description                                                                                                                              |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
@@ -194,7 +229,7 @@ Used by `/ak:ticket` and `/ak:review-pr`.
 
 ### Bitbucket Cloud (via Bitbucket REST API)
 
-Used by `/ak:review-pr`.
+Used by `/review-pr`.
 
 | Key                           | Description                                                                                                                              |
 | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

package/dist/kit-server.js

@@ -20995,7 +20995,7 @@ import * as path from "path";
 
 // src/utils/utils.ts
 function getWorkspaceRoot() {
-  return process.env.WORKSPACE_DIR || process.env.CLAUDE_WORKSPACE || process.env.GEMINI_WORKSPACE || process.env.INIT_CWD || process.env.PWD || process.cwd();
+  return process.env.WORKSPACE_DIR || process.env.CODEX_WORKSPACE || process.env.CODEX_PROJECT_DIR || process.env.CLAUDE_WORKSPACE || process.env.GEMINI_WORKSPACE || process.env.INIT_CWD || process.env.PWD || process.cwd();
 }
 function mcpText(text) {
   return { content: [{ type: "text", text }] };
@@ -21154,6 +21154,30 @@ function sanitizeOutput(text) {
 // src/tools/agent.ts
 var AGENT_TIMEOUT = parseInt(process.env.KIT_AGENT_TIMEOUT || "300000", 10);
 var jobRegistry = /* @__PURE__ */ new Map();
+var INSTALL_HINTS = {
+  gemini: "Install Gemini CLI: https://github.com/google-gemini/gemini-cli",
+  claude: "Install Claude CLI: npm install -g @anthropic-ai/claude-code",
+  codex: "Install Codex CLI: npm install -g @openai/codex"
+};
+function agentArgs(agent, prompt, workspaceRoot) {
+  switch (agent) {
+    case "gemini":
+      return ["-y", "-p", prompt];
+    case "claude":
+      return ["--dangerously-skip-permissions", "-p", prompt];
+    case "codex":
+      return [
+        "exec",
+        "--ask-for-approval",
+        "never",
+        "--sandbox",
+        "workspace-write",
+        "--cd",
+        workspaceRoot,
+        prompt
+      ];
+  }
+}
 function taskSlug(task) {
   return task.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim().split(/\s+/).slice(0, 6).join("-").slice(0, 48);
 }
@@ -21176,9 +21200,9 @@ ${"\u2500".repeat(60)}
 function registerAgentTools(server2) {
   server2.tool(
     "kit_trigger_agent",
-    "!Important: Trigger only when user explicitly asks to delegate a task to an external agent CLI (gemini or claude). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md). Falls back to the other agent CLI if the requested one is not installed.",
+    "!Important: Trigger only when user explicitly asks to delegate a task to an external agent CLI (gemini, claude, or codex). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md).",
     {
-      agent: external_exports.enum(["gemini", "claude"]).describe('The agent CLI to invoke: "gemini" or "claude"'),
+      agent: external_exports.enum(["gemini", "claude", "codex"]).describe('The agent CLI to invoke: "gemini", "claude", or "codex"'),
       task: external_exports.string().describe(
         'Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'
       )
@@ -21199,30 +21223,26 @@ function registerAgentTools(server2) {
             return mcpText(`Error reading task file: ${err}`);
           }
         }
-        let usedAgent = agent;
-        let fallbackReason;
         if (!commandExists(agent)) {
-          const fallback = agent === "gemini" ? "claude" : "gemini";
-          if (commandExists(fallback)) {
-            usedAgent = fallback;
-            fallbackReason = `${agent} CLI not installed, fell back to ${fallback}`;
-          } else {
-            const installHint = agent === "gemini" ? "Install Gemini CLI: https://github.com/google-gemini/gemini-cli" : "Install Claude CLI: npm install -g @anthropic-ai/claude-code";
-            return mcpJson({
-              agent,
-              status: "error",
-              output: "",
-              error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`
-            });
-          }
+          return mcpJson({
+            agent,
+            status: "error",
+            output: "",
+            error: `${agent} CLI is not installed. ${INSTALL_HINTS[agent]}`
+          });
         }
-        const agentArgs = usedAgent === "gemini" ? ["-y", "-p", prompt] : ["--dangerously-skip-permissions", "-p", prompt];
-        const { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), usedAgent);
+        const args = agentArgs(agent, prompt, workspaceRoot);
+        const { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), agent);
         logPath = lp;
         const jobId = randomUUID();
-        const child = spawn(usedAgent, agentArgs, {
+        const child = spawn(agent, args, {
           cwd: workspaceRoot,
-          env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot },
+          env: {
+            ...process.env,
+            CODEX_PROJECT_DIR: workspaceRoot,
+            CODEX_WORKSPACE: workspaceRoot,
+            GEMINI_WORKSPACE: workspaceRoot
+          },
           detached: process.platform !== "win32"
         });
         const killTree = (sig) => {
@@ -21237,7 +21257,7 @@ function registerAgentTools(server2) {
           }
         };
         job = {
-          agent: usedAgent,
+          agent,
           process: child,
           startedAt: /* @__PURE__ */ new Date(),
           chunks: [],
@@ -21270,11 +21290,10 @@ function registerAgentTools(server2) {
           child.on("error", reject);
         });
         return mcpJson({
-          agent: usedAgent,
-          status: fallbackReason ? "fallback" : "success",
+          agent,
+          status: "success",
           log: logPath,
-          output: sanitizeOutput(job.chunks.join("")),
-          ...fallbackReason && { fallback_reason: fallbackReason }
+          output: sanitizeOutput(job.chunks.join(""))
         });
       } catch (error2) {
         if (extra.signal.aborted) {

package/dist/tools/agent.d.ts

@@ -1,5 +1,5 @@
 /**
- * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude)
+ * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude, Codex)
  * Supports handoff file injection and automatic fallback
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

package/dist/tools/agent.js

@@ -1,5 +1,5 @@
 /**
- * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude)
+ * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude, Codex)
  * Supports handoff file injection and automatic fallback
  */
 import { spawn } from 'child_process';
@@ -12,6 +12,30 @@ import { commandExists, sanitizeOutput, validatePath } from './security.js';
 // Configurable timeout via environment variable (default: 5 minutes)
 const AGENT_TIMEOUT = parseInt(process.env.KIT_AGENT_TIMEOUT || '300000', 10);
 const jobRegistry = new Map();
+const INSTALL_HINTS = {
+    gemini: 'Install Gemini CLI: https://github.com/google-gemini/gemini-cli',
+    claude: 'Install Claude CLI: npm install -g @anthropic-ai/claude-code',
+    codex: 'Install Codex CLI: npm install -g @openai/codex',
+};
+function agentArgs(agent, prompt, workspaceRoot) {
+    switch (agent) {
+        case 'gemini':
+            return ['-y', '-p', prompt];
+        case 'claude':
+            return ['--dangerously-skip-permissions', '-p', prompt];
+        case 'codex':
+            return [
+                'exec',
+                '--ask-for-approval',
+                'never',
+                '--sandbox',
+                'workspace-write',
+                '--cd',
+                workspaceRoot,
+                prompt,
+            ];
+    }
+}
 function taskSlug(task) {
     return task
         .toLowerCase()
@@ -34,8 +58,10 @@ function initAgentLog(workspaceRoot, slug, agent) {
     return { logPath: path.relative(workspaceRoot, logFile), logStream };
 }
 export function registerAgentTools(server) {
-    server.tool('kit_trigger_agent', '!Important: Trigger only when user explicitly asks to delegate a task to an external agent CLI (gemini or claude). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md). Falls back to the other agent CLI if the requested one is not installed.', {
-        agent: z.enum(['gemini', 'claude']).describe('The agent CLI to invoke: "gemini" or "claude"'),
+    server.tool('kit_trigger_agent', '!Important: Trigger only when user explicitly asks to delegate a task to an external agent CLI (gemini, claude, or codex). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md).', {
+        agent: z
+            .enum(['gemini', 'claude', 'codex'])
+            .describe('The agent CLI to invoke: "gemini", "claude", or "codex"'),
         task: z
             .string()
             .describe('Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'),
@@ -57,40 +83,31 @@ export function registerAgentTools(server) {
                     return mcpText(`Error reading task file: ${err}`);
                 }
             }
-            // Resolve agent with fallback
-            let usedAgent = agent;
-            let fallbackReason;
             if (!commandExists(agent)) {
-                const fallback = agent === 'gemini' ? 'claude' : 'gemini';
-                if (commandExists(fallback)) {
-                    usedAgent = fallback;
-                    fallbackReason = `${agent} CLI not installed, fell back to ${fallback}`;
-                }
-                else {
-                    const installHint = agent === 'gemini'
-                        ? 'Install Gemini CLI: https://github.com/google-gemini/gemini-cli'
-                        : 'Install Claude CLI: npm install -g @anthropic-ai/claude-code';
-                    return mcpJson({
-                        agent,
-                        status: 'error',
-                        output: '',
-                        error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`,
-                    });
-                }
+                return mcpJson({
+                    agent,
+                    status: 'error',
+                    output: '',
+                    error: `${agent} CLI is not installed. ${INSTALL_HINTS[agent]}`,
+                });
             }
             // Gemini: -y (--yolo) for auto-accept, -p for headless prompt
             // Claude: --dangerously-skip-permissions for auto-accept, -p/--print for headless
-            const agentArgs = usedAgent === 'gemini'
-                ? ['-y', '-p', prompt]
-                : ['--dangerously-skip-permissions', '-p', prompt];
-            const { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), usedAgent);
+            // Codex: exec for headless prompt, never ask for approval, workspace-write sandbox
+            const args = agentArgs(agent, prompt, workspaceRoot);
+            const { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), agent);
             logPath = lp;
             const jobId = randomUUID();
             // detached=true on Unix creates a new process group so we can kill the
             // entire tree (CLI + its sub-agents) with process.kill(-pid, signal).
-            const child = spawn(usedAgent, agentArgs, {
+            const child = spawn(agent, args, {
                 cwd: workspaceRoot,
-                env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot },
+                env: {
+                    ...process.env,
+                    CODEX_PROJECT_DIR: workspaceRoot,
+                    CODEX_WORKSPACE: workspaceRoot,
+                    GEMINI_WORKSPACE: workspaceRoot,
+                },
                 detached: process.platform !== 'win32',
             });
             const killTree = (sig) => {
@@ -107,7 +124,7 @@ export function registerAgentTools(server) {
                 }
             };
             job = {
-                agent: usedAgent,
+                agent,
                 process: child,
                 startedAt: new Date(),
                 chunks: [],
@@ -142,11 +159,10 @@ export function registerAgentTools(server) {
                 child.on('error', reject);
             });
             return mcpJson({
-                agent: usedAgent,
-                status: fallbackReason ? 'fallback' : 'success',
+                agent,
+                status: 'success',
                 log: logPath,
                 output: sanitizeOutput(job.chunks.join('')),
-                ...(fallbackReason && { fallback_reason: fallbackReason }),
             });
         }
         catch (error) {

package/dist/utils/utils.js

@@ -1,5 +1,7 @@
 export function getWorkspaceRoot() {
     return (process.env.WORKSPACE_DIR ||
+        process.env.CODEX_WORKSPACE ||
+        process.env.CODEX_PROJECT_DIR ||
         process.env.CLAUDE_WORKSPACE ||
         process.env.GEMINI_WORKSPACE ||
         process.env.INIT_CWD ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanhnd/agent-kit",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "Super Engineer - Team of AI Agents for software development (Claude Code Plugin)",
   "type": "module",
   "main": "dist/kit-server.js",
@@ -18,8 +18,9 @@
     "url": "git+https://github.com/hanh-nd/agent-kit.git"
   },
   "scripts": {
+    "build:skills": "node scripts/build-skills.js",
     "prepublishOnly": "npm run build",
-    "build": "tsc && npm run bundle",
+    "build": "npm run build:skills && tsc && npm run bundle",
     "bundle": "esbuild src/kit-server.ts --bundle --platform=node --format=esm --outfile=dist/kit-server.js --external:node:* --banner:js=\"import { createRequire } from 'module'; const require = createRequire(import.meta.url);\"",
     "dev": "tsc --watch",
     "test": "node --test tests/*.test.js"