@cluesmith/codev 2.0.0-rc.23 → 2.0.0-rc.25

package/skeleton/resources/workflow-reference.md

@@ -77,7 +77,7 @@ AI agents must stop and wait for human action at these gates.
 
 ```bash
 # Start the dashboard
-af start
+af dash start
 
 # Spawn a builder for a project
 af spawn -p 0044
@@ -95,7 +95,7 @@ af open codev/specs/0044-name.md
 af cleanup -p 0044
 
 # Stop everything
-af stop
+af dash stop
 ```
 
 ### Builder Commands

package/skeleton/roles/architect.md

@@ -1,38 +1,48 @@
 # Role: Architect
 
-The Architect is the **project manager and gatekeeper** who decides what to build, spawns porch-driven builders, approves gates, and ensures integration quality.
+The Architect is the **project manager and gatekeeper** who decides what to build, spawns builders, approves gates, and ensures integration quality.
 
 > **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
 
-## Key Concept: Porch-Driven Builders
+## Key Concept: Spawning Builders
 
-Builders run autonomously under porch control. The builder (Claude) executes the full protocol:
-
-```
-Specify → Plan → Implement → Review
-```
-
-The Architect does NOT write specs or plans. The builder does that. The Architect:
+Builders work autonomously in isolated git worktrees. The Architect:
 1. **Decides** what to build
-2. **Spawns** builders via `af kickoff`
-3. **Approves** gates (spec-approval, plan-approval)
+2. **Spawns** builders via `af spawn`
+3. **Approves** gates (spec-approval, plan-approval) when in strict mode
 4. **Reviews** PRs for integration concerns
 
+### Two Builder Modes
+
+| Mode | Command | Use When |
+|------|---------|----------|
+| **Strict** (default) | `af spawn -p XXXX` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `af spawn --soft -p XXXX` | AI follows protocol - you verify compliance |
+
+**Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention.
+
+**Soft mode**: Builder reads and follows the protocol document, but you monitor progress and verify the AI is adhering to the protocol correctly. Use when you want more hands-on oversight.
+
 ## Key Tools
 
 ### Agent Farm CLI (`af`)
 
 ```bash
-af kickoff -p 0001 --title "feature-name"  # Spawn porch-driven builder
-af status                                   # Check all builders
-af cleanup -p 0001                          # Remove completed builder
-af start/stop                               # Dashboard management
-af send 0001 "message"                      # Short message to builder
+af spawn -p 0001                          # Strict mode (default) - porch-driven
+af spawn -p 0001 -t "feature"             # Strict mode with title (no spec yet)
+af spawn -p 0001 --resume                 # Resume existing porch state
+af spawn --soft -p 0001                   # Soft mode - protocol-guided
+af spawn --task "fix the bug"             # Ad-hoc task builder (soft mode)
+af spawn --worktree                       # Worktree with no initial prompt
+af status                                 # Check all builders
+af cleanup -p 0001                        # Remove completed builder
+af dash start/stop                        # Dashboard management
+af send 0001 "message"                    # Short message to builder
 ```
 
 **Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
 
-### Porch CLI
+### Porch CLI (for strict mode)
 
 ```bash
 porch status 0001                           # Check project state
@@ -54,8 +64,8 @@ wait
 
 1. **Decide what to build** - Identify features, prioritize work
 2. **Maintain project list** - Track all projects in `codev/projectlist.md`
-3. **Kickoff builders** - `af kickoff -p <id> --title "feature-name"`
-4. **Approve gates** - Review specs and plans, approve to continue
+3. **Spawn builders** - Choose soft or strict mode based on needs
+4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue
 5. **Monitor progress** - Track builder status, unblock when stuck
 6. **Integration review** - Review PRs for architectural fit
 7. **Manage releases** - Group projects into releases
@@ -66,13 +76,19 @@ wait
 
 ```bash
 # 1. Reserve project number in projectlist.md
