@haposoft/cafekit 0.14.0 → 0.14.2

package/src/claude/hooks/spec-gate.cjs

@@ -84,11 +84,12 @@ try {
   const newlyDone = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done' && featureCache[tp] !== 'done'
   );
-  if (newlyDone.length === 0) process.exit(0);
-
   // /m so ^ matches line starts (Evidence is never at byte 0 of the file).
+  // legacy heading aliases: read-compat only, no longer advertised
   const EVID_RE = /^#{2,3}\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/m;
-  const PROOF_RE = /(PASS|FAIL|exit code|passed|✓)/;
+  const PASS_MARKER_RE = /^\s*Verification:\s*PASS\s*$/m;
+  const LEGACY_SUCCESS_RE = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
+  const EXPLICIT_FAILURE_RE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
 
   /** Body of first Evidence heading until next same-or-higher heading. */
   function evidenceBody(text) {
@@ -122,12 +123,20 @@ try {
     const body = evidenceBody(text);
     if (body === null || !EVID_RE.test(text)) {
       fails.push('b');
-    } else if (/\{\{[^}]+\}\}/.test(body) || !(/```/.test(body) || PROOF_RE.test(body))) {
+    } else if (
+      /\{\{[^}]+\}\}/.test(body) ||
+      EXPLICIT_FAILURE_RE.test(body) ||
+      !(PASS_MARKER_RE.test(body) || LEGACY_SUCCESS_RE.test(body))
+    ) {
       fails.push('c');
     }
 
     const at = taskRegistry[taskPath]?.completed_at;
-    if (typeof at !== 'string' || at.trim() === '') fails.push('d');
+    if (
+      typeof at !== 'string' ||
+      !/^\d{4}-\d{2}-\d{2}T/.test(at) ||
+      Number.isNaN(Date.parse(at))
+    ) fails.push('d');
     return fails;
   }
 
@@ -135,7 +144,8 @@ try {
     .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
     .filter((f) => f.fails.length > 0);
 
-  // Leave failing newly-done at old cache status so the gate re-fires next Stop.
+  // Always persist status transitions, including done → pending. Leave failing
+  // newly-done tasks at their old status so the gate re-fires next Stop.
   try {
     const nextFeature = { ...featureCache, ...currentStatuses };
     for (const { taskPath } of failures) {
@@ -147,6 +157,7 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
+  if (newlyDone.length === 0) process.exit(0);
   if (failures.length === 0) process.exit(0);
 
   const lines = [
@@ -155,7 +166,7 @@ try {
   for (const { taskPath, fails } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
     lines.push(
-      `  Fix: add a verification receipt to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`: commands run + outcomes, then re-sync spec.json`
+      `  Fix: add \`Verification: PASS\` plus commands and successful outcomes to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`, then re-sync spec.json`
     );
   }
   process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');

package/src/claude/hooks/spec-state.cjs

@@ -30,6 +30,10 @@ try {
     if (fs.existsSync(p)) runtime = JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch { /* ignore */ }
 
+  // Reminder toggle — same key the OpenCode spec-state plugin honors.
+  // (The Stop completion gate has its own toggle: spec.completion_gate.)
+  if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
+
   const baseDir   = process.env.PROJECT_ROOT || cwd;
   const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
 

package/src/claude/hooks/state.cjs

@@ -120,19 +120,29 @@ try {
       }
     }
 
+    const changed = [];
     try {
       const diff = execSync('git diff --name-only HEAD', {
         encoding: 'utf8',
         timeout: 3000,
         stdio: ['pipe', 'pipe', 'pipe']
       }).trim();
+      if (diff) changed.push(...diff.split('\n'));
+    } catch {
+      // A repository without HEAD can still report untracked files below.
+    }
 
-      if (diff) {
-        data.modifiedFiles = diff.split('\n').slice(0, MAX_MODIFIED_FILES_DISPLAY);
-      }
+    try {
+      const untracked = execSync('git ls-files --others --exclude-standard', {
+        encoding: 'utf8',
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      if (untracked) changed.push(...untracked.split('\n'));
     } catch {
       // fail-open
     }
+    data.modifiedFiles = [...new Set(changed)].slice(0, MAX_MODIFIED_FILES_DISPLAY);
 
     return data;
   }

package/src/claude/hooks/usage.cjs

@@ -8,6 +8,12 @@
  * Fetches Claude Code usage limits from Anthropic OAuth API and writes to cache.
  * Cache is read by status.cjs for statusline display.
  *
+ * ⚠ EXPERIMENTAL / UNDOCUMENTED API: api.anthropic.com/api/oauth/usage with the
+ * "oauth-2025-04-20" beta header is not a public contract and may break or
+ * change shape without notice. Every failure path degrades to
+ * status:"unavailable" (statusline hides the segment) — never block on it.
+ * Disable entirely with "usage": { "enabled": false } if it misbehaves.
+ *
  * Features:
  * - Cross-platform credential retrieval (macOS Keychain, file-based)
  * - Throttled API calls: 1 min (prompt) / 5 min (tool use)

package/src/claude/migration-manifest.json

@@ -13,6 +13,7 @@
       "chrome-devtools",
       "code-review",
       "debug",
+      "delegate",
       "develop",
       "devops",
       "docs",

package/src/claude/rules/orchestrator.md

@@ -23,7 +23,7 @@ Example prompt:
 ## Resource Constraints
 
 - Each subagent has a **200K token context window** — scope tasks to fit comfortably within it
-- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out
+- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries the 200K budget above)
 - Prefer fewer, well-scoped agents over many overlapping ones
 - Include system resource info (from hook injection) when delegating tasks so subagents can self-regulate
 
@@ -48,7 +48,7 @@ For implementation tasks, keep the chain explicit:
 2. Verify with `test-runner` using task files and exact evidence commands.
 3. Review with `code-auditor` using task files, design contracts, and the diff.
 
-Do not dispatch multiple implementation agents against the same files or same task. Parallelize only independent scopes with distinct file ownership.
+Do not dispatch multiple implementation agents against the same files or same task **within the same working tree**. Parallelize only independent scopes with distinct file ownership — the sanctioned pattern for parallel implementation is **worktree isolation** (one agent per task, each in its own git worktree) with a **single writer per file per wave** and orchestrator-only spec-state writes, per `skills/develop/references/parallel-waves.md`.
 
 ### Parallel (independent tasks)
 

package/src/claude/rules/skill-domain-routing.md

@@ -1,88 +1,29 @@
 # Skill Domain Routing
 
-Use this decision tree to choose domain skills from the installed CafeKit skill set. This is advisory routing, not an automatic hook.
-
-## Frontend And UI
-
-```text
-User wants to...
-├── choose style, color, layout, UX, design system       -> /hapo:frontend-design
-├── build React/TypeScript UI components                 -> /hapo:frontend-development
-├── optimize React/Next.js performance or rerenders      -> /hapo:react-best-practices
-├── apply deep UI/UX intelligence, visual polish         -> /hapo:ui-ux-pro-max
-└── test UI in browser                                   -> /hapo:web-testing or /hapo:agent-browser
-```
-
-Use `/hapo:react-best-practices` for performance/re-render patterns. Use `/hapo:frontend-development` for normal implementation.
-
-## Backend, Data, And Infrastructure
-
-```text
-User wants to...
-├── API, service, auth, database-backed feature          -> /hapo:backend-development
-├── deployment, Docker, Kubernetes, Cloudflare, CI/CD     -> /hapo:devops
-└── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
-```
-
-## Codebase Understanding
-
-```text
-User wants to...
-├── answer questions from source code/docs/specs/config    -> /hapo:question
-├── find files, locate code, scan project structure       -> /hapo:inspect
-├── diagnose an error or failing check                    -> /hapo:debug
-├── understand possible side effects                      -> /hapo:inspect
-└── compare external approaches or best practices         -> /hapo:research
-```
-
-Local source truth comes from `/hapo:inspect`; external/current knowledge comes from `/hapo:research`.
-
-## Documentation
-
-```text
-User wants to...
-├── ask/answer documentation questions from source         -> /hapo:question
-├── create missing project docs                           -> /hapo:docs --init
-├── update docs after source changes                      -> /hapo:docs --update
-├── summarize codebase quickly                            -> /hapo:docs --summarize
-├── reconstruct as-is docs from legacy source code        -> /hapo:docs --reconstruct <scope>
-└── create a future feature spec                          -> /hapo:specs
-```
-
-Keep as-is reconstruction separate from future requirements. Reconstructed docs document current behavior; specs define requested changes.
-
-## Testing And Browser
-
-```text
-User wants to...
-├── run test suites, coverage, scoped verification        -> /hapo:test
-├── E2E/unit/integration/load/security/a11y strategy      -> /hapo:web-testing
-├── drive a browser with snapshots or Browserbase         -> /hapo:agent-browser
-└── Chrome DevTools/Puppeteer evidence                    -> /hapo:chrome-devtools
-```
-
-## Documents And Media
-
-```text
-User wants to...
-├── PowerPoint/slides                                     -> /hapo:pptx
-├── Word documents                                        -> /hapo:docx
-├── PDFs                                                  -> /hapo:pdf
-├── spreadsheets/CSV/XLSX                                 -> /hapo:xlsx
-└── image/audio/video/document multimodal analysis        -> /hapo:ai-multimodal
-```
-
-## Git And Release
-
-```text
-User wants to...
-├── commit, branch, tag, push, release prep               -> /hapo:git
-└── review before release                                 -> /hapo:code-review
-```
-
-## Usage Notes
-
-- Read the selected skill's `SKILL.md` before acting.
-- Do not activate a skill only because one keyword appears. Use the whole user intent.
-- If a task spans multiple domains, name the primary skill and mention the secondary skill in the plan.
-- If no domain skill fits, use the core CafeKit workflow in `skill-workflow-routing.md`.
+Advisory routing for installed domain skills (not an automatic hook). Read the selected skill's `SKILL.md` before acting.
+
+| Domain / intent | Skill |
+|---|---|
+| answer questions from source code/docs/specs/config | `/hapo:question` |
+| file discovery, structure, blast radius | `/hapo:inspect` |
+| style / layout / design system | `/hapo:frontend-design` |
+| React/TypeScript UI implementation | `/hapo:frontend-development` |
+| React/Next performance / re-renders | `/hapo:react-best-practices` |
+| deep UI/UX polish | `/hapo:ui-ux-pro-max` |
+| API, service, auth, database | `/hapo:backend-development` |
+| deploy / Docker / K8s / Cloudflare / CI | `/hapo:devops` |
+| mobile (RN / Flutter / iOS / Android) | `/hapo:mobile-development` |
+| docs init / update / summarize | `/hapo:docs --init` / `--update` / `--summarize` |
+| as-is reconstruction from legacy code | `/hapo:docs --reconstruct <scope>` |
+| future feature requirements | `/hapo:specs` |
+| run suites / scoped verification | `/hapo:test` |
+| E2E / load / a11y strategy | `/hapo:web-testing` |
+| browser snapshots / Browserbase | `/hapo:agent-browser` |
+| Chrome DevTools evidence | `/hapo:chrome-devtools` |
+| diagnose error / CI failure | `/hapo:debug` |
+| external best practices / tool compare | `/hapo:research` |
+| pptx / docx / pdf / xlsx / multimodal | `/hapo:pptx` / `docx` / `pdf` / `xlsx` / `ai-multimodal` |
+| commit / branch / release prep | `/hapo:git` |
+| review before release | `/hapo:code-review` |
+
+Pick one primary domain skill; name a secondary only when it changes execution. If none fit, use `skill-workflow-routing.md`.

package/src/claude/rules/skill-workflow-routing.md

@@ -4,84 +4,21 @@ Use this rule instead of automatic prompt routing. Read the user's intent, choos
 
 Do not inject or force a skill when the user explicitly asks for a direct answer, a specific command, or a different workflow.
 
-## Core Specification Workflow
+Claude Code selects skills from frontmatter descriptions; trust it for clear intents.
 
-```text
-/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
-```
-
-| User intent | Suggested start |
-|---|---|
-| ask about source code, docs, specs, config, dependencies, or external/current technical facts | `/hapo:question` |
-| vague request, missing acceptance criteria, unclear scope, stakeholder questions | ask one clarification or use `/hapo:brainstorm` |
-| unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
-| create requirements, design, task breakdown, validate spec | `/hapo:specs` |
-| implement an approved spec or a specific task file | `/hapo:develop` |
-| run tests, QA, runtime verification | `/hapo:test` |
-| review code quality, security, regressions, maintainability | `/hapo:code-review` |
-| commit, tag, push, branch, release prep | `/hapo:git` |
-
-## Bug And Incident Workflow
-
-```text
-/hapo:debug -> /hapo:hotfix -> /hapo:test -> /hapo:code-review
-```
-
-| User intent | Suggested start |
-|---|---|
-| diagnose why something fails, find root cause, inspect CI/logs | `/hapo:debug` |
-| fix a known bug after diagnosis, urgent regression, production issue | `/hapo:hotfix` |
-| verify the fix and affected behavior | `/hapo:test` |
-| check side effects before closeout | `/hapo:code-review` |
-
-`/hapo:debug` is diagnostic-only. Do not edit product code there. Use `/hapo:hotfix` when the user asks to fix.
-
-## Existing System Documentation Workflow
+## Core chain
 
 ```text
-/hapo:inspect -> /hapo:docs --reconstruct -> human review -> /hapo:specs -> /hapo:develop
-```
-
-| User intent | Suggested start |
-|---|---|
-| understand source structure or locate implementation areas | `/hapo:inspect` |
-| rebuild as-is docs/requirements from a legacy codebase | `/hapo:docs --reconstruct <scope>` |
-| update normal project docs | `/hapo:docs --update` |
-| initialize missing docs | `/hapo:docs --init` |
-| summarize a codebase without full docs work | `/hapo:docs --summarize` |
-
-Do not turn reconstructed docs directly into implementation. Human review must approve the as-is docs before `/hapo:specs` defines future changes.
-
-## Research And Analysis Workflow
-
-```text
-/hapo:inspect -> /hapo:research
+/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
-| User intent | Suggested start |
-|---|---|
-| file discovery, codebase structure, source scouting | `/hapo:inspect` |
-| affected files, blast radius, dependency impact, side effects | `/hapo:inspect` |
-| external best practices, tool comparison, technical investigation | `/hapo:research` |
-
-Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
-
-## Output Artifact Workflow
-
-| User intent | Suggested skill |
-|---|---|
-| PowerPoint or slide deck creation/editing | `/hapo:pptx` |
-| Word documents | `/hapo:docx` |
-| PDF processing | `/hapo:pdf` |
-| spreadsheets | `/hapo:xlsx` |
-| screenshots, images, audio, video, OCR, multimodal understanding | `/hapo:ai-multimodal` |
+Bug path: `/hapo:debug -> /hapo:hotfix` then test/review. As-is docs: `/hapo:inspect` → `/hapo:docs --reconstruct <scope>` → human review → specs → develop. Delegate implementation to an external agent CLI: `/hapo:delegate`.
 
-## Selection Rules
+## Ambiguous cases
 
-- Pick one primary workflow first.
-- Add a secondary skill only when it materially changes execution.
-- Prefer explicit user commands over this table.
-- If two workflows conflict, ask one concise clarification.
-- If the user asks a factual or project question before workflow selection, use `/hapo:question`.
-- If missing information blocks workflow selection, ask one concise clarification or use `/hapo:brainstorm`.
-- If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.
+| Ambiguity | Prefer | Not when |
+|---|---|---|
+| debug-vs-hotfix | `/hapo:debug` first when root cause unknown | Root cause is known / trivial local fix → `/hapo:hotfix` |
+| question-vs-research | `/hapo:question` to ask about source code, docs, specs, config, dependencies, or project facts | External best-practice comparison / multi-source investigation → `/hapo:research` |
+| question-vs-brainstorm | `/hapo:question` for factual answers with evidence | Vague idea, missing acceptance criteria, unclear scope, multi-approach tradeoffs → `/hapo:brainstorm` |
+| specs-vs-brainstorm | `/hapo:specs` when intent and acceptance are concrete enough | Unclear idea / architecture choices still open → `/hapo:brainstorm` first |

package/src/claude/rules/state-sync.md

@@ -28,4 +28,4 @@ Before returning control to the user or orchestrator, the agent **MUST**:
 
 ### Completion gate (Stop)
 
-Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, an Evidence section (or legacy `Task Test Plan & Verification Evidence` / `Verification & Evidence`) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).
+Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, `## Evidence` (legacy heading aliases still parse) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).

package/src/claude/runtime.json

@@ -13,21 +13,21 @@
   },
   "paths": {
     "docs": "docs",
-    "specs": "specs"
+    "specs": "specs",
+    "plans": "plans"
   },
   "spec": {
     "scaffold_guard": true,
-    "completion_gate": true
+    "completion_gate": true,
+    "tollgate": true
+  },
+  "develop": {
+    "parallel": true
   },
   "locale": {
     "thinkingLanguage": null,
     "responseLanguage": null
   },
