prompts iteration

CLAUDE.md

@@ -2,20 +2,24 @@
 
 Multi-agent orchestration system for Claude Code. Scale horizontally (multiple planning sessions) and vertically (weavers executing in parallel).
 
+**Read the complete workflow:** [WORKFLOW.md](WORKFLOW.md)
+
 ## Architecture
 
 ```
 You (Terminal)
-    |
-    v
-Planner (interactive)     <- You talk here
-    |
-    v (specs)
+    │
+    │ /plan
+    ▼
+Planner (interactive)     ← You talk here
+    │
+    │ (writes specs)
+    ▼
 Orchestrator (tmux background)
-    |
-    +-> Weaver 01 (tmux) -> Verifier (subagent) -> PR
-    +-> Weaver 02 (tmux) -> Verifier (subagent) -> PR
-    +-> Weaver 03 (tmux) -> Verifier (subagent) -> PR
+    │
+    ├─→ Weaver 01 (tmux) → Verifier (subagent) → PR
+    ├─→ Weaver 02 (tmux) → Verifier (subagent) → PR
+    └─→ Weaver 03 (tmux) → Verifier (subagent) → PR
 ```
 
 ## Commands
@@ -57,18 +61,44 @@ claude
         state.json        # Orchestrator state
         summary.md        # Human-readable results
         weavers/
-          w-01.json       # Weaver status + session ID
+          w-01.json       # Weaver status
           w-02.json
 ```
 
 ## All Agents Use Opus
 
-Every agent in the system uses `claude-opus-4-5-20250514`:
+Every agent uses `claude-opus-4-5-20250514`:
 - Planner
 - Orchestrator
 - Weavers
 - Verifiers (subagents)
 
+## Key Rules
+
+### Tests Never Ship
+
+Weavers may write tests for verification. They are **never committed**:
+```bash
+git reset HEAD -- '*.test.*' '*.spec.*' '__tests__/' 'tests/'
+```
+
+### PRs Are Always Created
+
+A weaver's success = PR created. No PR = failure.
+
+### Verification Is Mandatory
+
+Weavers spawn verifier subagents. No self-verification.
+
+### Context Is Isolated
+
+| Agent | Sees | Doesn't See |
+|-------|------|-------------|
+| Planner | Full codebase, human | Weaver impl |
+| Orchestrator | Specs, skill index | Actual code |
+| Weaver | Its spec, its skills | Other weavers |
+| Verifier | Verification spec | Building spec |
+
 ## Tmux Session Naming
 
 ```
@@ -79,16 +109,10 @@ vertical-<plan-id>-w-02     # Weaver 2
 
 ## Skill Index
 
-Skills live in `skill-index/skills/`. The orchestrator uses `skill-index/index.yaml` to match `skill_hints` from specs to actual skills.
-
-To add a skill:
-1. Create `skill-index/skills/<name>/SKILL.md`
-2. Add entry to `skill-index/index.yaml`
+Skills live in `skill-index/skills/`. The orchestrator uses `skill-index/index.yaml` to match `skill_hints` from specs.
 
 ## Resuming Sessions
 
-Every Claude session can be resumed:
-
 ```bash
 # Get session ID from weaver status
 cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq -r .session_id
@@ -100,20 +124,12 @@ claude --resume <session-id>
 ## Debugging
 
 ```bash
-# Source helpers
 source lib/tmux.sh
 
-# List all sessions
-vertical_list_sessions
-
-# Attach to a weaver
-vertical_attach vertical-plan-20260119-1430-w-01
-
-# Capture output
-vertical_capture_output vertical-plan-20260119-1430-w-01
-
-# Kill a plan's sessions
-vertical_kill_plan plan-20260119-1430
+vertical_list_sessions                           # List all sessions
+vertical_attach vertical-plan-20260119-1430-w-01 # Attach to weaver
+vertical_capture_output <session> # Capture output
+vertical_kill_plan plan-20260119-1430            # Kill plan sessions
 ```
 
 ## Spec Format
@@ -149,18 +165,19 @@ pr:
   title: "feat: description"
 ```
 
-## Context Isolation
+## Oracle for Complex Planning
 
-Each agent gets minimal, focused context:
+For complex tasks (5+ specs, unclear dependencies, architecture decisions), the planner invokes Oracle:
 
-| Agent | Receives | Does NOT Receive |
-|-------|----------|------------------|
-| Planner | Full codebase, your questions | Weaver implementation |
-| Orchestrator | Specs, skill index, status | Actual code |
-| Weaver | Spec + skills | Other weavers' work |
-| Verifier | Verification spec only | Building requirements |
+```bash
+npx -y @steipete/oracle \
+  --engine browser \
+  --model gpt-5.2-codex \
+  -p "$(cat /tmp/oracle-prompt.txt)" \
+  --file "src/**"
+```
 
-This prevents context bloat and keeps agents focused.
+Oracle takes 10-60 minutes and outputs `plan.md`. The planner transforms this into spec YAMLs.
 
 ## Parallel Execution
 
@@ -173,13 +190,3 @@ Terminal 3: /plan notification system
 ```
 
 Each spawns its own orchestrator and weavers. All run in parallel.
-
-## Weavers Always Create PRs
-
-Weavers follow the eval-skill pattern:
-1. Build implementation
-2. Spawn verifier subagent
-3. Fix on failure (max 5 iterations)
-4. Create PR on success
-
-No PR = failure. This is enforced.