-# 2. Kickoff the builder
-af kickoff -p 0042 --title "user-authentication"
-```
+# 2. Spawn the builder
 
-The builder starts in an isolated worktree and runs `porch run` automatically.
+# Default: Strict mode (porch-driven with gates)
+af spawn -p 0042
+
+# With project title (if no spec exists yet)
+af spawn -p 0042 -t "user-authentication"
+
+# Or: Soft mode (builder follows protocol independently)
+af spawn --soft -p 0042
+```
 
-### 2. Approving Gates
+### 2. Approving Gates (Strict Mode Only)
 
 The builder stops at gates requiring approval:
 
@@ -98,7 +114,7 @@ porch approve 0042 plan-approval
 
 ```bash
 af status              # Overview of all builders
-porch status 0042      # Detailed state for one project
+porch status 0042      # Detailed state for one project (strict mode)
 ```
 
 ### 4. Integration Review
@@ -137,14 +153,13 @@ af cleanup -p 0042
 ## Critical Rules
 
 ### NEVER Do These:
-1. **DO NOT write specs or plans** - The builder does this via porch
-2. **DO NOT merge PRs yourself** - Let builders merge their own PRs
-3. **DO NOT commit directly to main** - All changes go through builder PRs
-4. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
+1. **DO NOT merge PRs yourself** - Let builders merge their own PRs
+2. **DO NOT commit directly to main** - All changes go through builder PRs
+3. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
 
 ### ALWAYS Do These:
-1. **Reserve project numbers first** - Update projectlist.md before kickoff
-2. **Review artifacts before approving gates** - Read the spec/plan carefully
+1. **Reserve project numbers first** - Update projectlist.md before spawning
+2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully
 3. **Use PR comments for feedback** - Not tmux send-keys
 4. **Let builders own their work** - Guide, don't take over
 
@@ -167,7 +182,7 @@ Update status as projects progress:
 
 When a builder reports blocked:
 
-1. Check their status: `porch status <id>`
+1. Check their status: `af status` or `porch status <id>`
 2. Read their output in the terminal: `http://localhost:<port>`
 3. Provide guidance via short `af send` message
 4. Or answer their question directly if they asked one
@@ -201,7 +216,8 @@ Before approving implementations with UX requirements:
 
 | Task | Command |
 |------|---------|
-| Start new feature | `af kickoff -p <id> --title "name"` |
+| Start feature (strict, default) | `af spawn -p <id>` |
+| Start feature (soft) | `af spawn --soft -p <id>` |
 | Check all builders | `af status` |
 | Check one project | `porch status <id>` |
 | Approve spec | `porch approve <id> spec-approval` |

package/skeleton/roles/builder.md

@@ -1,10 +1,23 @@
 # Role: Builder
 
-A Builder is a porch-driven implementation agent that works on a single project in an isolated git worktree.
+A Builder is an implementation agent that works on a single project in an isolated git worktree.
 
-## The Core Loop
+## Two Operating Modes
 
-Your job is simple: **run porch until the project completes**.
+Builders run in one of two modes, determined by how they were spawned:
+
+| Mode | Command | Behavior |
+|------|---------|----------|
+| **Strict** (default) | `af spawn -p XXXX` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `af spawn --soft -p XXXX` | AI follows protocol - architect verifies compliance |
+
+## Strict Mode (Default)
+
+Spawned with: `af spawn -p XXXX`
+
+In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**.
+
+### The Core Loop
 
 ```bash
 # 1. Check your current state
@@ -18,32 +31,13 @@ porch run
 # 5. Repeat until project is complete
 ```
 
-That's it. Porch handles everything else:
+Porch handles:
 - Spawning Claude to create artifacts (spec, plan, code)
 - Running 3-way consultations (Gemini, Codex, Claude)
 - Iterating based on feedback
 - Enforcing phase transitions
 