-  "skills": {
-    "research": {
-      "useGemini": true
-    }
-  },
   "usage": {
     "enabled": true
   },

package/src/claude/scripts/validate-spec-output.cjs

@@ -113,6 +113,7 @@ function validateTaskSections(taskPath, content, errors) {
     hasHeading(content, 'Requirements') || /_Requirements:\s*[^_\n]+_/i.test(content);
   const hasRelatedFiles = hasHeading(content, 'Related Files');
   const hasCompletionCriteria = hasHeading(content, 'Completion Criteria');
+  // legacy heading aliases: read-compat only, no longer advertised
   const hasEvidence =
     hasHeading(content, 'Evidence') ||
     hasHeading(content, 'Task Test Plan & Verification Evidence') ||
@@ -365,6 +366,11 @@ function validateSpec(specDir) {
   const contractDefs = fs.existsSync(designPath)
     ? extractContractDefs(fs.readFileSync(designPath, 'utf8'))
     : new Map();
+  if (taskFiles.length >= 5 && contractDefs.size === 0) {
+    warnings.push(
+      'design.md declares no contract blocks; specs spanning BE/FE must declare shared shapes (<!-- contract:NAME -->)',
+    );
+  }
   for (const taskFile of taskFiles) {
     const fullPath = path.join(specDir, taskFile);
     const content = fs.readFileSync(fullPath, 'utf8');

package/src/claude/skills/code-review/references/spec-compliance-review.md

@@ -24,7 +24,7 @@ Do not attempt a standard text-based review if the project includes Visual Specs
 3. If NO (Markdown Spec only): Read the spec directly and extract:
    - requirement bullets
    - task `Completion Criteria`
-   - task `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+   - task `## Evidence` (legacy heading aliases still parse)
    - canonical contracts/invariants from `design.md`
    Then verify the changed files against those concrete obligations.
 

package/src/claude/skills/delegate/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: hapo:delegate
+description: "Delegate implementation tasks from Claude Code to external CLI agents (Codex or Grok). Covers task-brief authoring, non-interactive dispatch, permission setup, background monitoring, resume, and independent verification of the returned work."
+user-invocable: true
+when_to_use: "Invoke when the user asks to assign/offload a coding task to codex or grok, or to run work on an external agent CLI."
+category: orchestration
+keywords: [delegate, codex, grok, external-agent, offload, assign]
+argument-hint: "<codex|grok> <task-description | path/to/task-brief.md>"
+metadata:
+  author: haposoft
+  version: "1.0.0"
+---
+# Delegate to External Agents (Codex / Grok)
+
+Dispatch a well-scoped implementation task to an external agentic CLI — **Codex** (OpenAI) or **Grok** (xAI Grok Build) — from a Claude Code session acting as orchestrator. Claude Code stays responsible for: writing the task brief, choosing safe permissions, monitoring, and **independently verifying** the result before reporting completion.
+
+**Mantra:** Brief precisely, sandbox tightly, verify independently.
+
+## When to Use
+
+- User explicitly asks to hand a task to codex/grok ("giao cho codex", "assign to grok").
+- Parallel workstreams: Claude Code keeps orchestrating while an external agent implements a scoped task.
+- Cross-checking: a second model implements or reviews independently.
+
+Do NOT delegate: tasks touching secrets/`.env`, deploys to shared environments, destructive migrations on live data, or tasks whose scope is still unclear (clarify first — a vague brief wastes an entire agent run).
+
+## Workflow
+
+### 1. Write the task brief (mandatory, file-based)
+
+External agents run **fresh-context** — they see none of your conversation. Write the brief to a file (convention: `plans/<slug>-task.md` in the target repo), never inline-only. Follow the orchestrator prompt rules (`.claude/rules/orchestrator.md`): the brief must be self-contained.
+
+Required sections:
+
+```markdown
+# Task: <title>
+
+> Self-contained brief for a fresh-context agent. Date: <YYYY-MM-DD>.
+> FOUNDATION: <state of the working tree the agent builds on — branch,
+> uncommitted changes it must NOT revert, verified test/build status>
+
+## Context        — project, architecture, why this task exists
+## Scope          — numbered work items with exact file paths
+## Constraints    — what must NOT be touched (staging data, .env, deploys,
+                    unrelated refactors); repo rules to obey (CLAUDE.md)
+## Completion Criteria — verifiable, numbered
+## Evidence required   — exact commands whose output proves completion
+```
+
+Rules of thumb:
+- Name exact files and line-level anchors where known; agents burn tokens rediscovering what you already know.
+- State dependency order explicitly if this task builds on another agent's uncommitted work ("do NOT revert/stash existing changes").
+- Put user-pending decisions in Constraints as forbidden actions (e.g. "do NOT touch staging rows until user confirms").
+
+### 2. Protect the working tree
+
+Before dispatch, snapshot state you cannot afford to lose:
+
+```bash
+git stash push -u -m "backup: <reason>" && git stash apply -q   # snapshot, keep tree intact
+```
+
+Prefer isolation when the task is risky or parallel to other edits:
+- Grok: `--worktree=<name>` (built-in).
+- Codex: run with `-C <worktree-dir>` after creating a git worktree yourself.
+
+If the agent must build on uncommitted changes, isolation is not possible — use the stash-backup pattern above and say so in the brief.
+
+### 3. Dispatch
+
+Load the matching reference for exact flags, permission model, and pitfalls:
+- **Codex:** `./references/codex-delegation.md`
+- **Grok:** `./references/grok-delegation.md`
+
+Common principles:
+- Run non-interactive/headless mode in a **background** shell; both CLIs stream progress to stdout.
+- Grant the **minimum** permission set that lets the agent write code and run its Evidence commands (npm/node). Never grant full-access/bypass modes for routine tasks.
+- Model/effort overrides: pass explicitly rather than relying on user config, so the run is reproducible.
+- Capture the output file path; check progress after ~20–30s to confirm the agent actually started (auth errors, bad flags, and permission blocks surface early).
+
+### 4. Monitor
+
+- Poll the background output periodically; look for permission-block messages — both CLIs degrade to "design-only" output instead of failing loudly when a write tool is blocked.
+- If blocked on permissions: **resume the same session** with corrected flags (both CLIs support resume; see references) — context is preserved, work continues instead of restarting.
+- Apply the 3-strike rule from `.claude/rules/orchestrator.md`: same failure 3+ times → stop, escalate to user with evidence.
+
+### 5. Verify independently (non-negotiable)
+
+External-agent claims are **not** evidence (CLAUDE.md: no completion claim without fresh proof from the current run). After the agent reports done:
+
+1. `git status` / `git diff` — confirm the changed file set matches the brief's Scope; flag out-of-scope edits.
+2. Run the brief's Evidence commands yourself (tests, build). The agent's transcript of a test run does not count.
+3. Check Completion Criteria one by one.
+4. Report to user: what was delegated, what came back, verification results, and any deviations.
+
+### 6. Sync
+
+- Keep the brief file updated (checklist ticks / blockers) so it doubles as task state.
+- If a spec (`specs/<slug>/`) governs the work, follow the Tollgate Protocol (`.claude/rules/state-sync.md`): update `spec.json` + task files only after verification passes.
+- The user decides commit/merge/deploy — delegation ends at verified working-tree changes unless told otherwise.
+
+## Choosing Codex vs Grok
+
+Both are capable general coding agents; prefer the one the user names. If unspecified:
+
+| Factor | Codex | Grok |
+|---|---|---|
+| Isolation | manual git worktree + `-C` | built-in `--worktree=<name>` |
+| Structured output | `--output-schema` (JSON Schema) | `--json-schema` |
+| Self-verification | ask in the brief | `--check` flag appends a verify loop |
+| Resume | `codex exec resume <id>` | `grok --resume <id>` |
+
+## Rules
+
+- Never grant `--dangerously-bypass-approvals-and-sandbox` (codex) or `bypassPermissions` (grok) for routine delegation.
+- Never let an external agent touch `.env`, secrets, staging/production data, or run deploys.
+- Never report the agent's own success claim as completion — verify first.
+- Never re-dispatch a blocked task unchanged (BLOCKED ≠ retry; fix the cause: permissions, context, or scope).
+- One writer per file set: don't run two agents (or an agent + yourself) editing the same files concurrently.
+
+## References
+
+- `./references/codex-delegation.md` — Codex CLI: exec mode, sandbox/approval model, resume, pitfalls
+- `./references/grok-delegation.md` — Grok CLI: headless mode, worktree, permission rules, resume, pitfalls

package/src/claude/skills/delegate/references/codex-delegation.md

@@ -0,0 +1,71 @@
+# Delegating to Codex CLI
+
+Verified against codex-cli 0.144.4 (2026-07). Re-check `codex exec --help` if flags fail — the CLI evolves quickly.
+
+## Preflight
+
+```bash
+which codex && codex --version        # installed?
+codex doctor                          # auth + runtime health (slow; run only when suspicious)
+```
+
+User-level defaults live in `~/.codex/config.toml` (`model`, `model_reasoning_effort`, agents, MCP servers). Overrides via `-m` and `-c key=value` beat config — pass them explicitly for reproducible runs.
+
+## Non-interactive dispatch: `codex exec`
+
+Reads the prompt from an argument, or from **stdin** when the argument is `-`. Prefer stdin + brief file:
+
+```bash
+codex exec \
+  -m gpt-5.6-terra \
+  -c model_reasoning_effort='"max"' \
+  --sandbox workspace-write \
+  -o /tmp/codex-last-message.txt \
+  - < plans/<slug>-task.md
+```
+
+Run it in a background shell and poll the output.
+
+### Key flags
+
+| Flag | Notes |
+|---|---|
+| `-m <model>` | model ID, e.g. `gpt-5.6-terra` (note spelling: *terra*) |
+| `-c model_reasoning_effort='"max"'` | TOML-parsed value — keep the inner quotes |
+| `--sandbox <mode>` | `read-only` \| `workspace-write` \| `danger-full-access` |
+| `-o <file>` | write the agent's final message to a file — easiest completion check |
+| `-C <dir>` | working root (use for delegating into a git worktree) |
+| `--add-dir <dir>` | extra writable dirs alongside the workspace |
+| `--output-schema <file>` | JSON Schema constraining the final response |
+| `--json` | JSONL event stream on stdout (machine parsing) |
+| `--ephemeral` | don't persist session files |
+
+### Pitfalls
+
+- **`-a` / `--ask-for-approval` is TUI-only.** `codex exec` rejects it (`error: unexpected argument '-a' found`). Exec mode is implicitly `approval: never` — sandbox mode is your only control there.
+- **`workspace-write` limits writes, not reads**, to: workdir, `/tmp`, `$TMPDIR`. Network is available. Commands needing writes outside (global installs) will fail — keep Evidence commands repo-local.
+- **Effort value is TOML**: `-c model_reasoning_effort='"max"'` (double-quoted inside single quotes). Bare `max` may parse as a literal string too, but the quoted form is unambiguous.
+- Startup banner echoes `model:`, `reasoning effort:`, `sandbox:` — **verify these lines** ~20s after dispatch instead of assuming flags took effect.
+- User config may define agents/hooks/MCP servers that activate automatically; `--ignore-user-config` gives a clean run if they interfere.
+
+## Monitor & verify liveness
+
+```bash
+# ~20-30s after dispatch: banner shows model/sandbox; then agent narration follows
+head -c 1200 <output-file>
+tail -c 1500 <output-file>            # progress
+cat /tmp/codex-last-message.txt       # exists → run finished; content = final report
+```
+
+## Resume
+
+```bash
+codex exec resume --last "<follow-up>"          # most recent session
+codex exec resume <SESSION_ID> "<follow-up>"    # by id (session id printed in banner)
+```
+
+Use resume (not a fresh dispatch) when: permission-blocked mid-run, follow-up fixes after your verification failed, or continuing a design into implementation.
+
+## Review mode
+
+`codex review` (or `codex exec review`) runs a non-interactive code review of the current repo — useful as an independent second-opinion pass on another agent's diff.