@cluesmith/codev 3.2.2 → 3.2.4

package/skeleton/.claude/skills/afx/SKILL.md

@@ -99,6 +99,19 @@ afx status                      # Show all builders and workspace status
 
 No flags needed. Shows Tower status, workspace, and all active builders.
 
+## afx whoami
+
+```bash
+afx whoami                      # Report this terminal's identity (workspace, type, name)
+afx whoami --json               # Same, as a single JSON object
+```
+
+Resolves identity from Tower/global.db's perspective: builder-worktree cwd
+match first, then the Tower-injected `CODEV_ARCHITECT_NAME` env var. Exits 1
+with an explanation when identity cannot be determined — it never guesses and
+never defaults to `main` (issue #1094). Builders also get an `architect:`
+field naming their spawning architect when recorded. Works without Tower.
+
 ## afx tower
 
 ```bash

package/skeleton/.claude/skills/arch-init/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: arch-init
+description: Adopt an architect identity and recover its state from codev/state/<name>.md. Use when an architect terminal needs to (re)establish which architect it is — after a restart, context loss, or session handoff — or when the user says "/arch-init", "you are the X architect", or "recover your architect state". Identity resolves via `afx whoami` (an explicit name argument overrides); if neither resolves, ask the human — never guess.
+argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
+---
+
+# /arch-init — become architect `<name>` and recover state
+
+You are an **architect agent** in a codev workspace. This command tells you
+which architect you are and where your durable state lives, so you can resume
+mid-stream.
+
+`$ARGUMENTS` is the architect name (e.g. `main`, or a sibling architect's
+name in a multi-architect workspace).
+
+## What to do
+
+1. **Resolve your name.**
+   - If `$ARGUMENTS` is non-empty, that is your name — the human named you
+     explicitly, which removes all identity-resolution risk. **Validate it
+     first**: an architect name must match `[a-z][a-z0-9-]*` and be at most
+     64 characters (lowercase letters, digits, hyphens; starts with a
+     letter). Reject anything else — slashes, `..`, uppercase, spaces — and
+     tell the human the rule. Never build a file path from an unvalidated
+     name (path-traversal guard).
+   - If `$ARGUMENTS` is empty, run `afx whoami` and read its output:
+     - `type: architect` → adopt the reported `name`.
+     - `type: builder` → STOP. This terminal is a builder, not an architect;
+       report the mismatch to the human and do not adopt an architect
+       identity.
+     - Non-zero exit (identity unknown) → STOP and ask the human which
+       architect you are. Do NOT guess, and do NOT default to `main` —
+       adopting the wrong identity and writing to another architect's state
+       file is the exact failure this command exists to prevent.
+
+2. **Read your state file: `codev/state/<name>.md`** (relative to the
+   workspace root).
+   - If it does not exist: list the architect state files in `codev/state/`
+     — **excluding `*_thread.md` files**, which are builder thread logs that
+     share the directory — tell the human the file is missing, and ask
+     whether to start a fresh state file for `<name>`. Do not fabricate
+     state.
+   - The state file is authoritative free text. It typically opens with a
+     role banner and may carry resume instructions; follow whatever it says.
+   - Architect state files are per-person and gitignored
+     (`codev/state/*.md`); never commit them. Builder `*_thread.md` files
+     are the opposite: versioned, shipping with each builder PR.
+
+3. **Confirm identity + orient, then follow the state file.** In one tight
+   block, report: who you now are (name + one-line role from the banner, if
+   present), the file you read, and the current-state / open-loops summary
+   from the most recent dated section (or the file's leading content if it
+   has no dated sections). Then carry out whatever the state file says to do
+   on resume. Do not invent a new agenda — resume the one the state file
+   describes.
+
+## Saving your state (and knowing when to `/clear`)
+
+Recovery is only half the loop. `/arch-init` reads state; **you** write it. The
+state file is not crash insurance — it is your deliberate memory-management
+mechanism. Auto-compaction happens at an arbitrary moment with content you did
+not choose; a state save happens at a boundary **you** pick, with a summary
+**you** curate. That is strictly better, so use it:
+
+```
+/arch-init (recover) → work → save at a checkpoint → suggest /clear → human /clears → /arch-init → …
+```
+
+**When to save.** Save at a *resumable boundary* — a point a fresh session
+could pick up cleanly from. Good moments, judged by you: a gate approval, a PR
+merge, a completed investigation, the end of a long tool-heavy stretch.
+**Never save mid-task.** The state file must describe a point you can resume
+*from*, not a half-finished action; a mid-task snapshot resumes into confusion.
+
+**How to save (write format = read format).** Recovery reads *the role banner
+plus the most recent dated section*, so a save must leave exactly that behind:
+
+1. **Rewrite the current-state / open-loops section in place** — overwrite it
+   with where things actually stand now (current focus + open loops + how to
+   resume). Do not accumulate stale "current state" blocks, and never leave two
+   sections with the same heading (a duplicated "How to resume" or "Open loops"
+   means you appended where you should have overwritten). **Delete resolved
+   loops entirely** — a closed item's record is the log entry, not a lingering
+   line in current state.
+2. **Append one short dated log entry** capturing what changed this stretch.
+3. **Compact — this is part of the save, not optional polish.** Every save
+   both adds AND removes: after writing, keep the recent dated log entries in
+   full and collapse older ones into a single one-line summary that names
+   where the detail lives (the closed PRs, issues, and reviews it covered).
+   Remember these state files are gitignored — there is no git history to
+   fall back on, so pruned prose is gone for good. Prune by replacing detail
+   with pointers to durable artifacts, never by deleting the only record of
+   something. The file is a summary a fresh session reads at a glance —
+   one screen is the right order of magnitude, judged by you. If a save has
+   grown it past easy readability, prune as part of that save rather than
+   leaving it for next time.
+
+**Content guardrails.** No secrets (tokens, keys, credentials). No transcript
+dumps or raw tool output. Include only: current focus, open loops, and the
+instructions a fresh session needs to resume.
+
+**Then — and only then — suggest `/clear`.** Save first, *then* tell the human
+it is a good time to clear. You cannot clear your own context and must never
+decide unilaterally to lose it; keeping the irreversible step behind a human
+keystroke means accepting the suggestion can never lose anything, because the
+save already happened. Make the suggestion **advisory, never nagging**, and
+only right after a save — e.g.:
+
+> State saved to `codev/state/<name>.md` — good time to `/clear` if this
+> session is feeling heavy.
+
+Do not repeat it, and do not prompt to `/clear` at any other time.
+
+## Guardrails (architect-wide; the state file may add more)
+
+- **Never auto-approve porch gates.** A gate notification is for the human,
+  not you.
+- **Touch only your own builders / spawns / filings.** Sibling architects own
+  theirs.
+- **Never `cd` into a builder worktree**; use `git -C` + absolute paths.
+- **Stay on the default branch at the workspace root**; verify with
+  `git branch` if unsure.

package/skeleton/.claude/skills/codev/SKILL.md

@@ -16,7 +16,7 @@ codev doctor                   Check system dependencies
 
 ## codev init
 
-Creates a **new directory** with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, .claude/skills/, .codev/config.json, .gitignore.
+Creates a **new directory** with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, `.claude/skills/`, `.codex/skills/`, .codev/config.json, and .gitignore.
 
 ```bash
 codev init my-app              # Interactive setup
@@ -34,7 +34,7 @@ codev adopt -y                 # Skip conflict prompts
 
 ## codev update
 
-Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). Creates `.codev-new` versions for customized files.
+Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). Creates `.codev-new` versions for customized files. Missing Claude and Codex skills are added, while existing skill directories are preserved.
 
 ```bash
 codev update                   # Interactive update

package/skeleton/.codex/skills/afx/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: afx
+description: Agent Farm CLI — the tool for spawning builders, managing Tower, workspaces, and cron tasks. ALWAYS consult this skill BEFORE running any `afx` command to get the exact syntax. This prevents wasting time guessing flags that don't exist. Use this whenever you need to spawn a builder, check status, send messages, clean up worktrees, manage Tower, or run cron tasks. If you're about to type `afx` followed by anything, check here first.
+---
+
+# Agent Farm CLI
+
+## afx spawn
+
+Spawns a new builder in an isolated git worktree.
+
+```
+afx spawn [number] [options]
+```
+
+**The ONLY flags that exist:**
+
+| Flag | Description |
+|------|-------------|
+| `--protocol <name>` | Protocol: spir, aspir, air, bugfix, maintain, experiment. **Required for numbered spawns.** |
+| `--task <text>` | Ad-hoc task (no issue number needed) |
+| `--shell` | Bare Claude session |
+| `--worktree` | Bare worktree session |
+| `--files <files>` | Context files, comma-separated. **Requires `--task`.** |
+| `--no-comment` | Skip commenting on the GitHub issue |
+| `--force` | Skip dirty-worktree and collision checks |
+| `--soft` | Soft mode (AI follows protocol, you verify) |
+| `--strict` | Strict mode (porch orchestrates) — this is the default |
+| `--resume` | Resume builder in existing worktree |
+| `--no-role` | Skip loading role prompt |
+
+**There is NO `-t`, `--title`, `--name`, or `--branch` flag.** The branch name is auto-generated from the issue title.
+
+**Examples:**
+```bash
+afx spawn 42 --protocol spir           # SPIR builder for issue #42
+afx spawn 42 --protocol aspir          # ASPIR (autonomous, no human gates)
+afx spawn 42 --protocol air            # AIR (small features)
+afx spawn 42 --protocol bugfix         # Bugfix
+afx spawn 42 --protocol spir --soft    # Soft mode
+afx spawn 42 --resume                  # Resume existing builder
+afx spawn --task "fix the flaky test"  # Ad-hoc task (no issue)
+afx spawn 42 --protocol spir --force   # Skip dirty-worktree check
+```
+
+**Pre-spawn checklist:**
+1. `git status` — worktree must be clean (or use `--force`)
+2. Commit specs/plans first — builders branch from HEAD and can't see uncommitted files
+3. `--protocol` is required for numbered spawns
+
+## afx send
+
+Sends a message to a running builder.
+
+```
+afx send [builder] [message]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Send to all builders |
+| `--file <path>` | Include file content |
+| `--interrupt` | Send Ctrl+C first |
+| `--raw` | Skip structured formatting |
+| `--no-enter` | Don't press Enter after message |
+
+```bash
+afx send 0042 "PR approved, please merge"
+afx send 0585 "check the test output" --file /tmp/test-results.txt
+```
+
+## afx cleanup
+
+Removes a builder's worktree and branch after work is done.
+
+```
+afx cleanup [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --project <id>` | Builder project ID (no leading zeros: `585` not `0585`) |
+| `-i, --issue <number>` | Cleanup bugfix builder by issue number |
+| `-t, --task <id>` | Cleanup task builder (e.g., `task-bEPd`) |
+| `-f, --force` | Force cleanup even if branch not merged |
+
+```bash
+afx cleanup -p 585              # Clean up project 585
+afx cleanup -p 585 -f           # Force (unmerged branch)
+```
+
+**Note:** `afx cleanup` uses plain numbers (`585`), not zero-padded (`0585`). But `afx send` uses zero-padded IDs (`0585`).
+
+## afx status
+
+```bash
+afx status                      # Show all builders and workspace status
+```
+
+No flags needed. Shows Tower status, workspace, and all active builders.
+
+## afx whoami
+
+```bash
+afx whoami                      # Report this terminal's identity (workspace, type, name)
+afx whoami --json               # Same, as a single JSON object
+```
+
+Resolves identity from Tower/global.db's perspective: builder-worktree cwd
+match first, then the Tower-injected `CODEV_ARCHITECT_NAME` env var. Exits 1
+with an explanation when identity cannot be determined — it never guesses and
+never defaults to `main` (issue #1094). Builders also get an `architect:`
+field naming their spawning architect when recorded. Works without Tower.
+
+## afx tower
+
+```bash
+afx tower start                 # Start Tower on port 4100
+afx tower stop                  # Stop Tower
+afx tower log                   # Tail Tower logs
+afx tower status                # Check daemon and cloud connection status
+afx tower connect               # Connect to Codev Cloud
+afx tower disconnect            # Disconnect from Codev Cloud
+```
+
+There is NO `afx tower restart` — use `afx tower stop && afx tower start`.
+
+## afx workspace
+
+```bash
+afx workspace start             # Start workspace for current project
+afx workspace stop              # Stop workspace processes
+```
+
+`afx dash` is a deprecated alias — use `afx workspace` instead.
+
+## afx cron
+
+```bash
+afx cron list                   # List all cron tasks
+afx cron status <name>          # Check task status
+afx cron run <name>             # Run immediately
+afx cron enable <name>          # Enable
+afx cron disable <name>         # Disable
+```
+
+There is NO `afx cron add` — create YAML files in `.af-cron/` directly.
+
+## Other commands
+
+```bash
+afx open <file>                 # Open file in annotation viewer (NOT system open)
+afx shell                       # Spawn utility shell
+afx attach                      # Attach to running builder terminal
+afx rename <name>               # Rename current shell session
+afx architect                   # Start architect session in current terminal
+```

package/skeleton/.codex/skills/arch-init/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: arch-init
+description: Adopt an architect identity and recover its state from codev/state/<name>.md. Use when an architect terminal needs to (re)establish which architect it is — after a restart, context loss, or session handoff — or when the user says "/arch-init", "you are the X architect", or "recover your architect state". Identity resolves via `afx whoami` (an explicit name argument overrides); if neither resolves, ask the human — never guess.
+argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
+---
+
+# /arch-init — become architect `<name>` and recover state
+
+You are an **architect agent** in a codev workspace. This command tells you
+which architect you are and where your durable state lives, so you can resume
+mid-stream.
+
+`$ARGUMENTS` is the architect name (e.g. `main`, or a sibling architect's
+name in a multi-architect workspace).
+
+## What to do
+
+1. **Resolve your name.**
+   - If `$ARGUMENTS` is non-empty, that is your name — the human named you
+     explicitly, which removes all identity-resolution risk. **Validate it
+     first**: an architect name must match `[a-z][a-z0-9-]*` and be at most
+     64 characters (lowercase letters, digits, hyphens; starts with a
+     letter). Reject anything else — slashes, `..`, uppercase, spaces — and
+     tell the human the rule. Never build a file path from an unvalidated
+     name (path-traversal guard).
+   - If `$ARGUMENTS` is empty, run `afx whoami` and read its output:
+     - `type: architect` → adopt the reported `name`.
+     - `type: builder` → STOP. This terminal is a builder, not an architect;
+       report the mismatch to the human and do not adopt an architect
+       identity.
+     - Non-zero exit (identity unknown) → STOP and ask the human which
+       architect you are. Do NOT guess, and do NOT default to `main` —
+       adopting the wrong identity and writing to another architect's state
+       file is the exact failure this command exists to prevent.
+
+2. **Read your state file: `codev/state/<name>.md`** (relative to the
+   workspace root).
+   - If it does not exist: list the architect state files in `codev/state/`
+     — **excluding `*_thread.md` files**, which are builder thread logs that
+     share the directory — tell the human the file is missing, and ask
+     whether to start a fresh state file for `<name>`. Do not fabricate
+     state.
+   - The state file is authoritative free text. It typically opens with a
+     role banner and may carry resume instructions; follow whatever it says.
+   - Architect state files are per-person and gitignored
+     (`codev/state/*.md`); never commit them. Builder `*_thread.md` files
+     are the opposite: versioned, shipping with each builder PR.
+
+3. **Confirm identity + orient, then follow the state file.** In one tight
+   block, report: who you now are (name + one-line role from the banner, if
+   present), the file you read, and the current-state / open-loops summary
+   from the most recent dated section (or the file's leading content if it
+   has no dated sections). Then carry out whatever the state file says to do
+   on resume. Do not invent a new agenda — resume the one the state file
+   describes.
+
+## Saving your state (and knowing when to `/clear`)
+
+Recovery is only half the loop. `/arch-init` reads state; **you** write it. The
+state file is not crash insurance — it is your deliberate memory-management
+mechanism. Auto-compaction happens at an arbitrary moment with content you did
+not choose; a state save happens at a boundary **you** pick, with a summary
+**you** curate. That is strictly better, so use it:
+
+```
+/arch-init (recover) → work → save at a checkpoint → suggest /clear → human /clears → /arch-init → …
+```
+
+**When to save.** Save at a *resumable boundary* — a point a fresh session
+could pick up cleanly from. Good moments, judged by you: a gate approval, a PR
+merge, a completed investigation, the end of a long tool-heavy stretch.
+**Never save mid-task.** The state file must describe a point you can resume
+*from*, not a half-finished action; a mid-task snapshot resumes into confusion.
+
+**How to save (write format = read format).** Recovery reads *the role banner
+plus the most recent dated section*, so a save must leave exactly that behind:
+
+1. **Rewrite the current-state / open-loops section in place** — overwrite it
+   with where things actually stand now (current focus + open loops + how to
+   resume). Do not accumulate stale "current state" blocks, and never leave two
+   sections with the same heading (a duplicated "How to resume" or "Open loops"
+   means you appended where you should have overwritten). **Delete resolved
+   loops entirely** — a closed item's record is the log entry, not a lingering
+   line in current state.
+2. **Append one short dated log entry** capturing what changed this stretch.
+3. **Compact — this is part of the save, not optional polish.** Every save
+   both adds AND removes: after writing, keep the recent dated log entries in
+   full and collapse older ones into a single one-line summary that names
+   where the detail lives (the closed PRs, issues, and reviews it covered).
+   Remember these state files are gitignored — there is no git history to
+   fall back on, so pruned prose is gone for good. Prune by replacing detail
+   with pointers to durable artifacts, never by deleting the only record of
+   something. The file is a summary a fresh session reads at a glance —
+   one screen is the right order of magnitude, judged by you. If a save has
+   grown it past easy readability, prune as part of that save rather than
+   leaving it for next time.
+
+**Content guardrails.** No secrets (tokens, keys, credentials). No transcript
+dumps or raw tool output. Include only: current focus, open loops, and the
+instructions a fresh session needs to resume.
+
+**Then — and only then — suggest `/clear`.** Save first, *then* tell the human
+it is a good time to clear. You cannot clear your own context and must never
+decide unilaterally to lose it; keeping the irreversible step behind a human
+keystroke means accepting the suggestion can never lose anything, because the
+save already happened. Make the suggestion **advisory, never nagging**, and
+only right after a save — e.g.:
+
+> State saved to `codev/state/<name>.md` — good time to `/clear` if this
+> session is feeling heavy.
+
+Do not repeat it, and do not prompt to `/clear` at any other time.
+
+## Guardrails (architect-wide; the state file may add more)
+
+- **Never auto-approve porch gates.** A gate notification is for the human,
+  not you.
+- **Touch only your own builders / spawns / filings.** Sibling architects own
+  theirs.
+- **Never `cd` into a builder worktree**; use `git -C` + absolute paths.
+- **Stay on the default branch at the workspace root**; verify with
+  `git branch` if unsure.

package/skeleton/.codex/skills/codev/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: codev
+description: Codev project management CLI — init, adopt, update, and doctor commands. Check this skill before running any `codev` command (except `consult`, `porch`, or `afx` which have their own skills). Use when setting up new projects, adding codev to existing repos, updating framework files, or diagnosing missing dependencies.
+---
+
+# codev - Project Management CLI
+
+## Commands
+
+```
+codev init [project-name]      Create a new codev project directory
+codev adopt                    Add codev to the current directory
+codev update                   Update protocols, roles, skills from package
+codev doctor                   Check system dependencies
+```
+
+## codev init
+
+Creates a **new directory** with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, `.claude/skills/`, `.codex/skills/`, .codev/config.json, and .gitignore.
+
+```bash
+codev init my-app              # Interactive setup
+codev init my-app -y           # Non-interactive with defaults
+```
+
+## codev adopt
+
+Adds codev to the **current directory** (existing project). Run from the project root. If CLAUDE.md or AGENTS.md already exists, creates `.codev-new` versions and spawns Claude to merge.
+
+```bash
+codev adopt                    # Interactive
+codev adopt -y                 # Skip conflict prompts
+```
+
+## codev update
+
+Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). Creates `.codev-new` versions for customized files. Missing Claude and Codex skills are added, while existing skill directories are preserved.
+
+```bash
+codev update                   # Interactive update
+codev update --dry-run         # Preview changes
+codev update --force           # Overwrite all framework files
+codev update --agent           # Agent mode: JSON stdout, no interactive merge
+```
+
+## codev doctor
+
+Checks all required dependencies: Node.js (>=18), git (>=2.5), gh (authenticated), and at least one AI CLI (Claude, Gemini, or Codex).
+
+```bash
+codev doctor
+```
+
+## Common mistakes
+
+- There is NO `codev tower` command — use `afx tower start/stop`
+- `codev init` creates a new directory — use `codev adopt` for existing projects
+- Always run `codev adopt` and `codev update` from the project root
+- `codev update` only updates framework files — it never touches specs/plans/reviews

package/skeleton/.codex/skills/consult/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: consult
+description: AI consultation CLI — query Gemini, Codex, or Claude for reviews and analysis. ALWAYS check this skill before running any `consult` command. Use when reviewing specs, plans, implementations, or PRs with external models, running parallel 3-way reviews (cmap), or checking consultation stats. The `-m` model flag is always required except for `consult stats`.
+---
+
+# consult - AI Consultation CLI
+
+Query external AI models for reviews and analysis. Supports Gemini, Codex, and Claude.
+
+## Synopsis
+
+```
+consult -m <model> [options]
+consult stats [options]
+```
+
+The `-m` / `--model` flag is **always required** except for `consult stats`.
+
+## Models
+
+| Flag value | Alias | Notes |
+|------------|-------|-------|
+| `gemini` | `pro` | Antigravity CLI (`agy`); agentic file access (`--sandbox`), OAuth login; skips non-blockingly if unavailable |
+| `codex` | `gpt` | Thorough (~200-250s), shell exploration |
+| `claude` | `opus` | Agent SDK with tool use (~60-120s) |
+
+## All flags
+
+```
+-m, --model <model>         Model to use (required except stats)
+--prompt <text>              Inline prompt (general mode)
+--prompt-file <path>         Prompt file path (general mode)
+--protocol <name>            Protocol: spir, aspir, air, bugfix, maintain
+-t, --type <type>            Review type (see below)
+--issue <number>             Issue number (required in architect context)
+--output <path>              Save result to file
+--plan-phase <phase>         Scope review to a plan phase (porch use)
+--context <path>             Context file with feedback (porch use)
+--project-id <id>            Project ID for metrics (porch use)
+--days <n>                   Stats: limit to last N days (default: 30)
+--project <id>               Stats: filter by project ID
+--last <n>                   Stats: show last N invocations
+--json                       Stats: output as JSON
+```
+
+## Review types (`--type`)
+
+| Type | When to use |
+|------|-------------|
+| `spec` | Review a specification for completeness |
+| `plan` | Review an implementation plan |
+| `impl` | Review code implementation |
+| `pr` | Review a pull request before merge |
+| `phase` | Phase-scoped review (builder context only) |
+| `integration` | Architect's integration review of a PR |
+
+## Usage patterns
+
+**General query:**
+```bash
+consult -m gemini --prompt "What's the best way to structure auth?"
+consult -m codex --prompt-file review-checklist.md
+```
+
+**Protocol review:**
+```bash
+consult -m gemini --type spec --issue 42
+consult -m codex --type plan --issue 42
+consult -m claude --type integration --issue 42
+```
+
+**3-way parallel review (cmap):**
+Always use `--output` for background runs — without it, results go to a temp file that may be garbage-collected.
+
+```bash
+consult -m gemini --type integration --issue 42 --output /tmp/cmap-gemini-42.md &
+consult -m codex --type integration --issue 42 --output /tmp/cmap-codex-42.md &
+consult -m claude --type integration --issue 42 --output /tmp/cmap-claude-42.md &
+wait
+```
+
+**Stats:**
+```bash
+consult stats                     # 30-day summary
+consult stats --days 7 --json     # Last 7 days as JSON
+consult stats --project 42        # Filter by project
+```
+
+## Rules
+
+- `-m` is required for all non-stats commands
+- `--prompt` and `--type` are mutually exclusive (different modes)
+- `--prompt` and `--prompt-file` are mutually exclusive
+- `--protocol` requires `--type`
+- From architect context (outside `.builders/`), `--issue` is required for protocol reviews
+- From builder context (inside `.builders/`), project auto-detects from porch state

package/skeleton/.codex/skills/generate-image/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: generate-image
+description: AI image generation via Gemini. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY.
+---
+
+# generate-image - AI Image Generation
+
+Uses Google Gemini to generate images from text prompts.
+
+## Synopsis
+
+```
+codev generate-image "<prompt>" [options]
+```
+
+Note: this is a `codev` subcommand, not standalone.
+
+## All flags
+
+```
+-o, --output <file>        Output file path (default: output.png)
+-r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
+-a, --aspect <ratio>       Aspect ratio (default: 1:1)
+--ref <image>              Reference image (repeatable, max 14)
+```
+
+## Aspect ratios
+
+`1:1` | `16:9` | `9:16` | `3:4` | `4:3` | `3:2` | `2:3`
+
+## Examples
+
+```bash
+codev generate-image "A sunset over mountains"
+codev generate-image "A futuristic city" -r 4K -a 16:9 -o city.png
+codev generate-image "Same style but with cats" --ref style.png --ref layout.png
+codev generate-image prompt.txt -o result.png    # Prompt from .txt file
+```
+
+## Notes
+
+- Prompt must be quoted if it contains spaces
+- Prompt can be a `.txt` file path (auto-detected by extension)
+- Reference images must exist on disk
+- Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable