@cluesmith/codev 2.0.0-rc.59 → 2.0.0-rc.60

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

@@ -0,0 +1,74 @@
+---
+name: af
+description: Agent Farm CLI quick reference. Use when running af commands to check correct syntax, subcommands, and flags. Prevents guessing at command names.
+disable-model-invocation: false
+---
+
+# Agent Farm Quick Reference
+
+## Tower (Dashboard Server)
+
+```bash
+af tower start             # Start Tower on port 4100
+af tower stop              # Stop Tower
+af tower log               # Tail Tower logs
+af tower status            # Check if Tower is running
+```
+
+There is NO `af tower restart` — use `af tower stop && af tower start`.
+
+## Dashboard
+
+```bash
+af dash start              # Start architect dashboard for current project
+af dash stop               # Stop dashboard for current project
+af dash open               # Open dashboard in browser
+```
+
+## Builder Management
+
+```bash
+af spawn -p 0003           # Spawn builder for spec (strict mode, default)
+af spawn --soft -p 0003    # Spawn builder (soft mode)
+af spawn --issue 42        # Spawn builder for a bugfix
+af status                  # Check all builder status
+af cleanup --project 0003  # Clean up builder worktree (safe)
+af cleanup --project 0003 -f  # Force cleanup
+```
+
+## Utility
+
+```bash
+af util                    # Open utility shell
+af open file.ts            # Open file in annotation viewer
+af ports list              # List port allocations
+af send <builder> "msg"    # Send message to a builder
+```
+
+## Configuration
+
+Edit `af-config.json` at project root to customize shell commands.
+
+```json
+{
+  "shell": {
+    "architect": "claude",
+    "builder": "claude",
+    "shell": "bash"
+  }
+}
+```
+
+## Pre-Spawn Checklist
+
+**Before `af spawn`, commit all local changes.** Builders work in git worktrees
+branched from HEAD — uncommitted files (specs, plans, codev updates) are invisible
+to the builder. The spawn command will refuse if the worktree is dirty (override
+with `--force`).
+
+## Common Mistakes
+
+- **Spawning with uncommitted changes** — builder won't see specs, plans, or codev updates
+- There is NO `codev tower` command — Tower is managed via `af tower`
+- There is NO `restart` subcommand — stop then start
+- There is NO `af start` for Tower — use `af tower start` or `af dash start`

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

@@ -0,0 +1,41 @@
+---
+name: codev
+description: Codev project management CLI quick reference. Use when running codev commands to check correct syntax for init, adopt, update, and doctor.
+disable-model-invocation: false
+---
+
+# codev - Project Management CLI
+
+## Commands
+
+```bash
+codev init [name]          # Create a new codev project
+codev init my-app -y       # Non-interactive with defaults
+codev adopt                # Add codev to existing project (run from project root)
+codev adopt -y             # Skip conflict prompts
+codev update               # Update protocols, roles, skills from installed package
+codev update --dry-run     # Preview changes without applying
+codev update --force       # Force overwrite all framework files
+codev doctor               # Check system dependencies
+```
+
+## What Each Command Does
+
+### codev init
+Creates a new project directory with codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, .claude/skills/, af-config.json, .gitignore.
+
+### codev adopt
+Adds codev to the **current directory**. Detects existing CLAUDE.md/AGENTS.md and creates `.codev-new` versions for merge if conflicts exist. Spawns Claude to merge automatically.
+
+### codev update
+Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). If you've customized a framework file, creates a `.codev-new` version for manual merge.
+
+### codev doctor
+Checks that all required dependencies are installed: Node.js (>=18), tmux (>=3), git (>=2.5), gh (authenticated), and at least one AI CLI (Claude, Gemini, or Codex).
+
+## Common Mistakes
+
+- There is NO `codev tower` command — Tower is managed via `af tower start` / `af tower stop`
+- `codev init` creates a **new directory** — use `codev adopt` for existing projects
+- `codev update` only updates framework files — it will never overwrite your specs/plans/reviews
+- Always run `codev adopt` and `codev update` from the **project root directory**

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

