@cluesmith/codev 2.0.0-rc.6 → 2.0.0-rc.61

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/DEPENDENCIES.md

@@ -57,29 +57,6 @@ sudo apt install tmux
 tmux -V  # Should show tmux 3.x or higher
 ```
 
-### ttyd
-
-| Requirement | Value |
-|-------------|-------|
-| Minimum Version | 1.7.0 |
-| Purpose | Web-based terminal for dashboard access |
-
-**Installation:**
-
-```bash
-# macOS
-brew install ttyd
-
-# Ubuntu/Debian (build from source)
-sudo apt install build-essential cmake git libjson-c-dev libwebsockets-dev
-git clone https://github.com/tsl0922/ttyd.git
-cd ttyd && mkdir build && cd build
-cmake .. && make && sudo make install
-
-# Verify
-ttyd --version  # Should show 1.7.x or higher
-```
-
 ### git
 
 | Requirement | Value |
@@ -193,7 +170,6 @@ codex --version
 |------------|-----------------|-----------|
 | Node.js | 18.0.0 | Yes |
 | tmux | 3.0 | Yes |
-| ttyd | 1.7.0 | Yes |
 | git | 2.5.0 | Yes |
 | gh | latest | Yes |
 | Claude Code | latest | At least one AI CLI |
@@ -210,7 +186,7 @@ All dependencies are available via Homebrew:
 
 ```bash
 # Install all core dependencies at once
-brew install node tmux ttyd gh
+brew install node tmux gh
 
 # Git is included with Xcode command line tools
 xcode-select --install
@@ -218,15 +194,13 @@ xcode-select --install
 
 ### Ubuntu/Debian
 
-Most dependencies are available via apt, except ttyd which must be built from source:
+Most dependencies are available via apt:
 
 ```bash
 # Core dependencies
 sudo apt install nodejs npm tmux git
 
 # gh requires adding GitHub's apt repository (see above)
-
-# ttyd must be built from source (see above)
 ```
 
 ### Windows
@@ -267,7 +241,7 @@ sudo apt update
 sudo apt install tmux
 ```
 
-### ttyd connection issues
+### Terminal connection issues
 
 Ensure no firewall is blocking the ports (default: 4200-4299):
 

package/skeleton/builders.md

@@ -4,7 +4,7 @@ Track active builder agents here. Update manually or via `architect status`.
 
 ## Status Values
 
-- **spawning**: Worktree being created, ttyd starting
+- **spawning**: Worktree being created, terminal starting
 - **implementing**: Builder is working
 - **blocked**: Builder waiting for architect input
 - **pr-ready**: Builder has created a PR

package/skeleton/consult-types/impl-review.md

@@ -55,6 +55,15 @@ KEY_ISSUES:
 - `REQUEST_CHANGES`: Issues that must be fixed before proceeding
 - `COMMENT`: Minor suggestions, can proceed but note feedback
 
+## Scoping (Multi-Phase Plans)
+
+When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
+- **ONLY review work belonging to the current plan phase**
+- The query will specify which phase you are reviewing
+- Do NOT request changes for functionality scheduled in later phases
+- Do NOT flag missing features that are out of scope for this phase
+- If unsure whether something belongs to this phase, check the plan file
+
 ## Notes
 
 - This is a phase-level review, not the final PR review

package/skeleton/porch/prompts/defend.md

@@ -1,6 +1,6 @@
 # Defend Phase Prompt
 
-You are the **Tester** hat in a Ralph-SPIDER loop.
+You are the **Tester** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/evaluate.md

@@ -1,6 +1,6 @@
 # Evaluate Phase Prompt
 
-You are the **Verifier** hat in a Ralph-SPIDER loop.
+You are the **Verifier** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 
@@ -66,7 +66,7 @@ Create or update evaluation notes in the status file:
 ```markdown
 ## Evaluation Report
 
-**Evaluator**: Ralph-SPIDER Verifier
+**Evaluator**: Ralph-SPIR Verifier
 **Date**: {date}
 **Phase**: {phase-name}
 

package/skeleton/porch/prompts/implement.md

@@ -1,6 +1,6 @@
 # Implement Phase Prompt
 
-You are the **Implementer** hat in a Ralph-SPIDER loop.
+You are the **Implementer** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/plan.md

@@ -1,6 +1,6 @@
 # Plan Phase Prompt
 
-You are the **Planner** hat in a Ralph-SPIDER loop.
+You are the **Planner** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/review.md

@@ -1,10 +1,10 @@
 # Review Phase Prompt
 
-You are the **Reviewer** hat in a Ralph-SPIDER loop.
+You are the **Reviewer** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 
-Create the final deliverables: PR and review document. This is the capstone of the SPIDER protocol.
+Create the final deliverables: PR and review document. This is the capstone of the SPIR protocol.
 
 ## Input Context
 
@@ -27,7 +27,7 @@ Create `codev/reviews/{project-id}-{name}.md` with:
 - **ID**: {project-id}
 - **Spec**: `codev/specs/{project-id}-{name}.md`
 - **Plan**: `codev/plans/{project-id}-{name}.md`
-- **Protocol**: ralph-spider
+- **Protocol**: ralph-spir
 - **Completed**: {date}
 
 ## Summary
@@ -78,7 +78,7 @@ One paragraph summarizing what was built and why.
 2. Pattern that worked well
 
 ### Process Insights
-1. What worked well in the SPIDER process
+1. What worked well in the SPIR process
 2. What could be improved
 
 ## Recommendations

package/skeleton/porch/prompts/specify.md

@@ -1,6 +1,6 @@
 # Specify Phase Prompt
 
-You are the **Spec Writer** hat in a Ralph-SPIDER loop.
+You are the **Spec Writer** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/understand.md

@@ -30,7 +30,7 @@ TICK is appropriate when:
 - [ ] Requirements are clear
 - [ ] No architectural changes needed
 
-If NOT appropriate, signal: `<signal>NEEDS_SPIDER</signal>`
+If NOT appropriate, signal: `<signal>NEEDS_SPIR</signal>`
 
 ### 3. Document Understanding
 
@@ -58,4 +58,4 @@ When understanding is complete:
 
 - DO NOT start implementing
 - DO NOT create new spec files (amend existing)
-- Keep scope small - if > 300 LOC, recommend SPIDER instead
+- Keep scope small - if > 300 LOC, recommend SPIR instead