@cluesmith/codev 2.1.2 → 2.1.4

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

@@ -1,98 +1,96 @@
 ---
 name: consult
-description: AI consultation CLI quick reference. Use when running consult commands to check syntax for general queries, protocol reviews, and stats across Gemini, Codex, and Claude.
-disable-model-invocation: false
+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
 
-```bash
+```
 consult -m <model> [options]
 consult stats [options]
 ```
 
-The `-m` / `--model` flag is **always required** (except for stats).
+The `-m` / `--model` flag is **always required** except for `consult stats`.
 
 ## Models
 
-| Model | Alias | Speed | Approach |
-|-------|-------|-------|----------|
-| `gemini` | `pro` | ~120-150s | File access via --yolo, fast |
-| `codex` | `gpt` | ~200-250s | Shell command exploration, thorough |
-| `claude` | `opus` | ~60-120s | Agent SDK with tool use |
-
-## Modes
-
-### General Mode
-```bash
-consult -m gemini --prompt "What's the best way to structure auth?"
-consult -m codex --prompt-file review-checklist.md
-```
+| Flag value | Alias | Notes |
+|------------|-------|-------|
+| `gemini` | `pro` | Fast (~120-150s), file access via --yolo |
+| `codex` | `gpt` | Thorough (~200-250s), shell exploration |
+| `claude` | `opus` | Agent SDK with tool use (~60-120s) |
 
-### Protocol Mode
-```bash
-consult -m gemini --protocol spir --type spec       # Review a specification
-consult -m codex --protocol spir --type plan        # Review a plan
-consult -m claude --protocol spir --type impl       # Review implementation
-consult -m gemini --protocol spir --type pr         # Review a PR
-consult -m codex --protocol spir --type phase       # Phase-scoped review
-consult -m gemini --type integration                # Integration review
-```
+## All flags
 
-### Stats Mode
-```bash
-consult stats                     # 30-day summary
-consult stats --days 7 --json     # Last 7 days as JSON
 ```
-
-## Options
-
-```bash
--m, --model <model>         # Model to use (required except stats)
---prompt <text>              # Inline prompt (general mode)
---prompt-file <path>         # Prompt from file (general mode)
---protocol <name>            # Protocol: spir, bugfix, tick, maintain
--t, --type <type>            # Review type: spec, plan, impl, pr, phase, integration
---issue <number>             # Issue number (architect context)
+-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, tick, 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 with --protocol)
+## Review types (`--type`)
 
-| Type | Use Case |
-|------|----------|
-| `spec` | Review specification completeness |
-| `plan` | Review implementation plan |
+| Type | When to use |
+|------|-------------|
+| `spec` | Review a specification for completeness |
+| `plan` | Review an implementation plan |
 | `impl` | Review code implementation |
-| `pr` | Review pull request before merge |
-| `phase` | Phase-scoped review (builder only) |
-| `integration` | Architect's integration review |
-
-Protocol-specific prompts live in `codev/protocols/<protocol>/consult-types/`.
+| `pr` | Review a pull request before merge |
+| `phase` | Phase-scoped review (builder context only) |
+| `integration` | Architect's integration review of a PR |
 
-## Context Resolution
+## Usage patterns
 
-- **Builder context** (cwd in `.builders/`): auto-detects project from porch state
-- **Architect context** (cwd outside `.builders/`): requires `--issue <N>`
+**General query:**
+```bash
+consult -m gemini --prompt "What's the best way to structure auth?"
+consult -m codex --prompt-file review-checklist.md
+```
 
-## Parallel Consultation (3-Way / cmap)
+**Protocol review:**
+```bash
+consult -m gemini --type spec --issue 42
+consult -m codex --type plan --issue 42
+consult -m claude --type integration --issue 42
+```
 
-Run all three models in parallel for thorough reviews:
+**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 --protocol spir --type spec &
-consult -m codex --protocol spir --type spec &
-consult -m claude --protocol spir --type spec &
+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
 ```
 
-Or from Claude Code, use **cmap** pattern: three parallel background Bash calls.
+**Stats:**
+```bash
+consult stats                     # 30-day summary
+consult stats --days 7 --json     # Last 7 days as JSON
+consult stats --project 42        # Filter by project
+```
 
-## Common Mistakes
+## Rules
 
-- The `-m` flag is **required** — `consult --type spec` will fail without it
-- Cannot combine `--prompt` with `--type` (mode conflict)
-- Cannot use `--prompt` and `--prompt-file` together
-- `--protocol` requires `--type` — cannot use alone
-- General mode: `--prompt` text is passed directly, not as a positional arg
+- `-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/.claude/skills/generate-image/SKILL.md

@@ -1,56 +1,45 @@
 ---
 name: generate-image
-description: AI image generation CLI using Gemini. Use when generating images, checking syntax for resolution, aspect ratio, and reference image options.
-disable-model-invocation: false
+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 (gemini-3-pro-image-preview) to generate images from text prompts.
+Uses Google Gemini to generate images from text prompts.
 
 ## Synopsis
 