@@ -0,0 +1,81 @@
+---
+name: consult
+description: AI consultation CLI quick reference. Use when running consult commands to check syntax for PR reviews, spec reviews, plan reviews, and general queries across Gemini, Codex, and Claude.
+disable-model-invocation: false
+---
+
+# consult - AI Consultation CLI
+
+## Synopsis
+
+```bash
+consult -m <model> <subcommand> [args] [options]
+```
+
+The `-m` / `--model` flag is **always required**.
+
+## Models
+
+| Model | Alias | Speed | Approach |
+|-------|-------|-------|----------|
+| `gemini` | `pro` | ~120-150s | Pure text analysis, fast |
+| `codex` | `gpt` | ~200-250s | Shell command exploration, thorough |
+| `claude` | `opus` | ~60-120s | Balanced tool use |
+
+## Subcommands
+
+```bash
+consult -m gemini pr 42              # Review a pull request
+consult -m codex spec 42             # Review a specification
+consult -m gemini plan 42            # Review an implementation plan
+consult -m claude general "query"    # General question (quoted string)
+```
+
+## Options
+
+```bash
+-n, --dry-run              # Show command without running
+-t, --type <type>          # Review type (spec-review, plan-review, impl-review, pr-ready, integration-review)
+-r, --role <role>          # Custom role from codev/roles/ (without .md extension)
+```
+
+## Review Types (--type)
+
+| Type | Stage | Use Case |
+|------|-------|----------|
+| `spec-review` | conceived | Review spec completeness |
+| `plan-review` | specified | Review implementation plan |
+| `impl-review` | implementing | Review code implementation |
+| `pr-ready` | implemented | Final check before PR |
+| `integration-review` | committed | Architect's integration review |
+
+Review type prompts live in `codev/consult-types/` and can be customized.
+
+## Parallel Consultation (3-Way / cmap)
+
+Run all three models in parallel for thorough reviews:
+
+```bash
+consult -m gemini spec 42 &
+consult -m codex spec 42 &
+consult -m claude spec 42 &
+wait
+```
+
+Or from Claude Code, use **cmap** pattern: three parallel background Bash calls.
+
+## Custom Roles
+
+```bash
+consult -m gemini --role security-reviewer pr 42
+consult -m codex --role architect general "Review this design"
+```
+
+Roles are markdown files in `codev/roles/`. Create your own by adding `.md` files there.
+
+## Common Mistakes
+
+- The `-m` flag is **required** — `consult pr 42` will fail without it
+- PR numbers are GitHub PR numbers, not spec numbers
+- Spec/plan numbers match the `0042` prefix in filenames (pass just `42`, not `0042`)
+- General queries must be **quoted**: `consult -m gemini general "your question here"`

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

@@ -0,0 +1,56 @@
+---
+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
+---
+
+# generate-image - AI Image Generation
+
+Uses Google Gemini (gemini-3-pro-image-preview) to generate images from text prompts.
+
+## Synopsis
+
+```bash
+codev generate-image "<prompt>" [options]
+```
+
+## Options
+
+```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)
+```
+
+## 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
+```
+
+## Prerequisites
+
+Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable.
+Get a key at https://aistudio.google.com/apikey
+
+## Common Mistakes
+
+- 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

package/skeleton/protocols/bugfix/builder-prompt.md

@@ -17,6 +17,11 @@ You are running in STRICT mode. This means:
 - Porch orchestrates your work
 - Run: `porch run {{project_id}}`
 - Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
 {{/if}}
 
 ## Protocol

package/skeleton/protocols/experiment/builder-prompt.md

@@ -16,6 +16,11 @@ You are running in STRICT mode. This means:
 - Porch orchestrates your work
 - Run: `porch run {{project_id}}`
 - Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
 {{/if}}
 
 ## Protocol

package/skeleton/protocols/maintain/builder-prompt.md

@@ -16,6 +16,11 @@ You are running in STRICT mode. This means:
 - Porch orchestrates your work
 - Run: `porch run {{project_id}}`
 - Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
 {{/if}}
 
 ## Protocol

package/skeleton/protocols/spir/builder-prompt.md

@@ -18,6 +18,12 @@ You are running in STRICT mode. This means:
 - Run: `porch run {{project_id}}`
 - Follow porch signals and gate approvals
 - Do not deviate from the porch-driven workflow
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
+- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval
 {{/if}}
 
 ## Protocol

package/skeleton/protocols/spir/protocol.md

@@ -8,6 +8,12 @@
 
 ## Prerequisites
 
+**Clean Worktree Before Spawning Builders**:
+- All specs, plans, and local changes **MUST be committed** before `af spawn`
+- Builders work in git worktrees branched from HEAD — uncommitted files are invisible
+- This includes `codev update` results, spec drafts, and plan approvals
+- The `af spawn` command enforces this (use `--force` to override)
+
 **Required for Multi-Agent Consultation**:
 - The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`)
 - At least one consultation backend: `claude`, `gemini-cli`, or `codex`

package/skeleton/protocols/tick/builder-prompt.md

@@ -17,6 +17,11 @@ You are running in STRICT mode. This means:
 - Porch orchestrates your work
 - Run: `porch run {{project_id}}`
 - Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
 {{/if}}
 
 ## Protocol