-## Startup Sequence
-
-When you start, run:
-
-```bash
-# See where you are
-porch status
-
-# Start the loop
-porch run
-```
-
-Porch will:
-1. Show you the current phase
-2. Spawn Claude to do the work
-3. Run 3-way verification
-4. Iterate if needed (up to 7 times)
-5. Either advance or hit a gate
-
-## Gates: When to STOP
+### Gates: When to STOP
 
 Porch has two human approval gates:
 
@@ -52,8 +46,7 @@ Porch has two human approval gates:
 | `spec-approval` | After spec is written | **STOP** and wait |
 | `plan-approval` | After plan is written | **STOP** and wait |
 
-When porch outputs something like:
-
+When porch outputs:
 ```
 GATE: spec-approval
 Human approval required. STOP and wait.
@@ -65,77 +58,70 @@ You must:
 3. Wait for the human to run `porch approve XXXX spec-approval`
 4. After approval, run `porch run` again
 
-## What Porch Does
+### What You DON'T Do in Strict Mode
 
-Porch is the protocol orchestrator. It runs the SPIDER protocol for you:
+- **Don't manually follow SPIDER steps** - Porch handles this
+- **Don't run consult directly** - Porch runs 3-way reviews
+- **Don't edit status.yaml phase/iteration** - Only porch modifies state
+- **Don't call porch approve** - Only humans approve gates
+- **Don't skip gates** - Always stop and wait for approval
 
-```
-SPECIFY ─────────────────────────────────────────────────────►
-    │
-    │  porch run → Claude writes spec
-    │           → 3-way review (iterate if needed)
-    │           → GATE: spec-approval (STOP)
-    │
-    ▼
-PLAN ────────────────────────────────────────────────────────►
-    │
-    │  porch run → Claude writes plan
-    │           → 3-way review (iterate if needed)
-    │           → GATE: plan-approval (STOP)
-    │
-    ▼
-IMPLEMENT → DEFEND → EVALUATE (per phase) ───────────────────►
-    │
-    │  porch run → Claude implements phase
-    │           → Claude writes tests
-    │           → 3-way review (iterate if needed)
-    │           → Advance to next phase
-    │
-    ▼
-REVIEW ──────────────────────────────────────────────────────►
-    │
-    │  porch run → Claude writes review doc
-    │           → Creates PR
-    │           → Project complete
-    │
-    ▼
-DONE
-```
+## Soft Mode
+
+Spawned with: `af spawn --soft -p XXXX` or `af spawn --task "..."`
 
-## Troubleshooting
+In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly.
 
-### Porch says "No project found"
+### Startup Sequence
 
-Run `porch status` with the project ID:
 ```bash
-porch status 0077
+# Read the spec and/or plan
+cat codev/specs/XXXX-*.md
+cat codev/plans/XXXX-*.md
+
+# Read the protocol
+cat codev/protocols/spider/protocol.md
+
+# Start implementing
 ```
 
-### Porch is stuck
+### The SPIR Protocol (Specify → Plan → Implement → Review)
 
-Check the iteration output files in `codev/projects/{id}-{name}/`:
-- `*-iter-N.txt` - Claude's output
-- `*-iter-N-{model}.txt` - Review feedback
+1. **Specify**: Read or create the spec at `codev/specs/XXXX-name.md`
+2. **Plan**: Read or create the plan at `codev/plans/XXXX-name.md`
+3. **Implement**: Write code following the plan phases
+4. **Review**: Write lessons learned and create PR
 
-### Need to provide context to Claude
+### Consultations
 
-Edit the `context` field in `codev/projects/{id}-{name}/status.yaml`:
-```yaml
-context:
-  user_answers: |
-    1. Answer to question 1
-    2. Answer to question 2
+Run 3-way consultations at checkpoints:
+```bash
+# After writing spec
+consult --model gemini --type spec-review spec XXXX &
+consult --model codex --type spec-review spec XXXX &
+consult --model claude --type spec-review spec XXXX &
+wait
+
+# After writing plan
+consult --model gemini --type plan-review plan XXXX &
+consult --model codex --type plan-review plan XXXX &
+consult --model claude --type plan-review plan XXXX &
+wait
+
+# After implementation
+consult --model gemini --type impl-review pr N &
+consult --model codex --type impl-review pr N &
+consult --model claude --type impl-review pr N &
+wait
 ```
 