-```bash
+```
 codev generate-image "<prompt>" [options]
 ```
 
-## Options
+Note: this is a `codev` subcommand, not standalone.
 
-```bash
--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)
+## 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
+## Aspect ratios
 
 `1:1` | `16:9` | `9:16` | `3:4` | `4:3` | `3:2` | `2:3`
 
 ## Examples
 
 ```bash
-# Basic generation
 codev generate-image "A sunset over mountains"
-
-# High-res widescreen
 codev generate-image "A futuristic city" -r 4K -a 16:9 -o city.png
-
-# With reference images (style transfer)
 codev generate-image "Same style but with cats" --ref style.png --ref layout.png
-
-# Prompt from file
-codev generate-image prompt.txt -o result.png
+codev generate-image prompt.txt -o result.png    # Prompt from .txt file
 ```
 
-## Prerequisites
-
-Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable.
-Get a key at https://aistudio.google.com/apikey
-
-## Common Mistakes
+## Notes
 
-- Prompt must be **quoted** if it contains spaces
-- Prompt can also be a `.txt` file path (auto-detected by extension)
-- Reference images must exist on disk — max 14 images
-- Output defaults to `output.png` in current directory — use `-o` to change
+- 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

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

@@ -1,53 +1,60 @@
 ---
 name: porch
-description: Protocol orchestrator CLI quick reference. Use when running porch commands to check correct syntax for status, run, done, approve, next, and pending.
-disable-model-invocation: false
+description: Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, TICK, and BUGFIX protocols via a state machine. ALWAYS check this skill before running any `porch` command. Use when you need to check project status, approve gates, signal phase completion, or manage protocol state. Also use when a builder asks about gate approvals or phase transitions.
 ---
 
 # porch - Protocol Orchestrator
 
-## Synopsis
-
-```bash
-porch <command> [project-id]
-```
-
-Porch drives SPIR, TICK, and BUGFIX protocols via a state machine with phase transitions, gates, and multi-agent consultations.
+Porch manages the state machine behind development protocols. It tracks phases, gates, consultations, and transitions.
 
 ## Commands
 
-```bash
-porch status [id]          # Show project status (auto-detects in worktree)
-porch run [id]             # Run the protocol loop (strict mode)
-porch next [id]            # Get next tasks for a project
-porch done [id]            # Signal current phase work is complete
-porch approve <id> <gate>  # Approve a gate (human only)
-porch pending              # List all pending gates across projects
+```
+porch status [id]              Show current project state and phase
+porch run [id]                 Run the protocol loop (strict mode)
+porch next [id]                Get next tasks as JSON
+porch done [id]                Signal current phase is complete
+porch check [id]               Run checks for current phase
+porch gate [id]                Request human approval at a gate
+porch approve <id> <gate> --a-human-explicitly-approved-this
+porch rollback <id> <phase>    Rewind to an earlier phase
+porch init <protocol> <id> <name>   Initialize a new project
 ```
 
-## Gates
+Project ID auto-detects from worktree path when inside a builder worktree.
 
-Gates are human approval checkpoints. Builders STOP at gates and wait.
+## Gate approvals
+
+Gates are human-only approval checkpoints. The `--a-human-explicitly-approved-this` flag is **required** — it exists to prevent AI agents from auto-approving.
 
 | Gate | Protocol | When |
 |------|----------|------|
 | `spec-approval` | SPIR | After spec is written |
 | `plan-approval` | SPIR | After plan is written |
-| `pr` | SPIR, TICK | After PR is created |
+| `pr` | SPIR, TICK, AIR | After PR is created |
+
+```bash
+porch approve 42 spec-approval --a-human-explicitly-approved-this
+porch approve 42 plan-approval --a-human-explicitly-approved-this
+porch approve 42 pr --a-human-explicitly-approved-this
+```
+
+**ASPIR and BUGFIX have no spec/plan gates** — they run autonomously through those phases.
+
+## Checking pending gates
 
 ```bash
-porch approve 42 spec-approval    # Approve spec gate
-porch approve 42 plan-approval    # Approve plan gate
-porch approve 42 pr               # Approve PR gate
+porch pending                  # List all gates waiting for approval
 ```
 
-## Project State
+## Critical rules
 
-State is stored in `codev/projects/<id>/status.yaml`, managed automatically by porch. **Never edit status.yaml directly.**
+- **Builders must NEVER call `porch approve`** — only humans approve gates
+- **Never edit `status.yaml` directly** — porch manages all state
+- Builders signal completion with `porch done`, not `porch approve`
+- `porch run` is for strict mode only — soft mode builders follow the protocol document manually
+- When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`
 
-## Common Mistakes
+## State storage
 
-- **Never call `porch approve` as a builder** - Only humans approve gates
-- **Never edit status.yaml directly** - Only porch modifies state
-- Builders should use `porch done` to signal phase completion, not `porch approve`
-- `porch run` is for strict mode only - soft mode builders follow the protocol manually
+Project state lives in `codev/projects/<id>-<name>/status.yaml`, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.

package/templates/tower.html

@@ -1026,6 +1026,17 @@
         }
       }
 
+      // Abort SSE connection on page unload to free connection slots.
+      // fetch+ReadableStream SSE doesn't auto-close like EventSource,
+      // so without this, reloads leak connections until Chrome's 6-per-origin
+      // limit is exhausted and all subsequent fetches queue forever.
+      window.addEventListener('beforeunload', () => {
+        if (sseController) {
+          sseController.abort();
+          sseController = null;
+        }
+      });
+
       // Subscribe to SSE for push notifications
       subscribeToEvents();