@haposoft/cafekit 0.13.3 → 0.13.4

package/README.md

@@ -2,7 +2,7 @@
 
 > Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
 
-[![Version](https://img.shields.io/badge/version-0.9.3-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.13.4-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Primary-orange.svg)](https://claude.ai/code)
 
@@ -46,6 +46,26 @@ Requirements:
 - Node.js 18+
 - Claude Code project with `.claude/`, OpenCode project with `.opencode/` or `opencode.json`, or choose a runtime when prompted
 
+## Git ignore policy
+
+On install, CafeKit updates the **project-root** `.gitignore` with:
+
+```text
+# CafeKit / Ecosystem
+specs/_shared/
+plans/
+!plans/templates/
+.cafekit-backup/
+.cafekit.lock
+.claude/
+.opencode/
+```
+
+Runtime folders are local — reinstall with `npx @haposoft/cafekit` rather than
+committing them. Inside the runtime, CafeKit also installs `.claude/.gitignore`
+(or `.opencode/.gitignore`) so secrets, skill dependencies, session state, and
+hook logs stay out of git even if someone force-adds the folder.
+
 ## What Gets Installed
 
 Claude Code targets:

package/bin/phases/root-config.js

@@ -1,13 +1,29 @@
 /**
  * Phase: root project configuration (.gitignore).
  *
- * Ensures the root .gitignore carries CafeKit-managed patterns, including the
- * new install backup dir and lock file so they never get committed. Honors dry-run.
+ * Ensures the root .gitignore carries CafeKit-managed patterns:
+ *  - workflow dirs (plans, shared research)
+ *  - install safety artifacts (backup, lock)
+ *  - runtime folders (.claude/, .opencode/) — reinstall via
+ *    `npx @haposoft/cafekit`; do not commit the local payload
+ *
+ * Layered with the in-folder `.claude/.gitignore` /
+ * `.opencode/.gitignore` templates (secrets, skill deps, session
+ * state) so force-adds and partial un-ignores stay safe.
+ *
+ * Honors dry-run.
  */
 
 const fs = require('fs');
 const path = require('path');
 
+/** True if `lines` already carries `pattern` with or without a trailing slash. */
+function hasPattern(lines, pattern) {
+  const bare = pattern.replace(/\/$/, '');
+  const withSlash = bare + '/';
+  return lines.includes(pattern) || lines.includes(bare) || lines.includes(withSlash);
+}
+
 function ensureGitignore(ctx) {
   const gitignorePath = path.join(process.cwd(), '.gitignore');
   const header = '# CafeKit / Ecosystem';
@@ -16,7 +32,10 @@ function ensureGitignore(ctx) {
     'plans/',
     '!plans/templates/',
     '.cafekit-backup/',
-    '.cafekit.lock'
+    '.cafekit.lock',
+    // Local runtime payload — reinstall with npx; keep out of git
+    '.claude/',
+    '.opencode/'
   ];
   const prefix = ctx.dryRun ? '[dry-run] ' : '';
 
@@ -30,7 +49,7 @@ function ensureGitignore(ctx) {
 
   const content = fs.readFileSync(gitignorePath, 'utf8');
   const lines = content.split('\n').map((l) => l.trim());
-  const missing = patterns.filter((p) => !lines.includes(p));
+  const missing = patterns.filter((p) => !hasPattern(lines, p));
 
   if (missing.length > 0) {
     let newContent = content;
@@ -46,4 +65,4 @@ function ensureGitignore(ctx) {
   }
 }
 
-module.exports = { ensureGitignore };
+module.exports = { ensureGitignore, hasPattern };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/gitignore

@@ -1,19 +1,26 @@
-# Environment and Sandbox credentials within .claude
+# CafeKit local runtime (.claude/ or .opencode/)
+# Also ignored at project root by the installer. This file protects
+# force-adds (`git add -f`) and partial un-ignores of the runtime folder.
+
+# Secrets and local credentials
 .env
 .env.*
 !.env.example
 
-# Virtual environments for python scripts (skills)
+# Skill dependency installs (Python venv + npm)
 skills/.venv/
+skills/**/.venv/
+skills/**/node_modules/
 .venv/
 venv/
-skills/**/node_modules/
 __pycache__/
+**/__pycache__/
 *.pyc
 
-# System generated state, caches, and logs
+# Generated session state, caches, and logs
 session-state/
 hooks/.logs/
+plugins/.logs/
 agent-memory/
 settings.bak.json
 .mcp.json

package/src/claude/migration-manifest.json

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

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

@@ -66,6 +66,14 @@ Do not turn reconstructed docs directly into implementation. Human review must a
 
 Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
 
+## Delegation Workflow
+
+| User intent | Suggested skill |
+|---|---|
+| assign/offload an implementation task to an external agent CLI (codex, grok) | `/hapo:delegate` |
+
+Claude Code remains the orchestrator: it writes the task brief, dispatches, monitors, and independently verifies the returned work.
+
 ## Output Artifact Workflow
 
 | User intent | Suggested skill |

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.

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

@@ -0,0 +1,84 @@
+# Delegating to Grok CLI (Grok Build)
+
+Verified against grok 0.2.101 (2026-07). Re-check `grok --help` if flags fail.
+
+## Preflight
+
+```bash
+which grok && grok --version
+grok models          # available model IDs
+```
+
+## Non-interactive dispatch
+
+Two forms:
+
+```bash
+# single-turn from a brief file (preferred for delegation)
+grok --prompt-file plans/<slug>-task.md \
+     --worktree=<slug> \
+     --check \
+     --permission-mode acceptEdits \
+     --allow "Bash(npm:*)" --allow "Bash(node:*)" \
+     --output-format plain
+
+# short single-turn prompt
+grok -p "<prompt>"
+```
+
+Run in a background shell and poll the output.
+
+### Key flags
+
+| Flag | Notes |
+|---|---|
+| `--prompt-file <path>` | single-turn prompt from file |
+| `-p, --single <prompt>` | single-turn inline prompt |
+| `--worktree=<name>` | built-in git worktree isolation (grok-managed; see pitfalls) |
+| `--check` | appends a self-verification loop (headless only) — use it |
+| `--permission-mode <mode>` | `default` \| `acceptEdits` \| `auto` \| `dontAsk` \| `bypassPermissions` \| `plan` |
+| `--allow "<RULE>"` / `--deny "<RULE>"` | permission rules, Claude Code syntax: `Bash(npm:*)`, `Write`, `Edit` |
+| `-m <model>` / `--reasoning-effort` | model + effort overrides |
+| `--max-turns <N>` | hard cap on agent turns |
+| `--json-schema '<schema>'` | structured final output |
+| `--output-format plain\|json\|streaming-json` | headless output format |
+| `--resume <SESSION_ID>` | continue a session (context preserved) |
+| `--best-of-n <N>` | run task N ways in parallel, pick best (headless) |
+
+## Permission model — the #1 pitfall
+
+`--permission-mode acceptEdits` **does not reliably unblock file writes in headless runs**; grok may report "Write tool blocked" and quietly degrade to a **design-only** response that reads like progress. It still exits 0.
+
+Mitigations:
+- Add explicit allow rules for write tools on the first dispatch: `--allow "Write" --allow "Edit" --allow "StrReplace"` alongside `--allow "Bash(npm:*)" --allow "Bash(node:*)"`.
+- After ~30s, grep the output for `blocked`/`chặn` — catch degradation early.
+- If the run finished design-only: **resume the same session** with widened allows and an explicit apply instruction; grok picks up its own design and implements without re-exploring:
+
+```bash
+grok --resume <SESSION_ID> --no-plan \
+     --permission-mode acceptEdits \
+     --allow "Write" --allow "Edit" --allow "StrReplace" \
+     --allow "Bash(npm:*)" --allow "Bash(node:*)" \
+     --check -p "Continue: apply the designed changes, run tests, report results."
+```
+
+Even with allows granted, shell may still be policy-restricted (runs finish with "npm test BLOCKED — shell not pre-approved"). That's fine: **you run the Evidence commands yourself during verification** — do not loosen to `bypassPermissions` just to make the agent self-verify.
+
+## Worktree pitfalls
+
+- `--worktree=<name>` worktrees are **grok-managed**: they may not appear in the target repo's `git worktree list` and `grok worktree list` may still say "No worktrees found". **Do not trust either listing** — after the run, check `git status` in the main repo to find where changes actually landed. In practice (0.2.101, resumed sessions) grok can write **directly into the main working tree** despite the flag.
+- Consequence: always take a stash-backup snapshot before dispatch (`git stash push -u -m "backup: ..." && git stash apply -q`), and treat the main tree as potentially modified.
+
+## Session management
+
+```bash
+grok sessions list                      # ids + summaries
+grok --resume <SESSION_ID> [flags] -p "..."   # continue with same context
+grok export <SESSION_ID>                # transcript as Markdown
+```
+
+## Quirks
+
+- Grok reads the target repo's `CLAUDE.md` and obeys it (including tone rules) — repo constraints apply automatically, but so do repo-wide bans; account for that in the brief.
+- `--check` produces a self-verification section in the final report — useful signal, **not** a substitute for your independent verification.
+- Exit code 0 means the CLI ran, not that the task succeeded. Judge by diff + your own Evidence runs.