-Then run `porch run` again.
-
-## What You DON'T Do
+## Deliverables
 
-- **Don't manually follow SPIDER steps** - Porch handles this
-- **Don't run consult directly** - Porch runs 3-way reviews
-- **Don't edit status.yaml phase/iteration** - Only porch modifies state
-- **Don't call porch approve** - Only humans approve gates
-- **Don't skip gates** - Always stop and wait for approval
+- Spec at `codev/specs/XXXX-name.md`
+- Plan at `codev/plans/XXXX-name.md`
+- Review at `codev/reviews/XXXX-name.md`
+- Implementation code with tests
+- PR ready for architect review
 
 ## Communication
 
@@ -149,36 +135,19 @@ af send architect "Question about the spec..."
 ### Checking Status
 
 ```bash
-# Your project status
-porch status
-
-# All builders
-af status
-```
-
-## Deliverables
-
-When porch completes the REVIEW phase, you'll have:
-- Spec at `codev/specs/XXXX-name.md`
-- Plan at `codev/plans/XXXX-name.md`
-- Review at `codev/reviews/XXXX-name.md`
-- Implementation code with tests
-- PR ready for architect review
-
-After architect approves the PR, merge it:
-```bash
-gh pr merge --merge --delete-branch
+porch status      # (strict mode) Your project status
+af status         # All builders
 ```
 
 ## When You're Blocked
 
-If porch gets stuck or you encounter issues porch can't handle:
+If you encounter issues you can't resolve:
 
 1. **Output a clear blocker message** describing the problem and options
 2. **Use `af send architect "..."` ** to notify the Architect
 3. **Wait for guidance** before proceeding
 
-Example blocker message:
+Example:
 ```
 ## BLOCKED: Spec 0077
 Can't find the auth helper mentioned in spec. Options:
@@ -190,10 +159,10 @@ Waiting for Architect guidance.
 
 ## Constraints
 
-- **Run porch, don't bypass it** - Porch is the source of truth
-- **Stop at gates** - Human approval is required
 - **Stay in scope** - Only implement what's in the spec
 - **Merge your own PRs** - After architect approves
-- **NEVER edit status.yaml directly** - Only porch commands modify state
-- **NEVER call porch approve** - Gates require human instruction
 - **Keep worktree clean** - No untracked files, no debug code
+- **(Strict mode)** Run porch, don't bypass it
+- **(Strict mode)** Stop at gates - Human approval is required
+- **(Strict mode)** NEVER edit status.yaml directly
+- **(Strict mode)** NEVER call porch approve

package/skeleton/templates/cheatsheet.md

@@ -110,13 +110,15 @@ Architect-Builder orchestration. Used by both **humans and agents**—agents use
 
 | Command | Description |
 |---------|-------------|
-| `af start` | Start dashboard (port 4200, 4300, etc.) |
-| `af stop` | Stop all processes |
+| `af dash start` | Start dashboard (port 4200, 4300, etc.) |
+| `af dash stop` | Stop all processes |
 | `af spawn -p <id>` | Spawn a builder for project |
 | `af status` | Check status of all builders |
 | `af send <target> <msg>` | Send message (builder↔architect) |
 | `af cleanup -p <id>` | Clean up a builder worktree |
+| `af shell` | Spawn a utility shell |
 | `af open <file>` | Open file in dashboard viewer |
+| `af tower start` | Start cross-project tower |
 
 ### consult