harivansh-afk/claude-code-vertical
1
0
Fork 0
mirror of https://github.com/harivansh-afk/claude-code-vertical.git synced 2026-04-15 09:01:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

prompts iteration

Browse source
This commit is contained in:
Rathi Harivansh 2026-01-19 16:56:25 +00:00
parent 593bdb8208
commit bc2b015fff
11 changed files with 2245 additions and 933 deletions
Download patch file Download diff file Expand all files Collapse all files

105
CLAUDE.md
View file

@ -2,20 +2,24 @@
Multi-agent orchestration system for Claude Code. Scale horizontally (multiple planning sessions) and vertically (weavers executing in parallel). 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 ## Architecture
``` ```
You (Terminal) You (Terminal)
| │
v │ /plan
Planner (interactive) <- You talk here ▼
| Planner (interactive) ← You talk here
v (specs) │
│ (writes specs)
▼
Orchestrator (tmux background) Orchestrator (tmux background)
| │
+-> Weaver 01 (tmux) -> Verifier (subagent) -> PR ├─→ Weaver 01 (tmux) → Verifier (subagent) → PR
+-> Weaver 02 (tmux) -> Verifier (subagent) -> PR ├─→ Weaver 02 (tmux) → Verifier (subagent) → PR
+-> Weaver 03 (tmux) -> Verifier (subagent) -> PR └─→ Weaver 03 (tmux) → Verifier (subagent) → PR
``` ```
## Commands ## Commands
@ -57,18 +61,44 @@ claude
state.json # Orchestrator state state.json # Orchestrator state
summary.md # Human-readable results summary.md # Human-readable results
weavers/ weavers/
w-01.json # Weaver status + session ID w-01.json # Weaver status
w-02.json w-02.json
``` ```
## All Agents Use Opus ## All Agents Use Opus
Every agent in the system uses `claude-opus-4-5-20250514`: Every agent uses `claude-opus-4-5-20250514`:
- Planner - Planner
- Orchestrator - Orchestrator
- Weavers - Weavers
- Verifiers (subagents) - 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 ## Tmux Session Naming
``` ```
@ -79,16 +109,10 @@ vertical-<plan-id>-w-02 # Weaver 2
## Skill Index ## Skill Index
Skills live in `skill-index/skills/`. The orchestrator uses `skill-index/index.yaml` to match `skill_hints` from specs to actual skills. Skills live in `skill-index/skills/`. The orchestrator uses `skill-index/index.yaml` to match `skill_hints` from specs.
To add a skill:
1. Create `skill-index/skills/<name>/SKILL.md`
2. Add entry to `skill-index/index.yaml`
## Resuming Sessions ## Resuming Sessions
Every Claude session can be resumed:
```bash ```bash
# Get session ID from weaver status # Get session ID from weaver status
cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq -r .session_id cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq -r .session_id
@ -100,20 +124,12 @@ claude --resume <session-id>
## Debugging ## Debugging
```bash ```bash
# Source helpers
source lib/tmux.sh source lib/tmux.sh
# List all sessions vertical_list_sessions # List all sessions
vertical_list_sessions vertical_attach vertical-plan-20260119-1430-w-01 # Attach to weaver
vertical_capture_output <session> # Capture output
# Attach to a weaver vertical_kill_plan plan-20260119-1430 # Kill plan sessions
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
``` ```
## Spec Format ## Spec Format
@ -149,18 +165,19 @@ pr:
title: "feat: description" 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 | ```bash
|-------|----------|------------------| npx -y @steipete/oracle \
| Planner | Full codebase, your questions | Weaver implementation | --engine browser \
| Orchestrator | Specs, skill index, status | Actual code | --model gpt-5.2-codex \
| Weaver | Spec + skills | Other weavers' work | -p "$(cat /tmp/oracle-prompt.txt)" \
| Verifier | Verification spec only | Building requirements | --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 ## Parallel Execution
@ -173,13 +190,3 @@ Terminal 3: /plan notification system
``` ```
Each spawns its own orchestrator and weavers. All run in parallel. 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.

61
README.md
View file

@ -31,20 +31,30 @@ claude
> /status plan-20260119-1430 > /status plan-20260119-1430
``` ```
## Documentation
| Document | Description |
|----------|-------------|
| [WORKFLOW.md](WORKFLOW.md) | Complete workflow guide with examples |
| [CLAUDE.md](CLAUDE.md) | Project instructions and quick reference |
| [docs/spec-schema-v2.md](docs/spec-schema-v2.md) | Full spec YAML schema |
## Architecture ## Architecture
``` ```
You (Terminal) You (Terminal)
| │
v │ /plan
Planner (interactive) <- You talk here ▼
| Planner (interactive) ← You talk here
v (specs) │
│ (writes specs)
▼
Orchestrator (tmux background) Orchestrator (tmux background)
| │
+-> Weaver 01 (tmux) -> Verifier (subagent) -> PR ├─→ Weaver 01 (tmux) → Verifier (subagent) → PR
+-> Weaver 02 (tmux) -> Verifier (subagent) -> PR ├─→ Weaver 02 (tmux) → Verifier (subagent) → PR
+-> Weaver 03 (tmux) -> Verifier (subagent) -> PR └─→ Weaver 03 (tmux) → Verifier (subagent) → PR
``` ```
## Commands ## Commands
@ -60,15 +70,17 @@ Orchestrator (tmux background)
``` ```
claude-code-vertical/ claude-code-vertical/
├── CLAUDE.md # Project instructions ├── CLAUDE.md # Project instructions
├── WORKFLOW.md # Complete workflow guide
├── skills/ ├── skills/
│ ├── planner/ # Interactive planning │ ├── planner/ # Interactive planning
│ ├── orchestrator/ # Tmux + weaver management │ ├── orchestrator/ # Tmux + weaver management
│ ├── weaver-base/ # Base skill for all weavers │ ├── weaver-base/ # Base skill for all weavers
│ └── verifier/ # Verification subagent │ ├── verifier/ # Verification subagent
│ └── oracle/ # Deep planning with GPT-5.2 Codex
├── commands/ ├── commands/
│ ├── plan.md │ ├── vertical-plan.md
│ ├── build.md │ ├── vertical-build.md
│ └── status.md │ └── vertical-status.md
├── skill-index/ ├── skill-index/
│ ├── index.yaml # Skill registry │ ├── index.yaml # Skill registry
│ └── skills/ # Available skills │ └── skills/ # Available skills
@ -83,16 +95,17 @@ claude-code-vertical/
Every agent uses `claude-opus-4-5-20250514` for maximum capability. Every agent uses `claude-opus-4-5-20250514` for maximum capability.
## Key Rules
1. **Tests never ship** - Weavers may write tests for verification, but they're never committed
2. **PRs always created** - Weaver success = PR created
3. **Verification mandatory** - Weavers spawn verifier subagents
4. **Context isolated** - Each agent sees only what it needs
## Skill Index ## Skill Index
The orchestrator matches `skill_hints` from specs to skills in `skill-index/index.yaml`. The orchestrator matches `skill_hints` from specs to skills in `skill-index/index.yaml`.
Current skills include:
- Swift/iOS development (concurrency, SwiftUI, testing, debugging)
- Build and memory debugging
- Database and networking patterns
- Agent orchestration tools
## Resume Any Session ## Resume Any Session
```bash ```bash
@ -113,3 +126,13 @@ vertical_list_sessions # List tmux sessions
vertical_attach <session> # Attach to session vertical_attach <session> # Attach to session
vertical_kill_plan <plan-id> # Kill all sessions for a plan vertical_kill_plan <plan-id> # Kill all sessions for a plan
``` ```
## Oracle for Complex Planning
For complex tasks, the planner invokes Oracle (GPT-5.2 Codex) for deep planning:
```bash
npx -y @steipete/oracle --engine browser --model gpt-5.2-codex ...
```
Oracle runs 10-60 minutes and outputs `plan.md`, which the planner transforms into specs.

628
WORKFLOW.md Normal file
View file

@ -0,0 +1,628 @@
# Claude Code Vertical - Complete Workflow
This document describes the complete multi-agent workflow for Claude Code Vertical.
## Philosophy
This system is **prompt-driven**. Every agent is Claude reading markdown instructions. There is no traditional code—the markdown files ARE the program. Claude's ability to follow instructions precisely makes this possible.
**Key principles:**
- Tight prompts with no ambiguity
- Each agent has a single, focused responsibility
- Context isolation prevents bloat and confusion
- Human remains in control at key decision points
---
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ HUMAN │
│ │
│ You talk to the Planner. Everything else runs in the background. │
│ │
│ Commands: │
│ /plan Start planning session │
│ /build <plan-id> Execute plan (spawns orchestrator + weavers) │
│ /status <plan-id> Check progress │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ /plan
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PLANNER (Interactive) │
│ │
│ Location: Your terminal (direct Claude session) │
│ Skill: skills/planner/SKILL.md │
│ │
│ Responsibilities: │
│ • Ask clarifying questions │
│ • Research the codebase │
│ • Invoke Oracle for complex tasks (optional) │
│ • Design specs (each spec = one PR) │
│ • Write specs to .claude/vertical/plans/<plan-id>/specs/ │
│ │
│ Output: Spec YAML files + meta.json │
│ Handoff: Tells you to run /build <plan-id> │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ /build <plan-id>
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (tmux background) │
│ │
│ Location: tmux session "vertical-<plan-id>-orch" │
│ Skill: skills/orchestrator/SKILL.md │
│ │
│ Responsibilities: │
│ • Read specs and analyze dependencies │
│ • Match skill_hints → skill-index │
│ • Launch weavers in parallel tmux sessions │
│ • Track progress by polling status files │
│ • Launch dependent specs when dependencies complete │
│ • Write summary.md when all done │
│ │
│ Human Interaction: None (runs autonomously) │
│ Output: run/state.json, run/summary.md │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ WEAVER 01 │ │ WEAVER 02 │ │ WEAVER 03 │
│ │ │ │ │ │
│ tmux: vertical- │ │ tmux: vertical- │ │ tmux: vertical- │
│ <plan-id>-w-01 │ │ <plan-id>-w-02 │ │ <plan-id>-w-03 │
│ │ │ │ │ │
│ Skill: │ │ Skill: │ │ Skill: │
│ weaver-base + │ │ weaver-base + │ │ weaver-base + │
│ matched skills │ │ matched skills │ │ matched skills │
│ │ │ │ │ │
│ 1. Parse spec │ │ 1. Parse spec │ │ 1. (waiting for │
│ 2. Build code │ │ 2. Build code │ │ dependency) │
│ 3. Spawn verifier │ │ 3. Spawn verifier │ │ │
│ 4. Fix if failed │ │ 4. Fix if failed │ │ │
│ 5. Create PR │ │ 5. Create PR │ │ │
│ │ │ │ │ │
│ Output: PR #42 │ │ Output: PR #43 │ │ │
└─────────┬─────────┘ └─────────┬─────────┘ └───────────────────┘
│ │
│ Task tool │ Task tool
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ VERIFIER │ │ VERIFIER │
│ (subagent) │ │ (subagent) │
│ │ │ │
│ • Run checks │ │ • Run checks │
│ • Fast-fail │ │ • Fast-fail │
│ • PASS or FAIL │ │ • PASS or FAIL │
└───────────────────┘ └───────────────────┘
```
---
## Complete Workflow
### Phase 1: Planning
**You start a planning session:**
```bash
$ claude
> /plan
```
**What happens:**
1. Claude loads `skills/planner/SKILL.md`
2. Claude generates plan ID: `plan-20260119-143052`
3. Claude creates `.claude/vertical/plans/<plan-id>/specs/` directory
4. Claude asks: "What would you like to build?"
**Interactive Q&A:**
```
Planner: What would you like to build?
You: I want to add user authentication with Google OAuth and email/password.
Planner: Let me understand the requirements better.
1. What's your tech stack?
You: Next.js with Prisma and PostgreSQL.
Planner: 2. Do you need role-based access control?
You: Yes, admin and user roles.
Planner: 3. Any specific features?
You: Password reset and email verification.
Planner: Let me research your codebase...
[Reads existing patterns, checks file structure]
I found:
- Stack: Next.js 14, Prisma, PostgreSQL
- Existing patterns: Using NextAuth would fit well
- Files to modify: prisma/schema.prisma, src/pages/api/...
This is a complex task. I'll use Oracle for deep planning.
```
**Oracle (for complex tasks):**
```
Planner: Running Oracle for deep planning...
This typically takes 10-60 minutes.
I'll monitor and let you know when ready.
[Oracle runs via browser engine with GPT-5.2 Codex]
...
Planner: Oracle complete. Here's the breakdown:
Phase 1: Schema
01-schema.yaml - Add User, Session, Account tables
Phase 2: Backend
02-password-service.yaml - Password hashing with bcrypt
03-google-oauth.yaml - Google OAuth integration
04-auth-endpoints.yaml - Login/register/reset endpoints
Phase 3: Frontend
05-login-ui.yaml - Login page with Google button
Parallel: 01, 02, 03 can run together
Sequential: 04 waits for 02 and 03; 05 waits for 04
Approve this breakdown? [yes/modify]
```
**Specs written:**
```
Planner: ════════════════════════════════════════════════════════════════
PLANNING COMPLETE: plan-20260119-143052
════════════════════════════════════════════════════════════════
Specs created:
.claude/vertical/plans/plan-20260119-143052/specs/
01-schema.yaml
02-password-service.yaml
03-google-oauth.yaml
04-auth-endpoints.yaml
05-login-ui.yaml
To execute:
/build plan-20260119-143052
════════════════════════════════════════════════════════════════
```
### Phase 2: Execution
**You trigger the build:**
```bash
> /build plan-20260119-143052
```
**What happens:**
1. Claude generates orchestrator prompt with plan context
2. Claude launches tmux session: `vertical-plan-20260119-143052-orch`
3. Claude confirms launch and returns control to you
```
════════════════════════════════════════════════════════════════
BUILD LAUNCHED: plan-20260119-143052
════════════════════════════════════════════════════════════════
Orchestrator: vertical-plan-20260119-143052-orch
Monitor commands:
/status plan-20260119-143052
tmux attach -t vertical-plan-20260119-143052-orch
Results will be at:
.claude/vertical/plans/plan-20260119-143052/run/summary.md
════════════════════════════════════════════════════════════════
```
**Behind the scenes (orchestrator):**
```
Orchestrator: Reading specs...
Found 5 specs.
Dependency analysis:
01-schema.yaml → base: main (parallel)
02-password.yaml → base: main (parallel)
03-google-oauth.yaml → base: main (parallel)
04-endpoints.yaml → base: feature/password (waits)
05-login-ui.yaml → base: feature/endpoints (waits)
Matching skills...
01 → database-patterns
02 → security-patterns
03 → security-patterns
04 → api-design
05 → react-patterns
Launching parallel weavers...
vertical-plan-20260119-143052-w-01 → 01-schema
vertical-plan-20260119-143052-w-02 → 02-password
vertical-plan-20260119-143052-w-03 → 03-google-oauth
Polling status...
```
**Behind the scenes (weaver):**
```
Weaver 01: Parsing spec 01-schema.yaml...
Requirements:
- Add User model to Prisma
- Add Session model
- Add Account model for OAuth
Building...
Files created:
+ prisma/schema.prisma (modified)
Spawning verifier...
Verifier: 1. [command] npx prisma validate → PASS
2. [command] npx prisma generate → PASS
3. [file-contains] model User → PASS
RESULT: PASS
Weaver 01: Verification passed. Creating PR...
git checkout -b auth/01-schema main
git add prisma/schema.prisma
git commit -m "feat(auth): add user authentication schema"
git push -u origin auth/01-schema
gh pr create...
PR #42 created.
```
### Phase 3: Monitoring
**You check status periodically:**
```bash
> /status plan-20260119-143052
```
```
=== Plan: plan-20260119-143052 ===
Status: running
Started: 2026-01-19T14:35:00Z
=== Specs ===
01-schema.yaml
02-password-service.yaml
03-google-oauth.yaml
04-auth-endpoints.yaml
05-login-ui.yaml
=== Weavers ===
w-01 complete 01-schema.yaml PR #42
w-02 verifying 02-password-service.yaml -
w-03 complete 03-google-oauth.yaml PR #44
w-04 waiting 04-auth-endpoints.yaml -
w-05 waiting 05-login-ui.yaml -
=== Tmux Sessions ===
vertical-plan-20260119-143052-orch running
vertical-plan-20260119-143052-w-02 running
```
**Optional: Attach to watch:**
```bash
$ tmux attach -t vertical-plan-20260119-143052-w-02
```
### Phase 4: Results
**When complete, the orchestrator outputs:**
```
╔══════════════════════════════════════════════════════════════════╗
║ BUILD COMPLETE: plan-20260119-143052 ║
╠══════════════════════════════════════════════════════════════════╣
║ ✓ 01-schema complete PR #42 ║
║ ✓ 02-password complete PR #43 ║
║ ✓ 03-google-oauth complete PR #44 ║
║ ✓ 04-endpoints complete PR #45 ║
║ ✓ 05-login-ui complete PR #46 ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ Summary: .claude/vertical/plans/plan-20260119-143052/run/summary.md
║ PRs: gh pr list ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
```
**View summary:**
```bash
$ cat .claude/vertical/plans/plan-20260119-143052/run/summary.md
# Build Complete: plan-20260119-143052
**Status**: complete
**Started**: 2026-01-19T14:35:00Z
**Completed**: 2026-01-19T15:12:00Z
## Results
| Spec | Status | PR |
|------|--------|-----|
| 01-schema | ✓ complete | [#42](https://github.com/.../42) |
| 02-password | ✓ complete | [#43](https://github.com/.../43) |
| 03-google-oauth | ✓ complete | [#44](https://github.com/.../44) |
| 04-endpoints | ✓ complete | [#45](https://github.com/.../45) |
| 05-login-ui | ✓ complete | [#46](https://github.com/.../46) |
## PRs Ready for Review
Merge in this order (stacked):
1. #42 - feat(auth): add user authentication schema
2. #43 - feat(auth): add password hashing service
3. #44 - feat(auth): add Google OAuth integration
4. #45 - feat(auth): add authentication endpoints
5. #46 - feat(auth): add login UI
## Commands
```bash
gh pr list
gh pr merge 42 --merge
```
```
**Review and merge PRs:**
```bash
$ gh pr list
$ gh pr view 42
$ gh pr merge 42 --merge
$ gh pr merge 43 --merge
# ... etc
```
---
## Tmux Session Reference
| Session | Purpose | Attach Command |
|---------|---------|----------------|
| `vertical-<plan-id>-orch` | Orchestrator | `tmux attach -t vertical-<plan-id>-orch` |
| `vertical-<plan-id>-w-01` | Weaver 01 | `tmux attach -t vertical-<plan-id>-w-01` |
| `vertical-<plan-id>-w-02` | Weaver 02 | `tmux attach -t vertical-<plan-id>-w-02` |
| ... | ... | ... |
**Detach from tmux:** `Ctrl+B` then `D`
**Helper functions:**
```bash
source lib/tmux.sh
vertical_list_sessions # List all vertical sessions
vertical_status # Show all plans with status
vertical_attach <session> # Attach to session
vertical_capture_output <session> # Capture recent output
vertical_kill_plan <plan-id> # Kill all sessions for plan
vertical_kill_all # Kill all vertical sessions
```
---
## Directory Structure
```
.claude/vertical/
plans/
plan-20260119-143052/
meta.json # Plan metadata
specs/
01-schema.yaml # Spec files
02-password.yaml
...
run/
state.json # Orchestrator state
summary.md # Human-readable summary
weavers/
w-01.json # Weaver 01 status
w-02.json # Weaver 02 status
...
```
---
## Spec Format
```yaml
name: feature-name
description: |
What this PR accomplishes.
skill_hints:
- security-patterns
- typescript-patterns
building_spec:
requirements:
- Specific requirement 1
- Specific requirement 2
constraints:
- Rule to follow
files:
- src/path/to/file.ts
verification_spec:
- type: command
run: "npm run typecheck"
expect: exit_code 0
- type: file-contains
path: src/path/to/file.ts
pattern: "expected"
pr:
branch: feature/name
base: main
title: "feat(scope): description"
```
---
## Error Handling
### Weaver Fails After 5 Iterations
The weaver stops and reports failure. The orchestrator:
1. Marks the spec as failed
2. Blocks dependent specs
3. Continues with independent specs
4. Notes failure in summary
**To debug:**
```bash
# Check the error
cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json
# Resume the session
claude --resume <session-id>
# Or attach to tmux if still running
tmux attach -t vertical-<plan-id>-w-01
```
### Dependency Failure
If spec A fails and spec B depends on A:
- B is marked as `blocked`
- B is never launched
- Summary notes the blocking
### Killing a Stuck Build
```bash
source lib/tmux.sh
vertical_kill_plan <plan-id>
```
---
## Key Rules
### Tests Are Never Committed
Weavers may write tests during implementation to satisfy verification. But they **never commit test files**:
```bash
# Weaver always runs:
git reset HEAD -- '*.test.*' '*.spec.*' '__tests__/' 'tests/'
```
Tests are ephemeral. They verify the implementation but don't ship.
### PRs Are Always Created
A weaver's success condition is a created PR. No PR = failure.
### Verification Is Mandatory
Weavers must spawn a verifier subagent. They cannot self-verify.
### Context Is Isolated
| Agent | Sees | Doesn't See |
|-------|------|-------------|
| Planner | Full codebase, human input | Weaver implementation |
| Orchestrator | Specs, skill index | Actual code |
| Weaver | Its spec, its skills | Other weavers |
| Verifier | Verification spec | Building requirements |
---
## Parallel Execution
### Multiple Plans
Run multiple planning sessions:
```
Terminal 1: /plan authentication
Terminal 2: /plan payments
Terminal 3: /plan notifications
```
Each creates its own plan ID and executes independently.
### Parallel Weavers
Within a plan, independent specs run in parallel:
```
01-schema.yaml (base: main) ──┬── parallel
02-backend.yaml (base: main) ──┤
03-frontend.yaml (base: feature/backend) ── sequential (waits for 02)
```
---
## Resuming Sessions
Every Claude session can be resumed:
```bash
# Find session ID
cat .claude/vertical/plans/<plan-id>/meta.json | jq -r .planner_session
# Resume
claude --resume <session-id>
```
Weaver sessions are also saved:
```bash
cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq -r .session_id
claude --resume <session-id>
```
---
## Quick Reference
| Command | Description |
|---------|-------------|
| `/plan` | Start planning session |
| `/build <plan-id>` | Execute plan |
| `/status <plan-id>` | Check status |
| `tmux attach -t <session>` | Watch a session |
| `Ctrl+B D` | Detach from tmux |
| `source lib/tmux.sh` | Load helper functions |
| `vertical_status` | Show all plans |
| `vertical_kill_plan <id>` | Kill a plan |
| `gh pr list` | List created PRs |
| `gh pr merge <n>` | Merge a PR |

204
commands/vertical-build.md
View file

@ -1,5 +1,5 @@
--- ---
description: Execute a plan by launching orchestrator and weavers in tmux. Creates PRs for each spec. description: Execute a plan by launching orchestrator in tmux. Creates PRs for each spec.
argument-hint: <plan-id> [spec-names...] argument-hint: <plan-id> [spec-names...]
--- ---
@ -14,75 +14,129 @@ Execute a plan. Launches orchestrator in tmux, which spawns weavers for each spe
/build plan-20260119-1430 01-schema 02-backend /build plan-20260119-1430 01-schema 02-backend
``` ```
## What Happens ## What You Do
1. Read plan from `.claude/vertical/plans/<plan-id>/` When `/build <plan-id>` is invoked:
2. Launch orchestrator in tmux: `vertical-<plan-id>-orch`
3. Orchestrator reads specs, selects skills, spawns weavers
4. Each weaver runs in tmux: `vertical-<plan-id>-w-01`, etc.
5. Weavers build, verify, create PRs
6. Results written to `.claude/vertical/plans/<plan-id>/run/`
## Execution Flow ### Step 1: Validate Plan Exists
```
/build plan-20260119-1430
|
+-> Orchestrator (tmux: vertical-plan-20260119-1430-orch)
|
+-> Weaver 01 (tmux: vertical-plan-20260119-1430-w-01)
| |
| +-> Verifier (subagent)
| +-> PR #42
|
+-> Weaver 02 (tmux: vertical-plan-20260119-1430-w-02)
| |
| +-> Verifier (subagent)
| +-> PR #43
|
+-> Summary written to run/summary.md
```
## Parallelization
- Independent specs (all with `pr.base: main`) run in parallel
- Dependent specs (with `pr.base: <other-branch>`) wait for dependencies
## Monitoring
Check status while running:
```
/status plan-20260119-1430
```
Or directly:
```bash ```bash
# List tmux sessions if [ ! -f ".claude/vertical/plans/<plan-id>/meta.json" ]; then
tmux list-sessions | grep vertical echo "Error: Plan not found: <plan-id>"
echo "Run /status to see available plans"
exit 1
fi
```
# Attach to orchestrator ### Step 2: Generate Orchestrator Prompt
tmux attach -t vertical-plan-20260119-1430-orch
# Attach to a weaver ```bash
tmux attach -t vertical-plan-20260119-1430-w-01 cat > /tmp/orch-prompt-<plan-id>.md << 'PROMPT_EOF'
<orchestrator-skill>
$(cat skills/orchestrator/SKILL.md)
</orchestrator-skill>
# Capture weaver output <plan-id><plan-id></plan-id>
tmux capture-pane -t vertical-plan-20260119-1430-w-01 -p <repo-path>$(pwd)</repo-path>
Execute the plan. Spawn weavers. Track progress. Write summary.
Begin now.
PROMPT_EOF
```
### Step 3: Launch Orchestrator in Tmux
```bash
tmux new-session -d -s "vertical-<plan-id>-orch" -c "$(pwd)" \
"claude -p \"\$(cat /tmp/orch-prompt-<plan-id>.md)\" --dangerously-skip-permissions --model claude-opus-4-5-20250514; echo '[Orchestrator complete. Press any key to close.]'; read"
```
### Step 4: Confirm Launch
Output to human:
```
════════════════════════════════════════════════════════════════
BUILD LAUNCHED: <plan-id>
════════════════════════════════════════════════════════════════
Orchestrator: vertical-<plan-id>-orch
The orchestrator will:
1. Read specs from .claude/vertical/plans/<plan-id>/specs/
2. Spawn weavers in parallel tmux sessions
3. Track progress and handle dependencies
4. Write summary when complete
Monitor commands:
/status <plan-id> # Check status
tmux attach -t vertical-<plan-id>-orch # Watch orchestrator
tmux list-sessions | grep vertical # List all sessions
Results will be at:
.claude/vertical/plans/<plan-id>/run/summary.md
════════════════════════════════════════════════════════════════
```
## Partial Execution
To execute specific specs only:
```
/build plan-20260119-1430 01-schema 02-backend
```
Modify the orchestrator prompt:
```
<specs-to-execute>01-schema, 02-backend</specs-to-execute>
```
The orchestrator will only process those specs.
## Monitoring While Running
### Check Status
```bash
/status <plan-id>
```
### Attach to Orchestrator
```bash
tmux attach -t vertical-<plan-id>-orch
# Detach: Ctrl+B then D
```
### Attach to a Weaver
```bash
tmux attach -t vertical-<plan-id>-w-01
# Detach: Ctrl+B then D
```
### Capture Weaver Output
```bash
tmux capture-pane -t vertical-<plan-id>-w-01 -p -S -100
``` ```
## Results ## Results
When complete, find results at: When complete, find results at:
- `.claude/vertical/plans/<plan-id>/run/state.json` - Overall status | File | Contents |
- `.claude/vertical/plans/<plan-id>/run/summary.md` - Human-readable summary |------|----------|
- `.claude/vertical/plans/<plan-id>/run/weavers/w-*.json` - Per-weaver status | `run/state.json` | Overall status and weaver states |
| `run/summary.md` | Human-readable summary with PR links |
| `run/weavers/w-*.json` | Per-weaver status |
## Debugging Failures ## Debugging Failures
If a weaver fails, you can resume its session: ### Resume a Failed Weaver
```bash ```bash
# Get session ID from weaver status # Get session ID from weaver status
@ -92,7 +146,7 @@ cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq -r .session_id
claude --resume <session-id> claude --resume <session-id>
``` ```
Or attach to the tmux session if still running: ### Attach to Running Weaver
```bash ```bash
tmux attach -t vertical-<plan-id>-w-01 tmux attach -t vertical-<plan-id>-w-01
@ -101,20 +155,40 @@ tmux attach -t vertical-<plan-id>-w-01
## Killing a Build ## Killing a Build
```bash ```bash
# Kill all sessions for a plan # Source helpers
source lib/tmux.sh source lib/tmux.sh
vertical_kill_plan plan-20260119-1430
# Kill all sessions for this plan
vertical_kill_plan <plan-id>
# Or kill everything # Or kill everything
vertical_kill_all vertical_kill_all
``` ```
## Implementation Notes ## What Happens Behind the Scenes
This command: ```
1. Loads orchestrator skill /build plan-20260119-1430
2. Generates orchestrator prompt with plan context │
3. Spawns tmux session with `claude -p "<prompt>" --dangerously-skip-permissions --model opus` ├─→ Create orchestrator prompt
4. Returns immediately (orchestrator runs in background) │
├─→ Launch tmux: vertical-plan-20260119-1430-orch
The orchestrator handles everything from there. │ │
│ ├─→ Read specs
│ ├─→ Analyze dependencies
│ ├─→ Launch weavers in parallel
│ │ │
│ │ ├─→ vertical-plan-20260119-1430-w-01
│ │ │ └─→ Build → Verify → PR #42
│ │ │
│ │ ├─→ vertical-plan-20260119-1430-w-02
│ │ │ └─→ Build → Verify → PR #43
│ │ │
│ │ └─→ (waits for dependencies...)
│ │
│ ├─→ Poll weaver status
│ ├─→ Launch dependent specs when ready
│ └─→ Write summary.md
│
└─→ Human runs /status to check progress
```

123
commands/vertical-plan.md
View file

@ -1,5 +1,5 @@
--- ---
description: Start an interactive planning session. Design specs through Q&A, then hand off to build. description: Start an interactive planning session. Design specs through Q&A with the planner.
argument-hint: [description] argument-hint: [description]
--- ---
@ -14,52 +14,100 @@ Start a planning session. You become the planner agent.
/plan Add user authentication with OAuth /plan Add user authentication with OAuth
``` ```
## What Happens ## What You Do
1. Load the planner skill from `skills/planner/SKILL.md` When `/plan` is invoked:
2. Generate a plan ID: `plan-YYYYMMDD-HHMMSS`
3. Create plan directory: `.claude/vertical/plans/<plan-id>/`
4. Enter interactive planning mode
## Planning Flow ### Step 1: Load Planner Skill
1. **Understand** - Ask questions until the task is crystal clear Read and internalize `skills/planner/SKILL.md`.
2. **Research** - Explore the codebase, find patterns
3. **Design** - Break into specs (each = one PR)
4. **Write** - Create spec files in `specs/` directory
5. **Hand off** - Tell user to run `/build <plan-id>`
## Spec Output ### Step 2: Generate Plan ID
Specs go to: `.claude/vertical/plans/<plan-id>/specs/` ```bash
plan_id="plan-$(date +%Y%m%d-%H%M%S)"
```
### Step 3: Create Plan Directory
```bash
mkdir -p ".claude/vertical/plans/${plan_id}/specs"
mkdir -p ".claude/vertical/plans/${plan_id}/run/weavers"
```
### Step 4: Start Interactive Planning
Follow the planner skill phases:
1. **Understand** - Ask questions until task is crystal clear
2. **Research** - Explore codebase, find patterns
3. **Assess Complexity** - Decide if Oracle is needed
4. **Oracle (optional)** - For complex tasks, invoke Oracle
5. **Design** - Break into specs (each = one PR)
6. **Write** - Create spec YAML files
7. **Hand off** - Tell human to run `/build <plan-id>`
### Step 5: Confirm Plan Ready
When specs are written:
``` ```
01-schema.yaml ════════════════════════════════════════════════════════════════
02-backend.yaml PLANNING COMPLETE: <plan-id>
03-frontend.yaml ════════════════════════════════════════════════════════════════
Specs created:
.claude/vertical/plans/<plan-id>/specs/
01-schema.yaml
02-backend.yaml
03-frontend.yaml
To execute:
/build <plan-id>
To check status:
/status <plan-id>
════════════════════════════════════════════════════════════════
```
## When to Use Oracle
The planner will invoke Oracle for:
| Trigger | Why |
|---------|-----|
| 5+ specs needed | Complex dependency management |
| Unclear dependencies | Need deep analysis |
| Architecture decisions | Needs extended thinking |
| Performance/migration planning | Requires careful sequencing |
Oracle runs via browser engine (10-60 minutes typical).
## Spec Output Location
```
.claude/vertical/plans/<plan-id>/
meta.json # Plan metadata
specs/
01-schema.yaml # First spec
02-backend.yaml # Second spec
03-frontend.yaml # Third spec
``` ```
## Transitioning to Build ## Transitioning to Build
When specs are ready: When specs are ready, the human runs:
``` ```
Specs ready. To execute: /build <plan-id>
/build <plan-id>
To execute specific specs:
/build <plan-id> 01-schema 02-backend
To check status:
/status <plan-id>
``` ```
This launches the orchestrator in tmux, which spawns weavers.
## Multiple Planning Sessions ## Multiple Planning Sessions
You can run multiple planning sessions in parallel: Run multiple planning sessions in parallel:
``` ```
# Terminal 1 # Terminal 1
@ -67,16 +115,27 @@ You can run multiple planning sessions in parallel:
# Terminal 2 # Terminal 2
/plan Add payment processing /plan Add payment processing
# Terminal 3
/plan Add notification system
``` ```
Each gets its own plan-id and can be built independently. Each gets its own plan-id and can be built independently.
## Resuming ## Resuming a Planning Session
Planning sessions are Claude Code sessions. Resume with: Planning sessions are Claude Code sessions. Resume with:
``` ```bash
claude --resume <session-id> claude --resume <session-id>
``` ```
The session ID is saved in `.claude/vertical/plans/<plan-id>/meta.json`. The session ID is saved in `.claude/vertical/plans/<plan-id>/meta.json`.
## Example Interaction
```
Human: /plan
Claude: Starting plan: plan-20260119-143052
What would you like to build?

182
commands/vertical-status.md
View file

@ -10,13 +10,49 @@ Check the status of plans and weavers.
## Usage ## Usage
``` ```
/status # All plans /status # All plans
/status plan-20260119-1430 # Specific plan /status plan-20260119-1430 # Specific plan
``` ```
## Output ## What You Do
### All Plans When `/status` is invoked:
### Without Arguments (All Plans)
```bash
# List active tmux sessions
echo "=== Active Tmux Sessions ==="
tmux list-sessions 2>/dev/null | grep "^vertical-" || echo "No active sessions"
echo ""
# List plan statuses
echo "=== Plan Status ==="
if [ -d ".claude/vertical/plans" ]; then
for plan_dir in .claude/vertical/plans/*/; do
if [ -d "$plan_dir" ]; then
plan_id=$(basename "$plan_dir")
state_file="${plan_dir}run/state.json"
if [ -f "$state_file" ]; then
status=$(jq -r '.status // "unknown"' "$state_file" 2>/dev/null)
echo " ${plan_id}: ${status}"
else
meta_file="${plan_dir}meta.json"
if [ -f "$meta_file" ]; then
echo " ${plan_id}: ready (not started)"
else
echo " ${plan_id}: incomplete"
fi
fi
fi
done
else
echo " No plans found"
fi
```
Output:
``` ```
=== Active Tmux Sessions === === Active Tmux Sessions ===
@ -31,7 +67,67 @@ vertical-plan-20260119-1445-orch
plan-20260119-1400: complete plan-20260119-1400: complete
``` ```
### Specific Plan ### With Plan ID (Specific Plan)
```bash
plan_id="$1"
plan_dir=".claude/vertical/plans/${plan_id}"
# Validate plan exists
if [ ! -d "$plan_dir" ]; then
echo "Error: Plan not found: ${plan_id}"
exit 1
fi
# Read state
state_file="${plan_dir}/run/state.json"
if [ -f "$state_file" ]; then
status=$(jq -r '.status // "unknown"' "$state_file")
started=$(jq -r '.started_at // "-"' "$state_file")
else
status="ready (not started)"
started="-"
fi
echo "=== Plan: ${plan_id} ==="
echo "Status: ${status}"
echo "Started: ${started}"
echo ""
# List specs
echo "=== Specs ==="
for spec in "${plan_dir}/specs/"*.yaml; do
[ -f "$spec" ] && echo " $(basename "$spec")"
done
echo ""
# List weaver status
echo "=== Weavers ==="
weavers_dir="${plan_dir}/run/weavers"
if [ -d "$weavers_dir" ]; then
for weaver_file in "${weavers_dir}"/*.json; do
if [ -f "$weaver_file" ]; then
w_name=$(basename "$weaver_file" .json)
w_status=$(jq -r '.status // "unknown"' "$weaver_file" 2>/dev/null)
w_spec=$(jq -r '.spec // "?"' "$weaver_file" 2>/dev/null)
w_pr=$(jq -r '.pr // "-"' "$weaver_file" 2>/dev/null)
printf " %-10s %-15s %-30s %s\n" "$w_name" "$w_status" "$w_spec" "$w_pr"
fi
done
else
echo " No weavers yet"
fi
echo ""
# List tmux sessions for this plan
echo "=== Tmux Sessions ==="
tmux list-sessions 2>/dev/null | grep "vertical-${plan_id}" | while read line; do
session_name=$(echo "$line" | cut -d: -f1)
echo " ${session_name}"
done || echo " No active sessions"
```
Output:
``` ```
=== Plan: plan-20260119-1430 === === Plan: plan-20260119-1430 ===
@ -44,70 +140,74 @@ Started: 2026-01-19T14:35:00Z
03-frontend.yaml 03-frontend.yaml
=== Weavers === === Weavers ===
w-01 complete 01-schema.yaml https://github.com/owner/repo/pull/42 w-01 complete 01-schema.yaml https://github.com/...
w-02 verifying 02-backend.yaml - w-02 verifying 02-backend.yaml -
w-03 waiting 03-frontend.yaml - w-03 waiting 03-frontend.yaml -
=== Tmux Sessions === === Tmux Sessions ===
vertical-plan-20260119-1430-orch running vertical-plan-20260119-1430-orch
vertical-plan-20260119-1430-w-01 done vertical-plan-20260119-1430-w-01
vertical-plan-20260119-1430-w-02 running vertical-plan-20260119-1430-w-02
``` ```
## Weaver Statuses ## Weaver Status Reference
| Status | Meaning | | Status | Meaning |
|--------|---------| |--------|---------|
| waiting | Waiting for dependency | | waiting | Waiting for dependency to complete |
| building | Implementing the spec | | building | Implementing the spec |
| verifying | Running verification checks | | verifying | Running verification checks |
| fixing | Fixing verification failures | | fixing | Fixing verification failures |
| complete | PR created successfully | | complete | PR created successfully |
| failed | Failed after max iterations | | failed | Failed after max iterations |
| blocked | Dependency failed | | blocked | Dependency failed |
| crashed | Session terminated unexpectedly |
## Quick Commands ## Quick Actions
Based on status, suggest actions:
| Status | Suggested Action |
|--------|------------------|
| complete | `gh pr list` to review PRs |
| running | `tmux attach -t <session>` to watch |
| failed | `claude --resume <session-id>` to debug |
| ready | `/build <plan-id>` to start |
## Viewing Results
```bash
# Summary (after completion)
cat .claude/vertical/plans/<plan-id>/run/summary.md
# State JSON
cat .claude/vertical/plans/<plan-id>/run/state.json | jq
# Specific weaver
cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq
# List PRs
gh pr list
```
## Tmux Helper Commands
```bash ```bash
# Source helpers # Source helpers
source lib/tmux.sh source lib/tmux.sh
# List all sessions # List all vertical sessions
vertical_list_sessions vertical_list_sessions
# Status for all plans # Full status
vertical_status vertical_status
# Weaver status for a plan # Weaver status for a plan
vertical_weaver_status plan-20260119-1430 vertical_weaver_status plan-20260119-1430
# Capture recent output from a weaver # Capture recent output
vertical_capture_output vertical-plan-20260119-1430-w-01 vertical_capture_output vertical-plan-20260119-1430-w-01
# Attach to a session # Attach to a session
vertical_attach vertical-plan-20260119-1430-w-01 vertical_attach vertical-plan-20260119-1430-w-01
``` ```
## Reading Results
After completion:
```bash
# Summary
cat .claude/vertical/plans/plan-20260119-1430/run/summary.md
# State
cat .claude/vertical/plans/plan-20260119-1430/run/state.json | jq
# Specific weaver
cat .claude/vertical/plans/plan-20260119-1430/run/weavers/w-01.json | jq
```
## PRs Created
When weavers complete, PRs are listed in:
- The summary.md file
- Each weaver's status JSON (`pr` field)
- The overall state.json (`weavers.<id>.pr`)
Merge order is indicated in summary.md for stacked PRs.

435
skills/oracle/SKILL.md
View file

@ -1,53 +1,119 @@
--- ---
name: oracle-planner name: oracle
description: Codex 5.2 planning specialist using oracle CLI + llmjunky's proven prompt patterns. Call when planning is complex or requires structured breakdown. description: Deep planning via Oracle CLI (GPT-5.2 Codex). Use for complex tasks requiring extended thinking (10-60 minutes). Outputs plan.md for planner to transform into specs.
model: opus model: opus
--- ---
# Oracle Planner - Codex Planning Specialist # Oracle
Leverage oracle CLI with Codex 5.2 for deep, structured planning. Uses llmjunky's battle-tested prompt patterns. Oracle bundles your prompt + codebase files into a single request for GPT-5.2 Codex. Use it when planning is complex and requires deep, extended thinking.
## When to Call Me ## When to Use Oracle
- Complex features needing careful breakdown | Trigger | Why |
- Multi-phase implementations |---------|-----|
- Unclear dependency graphs | 5+ specs needed | Complex dependency management |
- Parallel task identification needed | Unclear dependency graph | Needs analysis |
- Architecture decisions | Architecture decisions | Extended thinking helps |
- Migration plans | Migration planning | Requires careful sequencing |
- Any planning where you need ~10min+ of deep thinking | Performance optimization | Needs deep code analysis |
| Any planning >10 minutes | Offload to Codex |
## When NOT to Use Oracle
- Simple 1-2 spec tasks
- Clear, linear implementations
- Bug fixes
- Quick refactors
## Prerequisites ## Prerequisites
Oracle CLI must be installed: Oracle CLI installed:
```bash ```bash
npm install -g @steipete/oracle npm install -g @steipete/oracle
``` ```
Reference: skill-index/skills/oracle/SKILL.md for oracle CLI best practices Or use npx:
## How I Work ```bash
npx -y @steipete/oracle --help
```
1. **Planner gathers context** - uses AskUserTool for clarifying questions ## Workflow
2. **Planner crafts perfect prompt** - following templates below
3. **Planner calls oracle** - via CLI with full context
4. **Oracle outputs plan.md** - structured breakdown from Codex 5.2
5. **Planner transforms** - plan.md → spec yamls
## Calling Oracle (Exact Commands) ### Step 1: Craft the Prompt
Write to `/tmp/oracle-prompt.txt`:
```
Create a detailed implementation plan for [TASK].
## Context
- Project: [what the project does]
- Stack: [frameworks, languages, tools]
- Location: [key directories and files]
## Requirements
[ALL requirements gathered from human]
- [Requirement 1]
- [Requirement 2]
- Features needed:
- [Feature A]
- [Feature B]
- NOT needed: [explicit out-of-scope]
## Plan Structure
Output as plan.md with this structure:
# Plan: [Task Name]
## Overview
[Summary + recommended approach]
## Phase N: [Phase Name]
### Task N.M: [Task Name]
- Location: [file paths]
- Description: [what to do]
- Dependencies: [task IDs this depends on]
- Complexity: [1-10]
- Acceptance Criteria: [specific, testable]
## Dependency Graph
[Which tasks run parallel vs sequential]
## Testing Strategy
[What tests prove success]
## Instructions
- Write complete plan to plan.md
- Do NOT ask clarifying questions
- Be specific and actionable
- Include file paths and code locations
```
### Step 2: Preview Token Count
**1. Preview first (no tokens spent):**
```bash ```bash
npx -y @steipete/oracle --dry-run summary --files-report \ npx -y @steipete/oracle --dry-run summary --files-report \
-p "$(cat /tmp/oracle-prompt.txt)" \ -p "$(cat /tmp/oracle-prompt.txt)" \
--file "src/**" \ --file "src/**" \
--file "!**/*.test.*" \ --file "!**/*.test.*" \
--file "!**/*.snap" --file "!**/*.snap" \
--file "!node_modules" \
--file "!dist"
``` ```
Check token count (target: <196k tokens). If over budget, narrow files.
**2. Run with browser engine (main path):** **Target:** <196k tokens
**If over budget:**
- Narrow file selection
- Exclude more test/build directories
- Split into focused prompts
### Step 3: Run Oracle
```bash ```bash
npx -y @steipete/oracle \ npx -y @steipete/oracle \
--engine browser \ --engine browser \
@ -62,225 +128,152 @@ npx -y @steipete/oracle \
--file "!dist" --file "!dist"
``` ```
**Why browser engine?** **Why browser engine:**
- GPT-5.2 Codex runs take 10-60 minutes (normal) - GPT-5.2 Codex runs take 10-60 minutes (normal)
- Browser mode handles long runs + reattach - Browser mode handles long runs
- Sessions stored in `~/.oracle/sessions` - Sessions stored in `~/.oracle/sessions`
- Can reattach if timeout
### Step 4: Monitor
Tell the human:
```
Oracle is running. This typically takes 10-60 minutes.
I will check status periodically.
```
Check status:
**3. Check status (if run detached):**
```bash ```bash
npx -y @steipete/oracle status --hours 1 npx -y @steipete/oracle status --hours 1
``` ```
**4. Reattach to session:** ### Step 5: Reattach (if timeout)
If the CLI times out, do NOT re-run. Reattach:
```bash ```bash
npx -y @steipete/oracle session <session-id> --render > /tmp/oracle-plan-result.txt npx -y @steipete/oracle session <session-id> --render > /tmp/oracle-result.txt
``` ```
**Important:** ### Step 6: Read Output
- Don't re-run if timeout - reattach instead
- Use `--force` only if you truly want a duplicate run
- Files >1MB are rejected (split or narrow match)
- Default-ignored: node_modules, dist, coverage, .git, .next, build, tmp
## Prompt Template Oracle writes `plan.md` to current directory. Read it:
Use this EXACT structure when crafting my prompt: ```bash
cat plan.md
```
### Step 7: Transform to Specs
Convert Oracle's phases/tasks → spec YAML files:
| Oracle Output | Spec YAML |
|---------------|-----------|
| Phase N | Group of related specs |
| Task N.M | Individual spec file |
| Dependencies | pr.base field |
| Location | building_spec.files |
| Acceptance Criteria | verification_spec |
## File Attachment Patterns
**Include:**
```bash
--file "src/**"
--file "prisma/**"
--file "convex/**"
```
**Exclude:**
```bash
--file "!**/*.test.*"
--file "!**/*.spec.*"
--file "!**/*.snap"
--file "!node_modules"
--file "!dist"
--file "!build"
--file "!coverage"
--file "!.next"
```
**Default ignored:** node_modules, dist, coverage, .git, .turbo, .next, build, tmp
**Size limit:** Files >1MB are rejected
## Prompt Templates
### For Authentication
``` ```
Create a detailed implementation plan for [TASK]. Create a detailed implementation plan for adding authentication.
## Context
- Project: [app name]
- Stack: Next.js, Prisma, PostgreSQL
- Location: src/pages/api/ for API, src/components/ for UI
## Requirements ## Requirements
[List ALL requirements gathered from user]
- [Requirement 1]
- [Requirement 2]
- Features needed:
- [Feature A]
- [Feature B]
- NOT needed: [Explicitly state what's out of scope]
## Plan Structure
Use this template structure:
```markdown
# Plan: [Task Name]
**Generated**: [Date]
**Estimated Complexity**: [Low/Medium/High]
## Overview
[Brief summary of what needs to be done and the general approach, including recommended libraries/tools]
## Prerequisites
- [Dependencies or requirements that must be met first]
- [Tools, libraries, or access needed]
## Phase 1: [Phase Name]
**Goal**: [What this phase accomplishes]
### Task 1.1: [Task Name]
- **Location**: [File paths or components involved]
- **Description**: [What needs to be done]
- **Dependencies**: [Task IDs this depends on, e.g., "None" or "1.2, 2.1"]
- **Complexity**: [1-10]
- **Test-First Approach**:
- [Test to write before implementation]
- [What the test should verify]
- **Acceptance Criteria**:
- [Specific, testable criteria]
### Task 1.2: [Task Name]
[Same structure...]
## Phase 2: [Phase Name]
[...]
## Testing Strategy
- **Unit Tests**: [What to unit test, frameworks to use]
- **Integration Tests**: [API/service integration tests]
- **E2E Tests**: [Critical user flows to test end-to-end]
- **Test Coverage Goals**: [Target coverage percentage]
## Dependency Graph
[Show which tasks can run in parallel vs which must be sequential]
- Tasks with no dependencies: [list - these can start immediately]
- Task dependency chains: [show critical path]
## Potential Risks
- [Things that could go wrong]
- [Mitigation strategies]
## Rollback Plan
- [How to undo changes if needed]
```
### Task Guidelines
Each task must:
- Be specific and actionable (not vague)
- Have clear inputs and outputs
- Be independently testable
- Include file paths and specific code locations
- Include dependencies so parallel execution is possible
- Include complexity score (1-10)
Break large tasks into smaller ones:
- ✗ Bad: "Implement Google OAuth"
- ✓ Good:
- "Add Google OAuth config to environment variables"
- "Install and configure passport-google-oauth20 package"
- "Create OAuth callback route handler in src/routes/auth.ts"
- "Add Google sign-in button to login UI"
- "Write integration tests for OAuth flow"
## Instructions
- Write the complete plan to a file called `plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation for each task
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file
Begin immediately.
```
## Clarifying Question Patterns
Before calling me, gather context with these question types:
### For "implement auth"
- What authentication methods do you need? (email/password, OAuth providers like Google/GitHub, SSO, magic links)
- Do you need role-based access control (RBAC) or just authenticated/unauthenticated?
- What's your backend stack? (Node/Express, Python/Django, etc.)
- Where will you store user credentials/sessions? (Database, Redis, JWT stateless)
- Do you need features like: password reset, email verification, 2FA?
- Any compliance requirements? (SOC2, GDPR, HIPAA)
### For "build an API"
- What resources/entities does this API need to manage?
- REST or GraphQL?
- What authentication will the API use?
- Expected scale/traffic?
- Do you need rate limiting, caching, versioning?
### For "migrate to microservices"
- Which parts of the monolith are you migrating first?
- What's your deployment target? (K8s, ECS, etc.)
- How will services communicate? (REST, gRPC, message queues)
- What's your timeline and team capacity?
### For "add testing"
- What testing levels do you need? (unit, integration, e2e)
- What's your current test coverage?
- What frameworks do you prefer or already use?
- What's the most critical functionality to test first?
### For "performance optimization"
- What specific performance issues are you seeing?
- Current metrics (load time, response time, throughput)?
- What's the target performance?
- Where are the bottlenecks? (DB queries, API calls, rendering)
- What profiling have you done?
### For "database migration"
- What's the source and target database?
- How much data needs to be migrated?
- Can you afford downtime? If so, how much?
- Do you need dual-write/read during migration?
- What's your rollback strategy?
## Example Prompt (Auth)
**After gathering:**
- Methods: Email/password + Google OAuth - Methods: Email/password + Google OAuth
- Stack: Next.js + Prisma + PostgreSQL - Roles: Admin and User
- Roles: Admin/User
- Features: Password reset, email verification - Features: Password reset, email verification
- No 2FA, no special compliance - NOT needed: 2FA, SSO
**Prompt to send me:**
```
Create a detailed implementation plan for adding authentication to a Next.js web application.
## Requirements
- Authentication methods: Email/password + Google OAuth
- Framework: Next.js (App Router)
- Database: PostgreSQL with Prisma ORM
- Role-based access: Admin and User roles
- Features needed:
- User registration and login
- Password reset flow
- Email verification
- Google OAuth integration
- Session management
- NOT needed: 2FA, SSO, special compliance
## Plan Structure ## Plan Structure
[Use the full template above] [standard structure]
## Instructions
- Write the complete plan to a file called `plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation for each task
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file
Begin immediately.
``` ```
## Important Notes ### For API Development
- **I only output plan.md** - you transform it into spec yamls ```
- **No interaction** - one-shot execution with full context Create a detailed implementation plan for building a REST API.
- **Always gpt-5.2-codex + xhigh** - this is my configuration
- **File output: plan.md** in current directory
- **Parallel tasks identified** - I explicitly list dependencies
## After I Run ## Context
- Project: [app name]
- Stack: [framework]
- Location: src/api/ for routes
## Requirements
- Resources: [entities]
- Auth: [method]
- Rate limiting: [yes/no]
- NOT needed: [out of scope]
## Plan Structure
[standard structure]
```
### For Migration
```
Create a detailed implementation plan for migrating [from] to [to].
## Context
- Current: [current state]
- Target: [target state]
- Constraints: [downtime, rollback needs]
## Requirements
- Data to migrate: [what]
- Dual-write period: [yes/no]
- Rollback strategy: [required]
## Plan Structure
[standard structure]
```
## Important Rules
1. **One-shot execution** - Oracle doesn't interact, just outputs
2. **Always gpt-5.2-codex** - Use Codex model for coding tasks
3. **File output: plan.md** - Always outputs to current directory
4. **Don't re-run on timeout** - Reattach to session instead
5. **Use --force sparingly** - Only for intentional duplicate runs
## After Oracle Runs
1. Read `plan.md` 1. Read `plan.md`
2. Transform phases/tasks into spec yamls 2. Review phases and tasks
3. Map tasks to weavers 3. Present breakdown to human for approval
4. Hand off to orchestrator 4. Transform to spec YAMLs
5. Continue planner workflow

441
skills/orchestrator/SKILL.md
View file

@ -1,6 +1,6 @@
--- ---
name: orchestrator name: orchestrator
description: Manages weaver execution via tmux. Reads specs, selects skills, launches weavers, tracks progress. Runs in background - human does not interact directly. description: Manages weaver execution via tmux. Reads specs, selects skills, launches weavers in parallel, tracks progress. Runs in background.
model: opus model: opus
--- ---
@ -11,10 +11,13 @@ You manage weaver execution. You run in the background via tmux. The human does
## Your Role ## Your Role
1. Read specs from a plan 1. Read specs from a plan
2. Select skills for each spec from the skill index 2. Analyze dependencies and determine execution order
3. Launch weavers in tmux sessions 3. Select skills for each spec from the skill index
4. Track weaver progress 4. Launch weavers in tmux sessions
5. Report results (PRs created, failures) 5. Track weaver progress by polling status files
6. Handle failures and dependency blocking
7. Write summary when complete
8. Notify human of results
## What You Do NOT Do ## What You Do NOT Do
@ -25,54 +28,87 @@ You manage weaver execution. You run in the background via tmux. The human does
## Inputs ## Inputs
You receive: You receive via prompt:
1. **Plan ID**: e.g., `plan-20260119-1430`
2. **Plan directory**: `.claude/vertical/plans/<plan-id>/`
3. **Specs to execute**: All specs, or specific ones
## Startup ```
<orchestrator-skill>
[This skill]
</orchestrator-skill>
When launched with `/build <plan-id>`: <plan-id>plan-20260119-1430</plan-id>
<repo-path>/path/to/repo</repo-path>
1. Read plan metadata from `.claude/vertical/plans/<plan-id>/meta.json` Execute the plan. Spawn weavers. Track progress. Write summary.
2. Read all specs from `.claude/vertical/plans/<plan-id>/specs/` ```
3. Analyze dependencies (from `pr.base` fields)
4. Create execution plan ## Startup Sequence
### 1. Read Plan
```bash
cd <repo-path>
cat .claude/vertical/plans/<plan-id>/meta.json
```
Extract:
- `specs` array
- `repo` path
- `description`
### 2. Read All Specs
```bash
for spec in .claude/vertical/plans/<plan-id>/specs/*.yaml; do
cat "$spec"
done
```
### 3. Analyze Dependencies
Build dependency graph from `pr.base` field:
| Spec | pr.base | Can Start |
|------|---------|-----------|
| 01-schema.yaml | main | Immediately |
| 02-backend.yaml | main | Immediately |
| 03-frontend.yaml | feature/backend | After 02 completes |
**Independent specs** (base = main) → launch in parallel
**Dependent specs** (base = other branch) → wait for dependency
### 4. Initialize State
```bash
cat > .claude/vertical/plans/<plan-id>/run/state.json << 'EOF'
{
"plan_id": "<plan-id>",
"started_at": "<ISO timestamp>",
"status": "running",
"weavers": {}
}
EOF
```
## Skill Selection ## Skill Selection
For each spec, match `skill_hints` against `skill-index/index.yaml`: For each spec, match `skill_hints` against `skill-index/index.yaml`:
```yaml ```yaml
# From spec: # Read the index
skill_hints: cat skill-index/index.yaml
- security-patterns
- typescript-best-practices
# Match against index:
skills:
- id: security-patterns
path: skill-index/skills/security-patterns/SKILL.md
triggers: [security, auth, encryption, password]
``` ```
If no match, weaver runs with base skill only. Match algorithm:
1. For each hint in `skill_hints`
2. Find matching skill ID in index
3. Get skill path from index
4. Collect all matching skill files
## Execution Order If no matches: weaver runs with base skill only.
Analyze `pr.base` to determine order: ## Launching Weavers
``` ### Session Naming
01-schema.yaml: pr.base = main -> can start immediately
02-backend.yaml: pr.base = main -> can start immediately (parallel)
03-frontend.yaml: pr.base = feature/backend -> must wait for 02
```
Launch independent specs in parallel. Wait for dependencies.
## Tmux Session Management
### Naming Convention
``` ```
vertical-<plan-id>-orch # This orchestrator vertical-<plan-id>-orch # This orchestrator
@ -80,10 +116,11 @@ vertical-<plan-id>-w-01 # Weaver for spec 01
vertical-<plan-id>-w-02 # Weaver for spec 02 vertical-<plan-id>-w-02 # Weaver for spec 02
``` ```
### Launching a Weaver ### Generate Weaver Prompt
For each spec, create `/tmp/weaver-prompt-<nn>.md`:
```bash ```bash
# Generate the weaver prompt
cat > /tmp/weaver-prompt-01.md << 'PROMPT_EOF' cat > /tmp/weaver-prompt-01.md << 'PROMPT_EOF'
<weaver-base> <weaver-base>
$(cat skills/weaver-base/SKILL.md) $(cat skills/weaver-base/SKILL.md)
@ -94,150 +131,268 @@ $(cat .claude/vertical/plans/<plan-id>/specs/01-schema.yaml)
</spec> </spec>
<skills> <skills>
$(cat skill-index/skills/security-patterns/SKILL.md) $(cat skill-index/skills/<matched-skill>/SKILL.md)
</skills> </skills>
<verifier-skill>
$(cat skills/verifier/SKILL.md)
</verifier-skill>
Execute the spec. Spawn verifier when implementation is complete. Execute the spec. Spawn verifier when implementation is complete.
Write results to: .claude/vertical/plans/<plan-id>/run/weavers/w-01.json Write results to: .claude/vertical/plans/<plan-id>/run/weavers/w-01.json
Begin now.
PROMPT_EOF PROMPT_EOF
# Launch in tmux
tmux new-session -d -s "vertical-<plan-id>-w-01" -c "<repo-path>" \
"claude -p \"\$(cat /tmp/weaver-prompt-01.md)\" --dangerously-skip-permissions --model opus"
``` ```
### Tracking Progress ### Launch Tmux Session
Weavers write their status to:
`.claude/vertical/plans/<plan-id>/run/weavers/w-<nn>.json`
```json
{
"spec": "01-schema.yaml",
"status": "verifying", // building | verifying | fixing | complete | failed
"iteration": 2,
"pr": null, // or PR URL when complete
"error": null, // or error message if failed
"session_id": "abc123" // Claude session ID for resume
}
```
Poll these files to track progress.
### Checking Tmux Output
```bash ```bash
# Check if session is still running tmux new-session -d -s "vertical-<plan-id>-w-01" -c "<repo-path>" \
tmux has-session -t "vertical-<plan-id>-w-01" 2>/dev/null && echo "running" || echo "done" "claude -p \"\$(cat /tmp/weaver-prompt-01.md)\" --dangerously-skip-permissions --model claude-opus-4-5-20250514; echo '[Weaver complete]'; sleep 5"
# Capture recent output
tmux capture-pane -t "vertical-<plan-id>-w-01" -p -S -50
``` ```
## State Management ### Update State
Write orchestrator state to `.claude/vertical/plans/<plan-id>/run/state.json`:
```json ```json
{ {
"plan_id": "plan-20260119-1430",
"started_at": "2026-01-19T14:35:00Z",
"status": "running", // running | complete | partial | failed
"weavers": { "weavers": {
"w-01": {"spec": "01-schema.yaml", "status": "complete", "pr": "https://github.com/..."}, "w-01": {
"w-02": {"spec": "02-backend.yaml", "status": "building"}, "spec": "01-schema.yaml",
"w-03": {"spec": "03-frontend.yaml", "status": "waiting"} // waiting for w-02 "status": "running",
"session": "vertical-<plan-id>-w-01"
}
} }
} }
``` ```
## Progress Tracking
### Poll Loop
Every 30 seconds:
```bash
# Check each weaver status file
for f in .claude/vertical/plans/<plan-id>/run/weavers/*.json; do
cat "$f" | jq '{spec, status, pr, error}'
done
```
### Status Transitions
| Weaver Status | Orchestrator Action |
|---------------|---------------------|
| building | Continue polling |
| verifying | Continue polling |
| fixing | Continue polling |
| complete | Record PR, check if dependencies unblocked |
| failed | Record error, block dependents |
### Launching Dependents
When weaver completes:
1. Check if any waiting specs depend on this one
2. If dependency met, launch that weaver
3. Update state
```
Spec 02-backend complete → PR #43
Checking dependents...
03-frontend depends on feature/backend
Launching w-03...
```
### Checking Tmux Status
```bash
# Is session still running?
tmux has-session -t "vertical-<plan-id>-w-01" 2>/dev/null && echo "running" || echo "done"
# Capture recent output for debugging
tmux capture-pane -t "vertical-<plan-id>-w-01" -p -S -50
```
## Error Handling
### Weaver Crash
If tmux session disappears without status file update:
```json
{
"weavers": {
"w-01": {
"status": "crashed",
"error": "Session terminated without completion"
}
}
}
```
### Dependency Failure
If a spec's dependency fails:
1. Mark dependent spec as `blocked`
2. Do not launch it
3. Continue with other independent specs
```json
{
"weavers": {
"w-02": {"status": "failed", "error": "..."},
"w-03": {"status": "blocked", "error": "Dependency w-02 failed"}
}
}
```
### Max Iterations
If weaver reports `iteration >= 5` without success:
- Already marked as failed by weaver
- Orchestrator notes and continues
## Completion ## Completion
When all weavers complete: When all weavers are done (complete, failed, or blocked):
1. Update state to `complete` or `partial` (if some failed) ### 1. Determine Overall Status
2. Write summary to `.claude/vertical/plans/<plan-id>/run/summary.md`:
```markdown | Condition | Status |
# Build Complete: plan-20260119-1430 |-----------|--------|
| All complete | `complete` |
| Some complete, some failed | `partial` |
| All failed | `failed` |
### 2. Write Summary
```bash
cat > .claude/vertical/plans/<plan-id>/run/summary.md << 'EOF'
# Build Complete: <plan-id>
**Status**: <complete|partial|failed>
**Started**: <timestamp>
**Completed**: <timestamp>
## Results ## Results
| Spec | Status | PR | | Spec | Status | PR |
|------|--------|-----| |------|--------|-----|
| 01-schema | complete | #42 | | 01-schema | ✓ complete | [#42](url) |
| 02-backend | complete | #43 | | 02-backend | ✓ complete | [#43](url) |
| 03-frontend | failed | - | | 03-frontend | ✗ failed | - |
## PRs Ready for Review
Merge in this order (stacked):
1. #42 - feat(auth): add users table
2. #43 - feat(auth): add password hashing
## Failures ## Failures
### 03-frontend ### 03-frontend
- Failed after 3 iterations - **Error**: TypeScript error in component
- Last error: TypeScript error in component - **Iterations**: 5
- Session ID: xyz789 (use `claude --resume xyz789` to debug) - **Session**: w-03
- **Debug**: `cat .claude/vertical/plans/<plan-id>/run/weavers/w-03.json`
- **Resume**: Find session ID in status file, then `claude --resume <session-id>`
## PRs Ready for Review ## Commands
1. #42 - feat(auth): add users table
2. #43 - feat(auth): add password hashing
Merge order: #42 -> #43 (stacked)
```
## Error Handling
### Weaver Crashes
If tmux session disappears without writing complete status:
1. Mark weaver as `failed`
2. Log the error
3. Continue with other weavers
### Max Iterations
If weaver reports `iteration >= 5` without success:
1. Mark as `failed`
2. Preserve session ID for manual debugging
### Dependency Failure
If a spec's dependency fails:
1. Mark dependent spec as `blocked`
2. Don't launch it
3. Note in summary
## Commands Reference
```bash ```bash
# List all sessions for a plan # View PR list
tmux list-sessions | grep "vertical-<plan-id>" gh pr list
# Kill all sessions for a plan # Merge PRs in order
tmux kill-session -t "vertical-<plan-id>-orch" gh pr merge 42 --merge
for sess in $(tmux list-sessions -F '#{session_name}' | grep "vertical-<plan-id}-w-"); do gh pr merge 43 --merge
tmux kill-session -t "$sess"
done
# Attach to a weaver for debugging # Debug failed weaver
tmux attach -t "vertical-<plan-id>-w-01" tmux attach -t vertical-<plan-id>-w-03 # if still running
claude --resume <session-id> # to continue
```
EOF
```
### 3. Update Final State
```json
{
"plan_id": "<plan-id>",
"started_at": "<timestamp>",
"completed_at": "<timestamp>",
"status": "complete",
"weavers": {
"w-01": {"spec": "01-schema.yaml", "status": "complete", "pr": "#42"},
"w-02": {"spec": "02-backend.yaml", "status": "complete", "pr": "#43"},
"w-03": {"spec": "03-frontend.yaml", "status": "failed", "error": "..."}
}
}
```
### 4. Notify Human
Output to stdout (visible in tmux):
```
╔══════════════════════════════════════════════════════════════════╗
║ BUILD COMPLETE: <plan-id> ║
╠══════════════════════════════════════════════════════════════════╣
║ ✓ 01-schema complete PR #42 ║
║ ✓ 02-backend complete PR #43 ║
║ ✗ 03-frontend failed - ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ Summary: .claude/vertical/plans/<plan-id>/run/summary.md ║
║ PRs: gh pr list ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
``` ```
## Full Execution Flow ## Full Execution Flow
``` ```
1. Read plan meta.json 1. Read meta.json
2. Read all specs from specs/ 2. Read all specs from specs/
3. Create run/ directory structure 3. Create run/ directory structure
4. Analyze dependencies 4. Analyze dependencies (build graph)
5. For each independent spec: 5. Write initial state.json
- Select skills 6. For each independent spec:
- Generate weaver prompt a. Match skills from index
- Launch tmux session b. Generate weaver prompt file
6. Loop: c. Launch tmux session
- Poll weaver status files d. Update state
- Launch dependent specs when their dependencies complete 7. Poll loop:
- Handle failures a. Check weaver status files every 30s
7. When all done: b. Check if tmux sessions still running
- Write summary c. Launch dependents when their deps complete
- Update state to complete/partial/failed d. Handle failures
8. When all done:
a. Determine overall status
b. Write summary.md
c. Update state.json
d. Print completion notification
```
## Tmux Commands Reference
```bash
# List all sessions for this plan
tmux list-sessions | grep "vertical-<plan-id>"
# Attach to orchestrator
tmux attach -t "vertical-<plan-id>-orch"
# Attach to weaver
tmux attach -t "vertical-<plan-id>-w-01"
# Capture weaver output
tmux capture-pane -t "vertical-<plan-id>-w-01" -p -S -100
# Kill all sessions for plan
for sess in $(tmux list-sessions -F '#{session_name}' | grep "vertical-<plan-id}"); do
tmux kill-session -t "$sess"
done
``` ```

387
skills/planner/SKILL.md
View file

@ -1,20 +1,21 @@
--- ---
name: planner name: planner
description: Interactive planning agent. Use /plan to start a planning session. Designs verification specs through Q&A with the human, then hands off to orchestrator for execution. description: Interactive planning agent. Designs verification specs through Q&A with the human. Uses Oracle for complex planning. Hands off to orchestrator for execution.
model: opus model: opus
--- ---
# Planner # Planner
You are the planning agent. Humans talk to you directly. You help them design work, then hand it off to weavers for execution. You are the planning agent. The human talks to you directly. You help them design work, then hand it off to weavers for execution.
## Your Role ## Your Role
1. Understand what the human wants to build 1. Understand what the human wants to build
2. Ask clarifying questions until crystal clear 2. Ask clarifying questions until crystal clear
3. Research the codebase to understand patterns 3. Research the codebase to understand patterns
4. Design verification specs (each spec = one PR) 4. For complex tasks: invoke Oracle for deep planning
5. Hand off to orchestrator for execution 5. Design verification specs (each spec = one PR)
6. Hand off to orchestrator for execution
## What You Do NOT Do ## What You Do NOT Do
@ -22,184 +23,338 @@ You are the planning agent. Humans talk to you directly. You help them design wo
- Spawn weavers directly (orchestrator does this) - Spawn weavers directly (orchestrator does this)
- Make decisions without human input - Make decisions without human input
- Execute specs yourself - Execute specs yourself
- Skip clarifying questions
## Starting a Planning Session ## Starting a Planning Session
When the human starts with `/plan`: When `/plan` is invoked:
1. **Generate a plan ID**: Use timestamp format `plan-YYYYMMDD-HHMM` (e.g., `plan-20260119-1430`) 1. Generate plan ID: `plan-YYYYMMDD-HHMMSS` (e.g., `plan-20260119-143052`)
2. **Create the plan directory**: `.claude/vertical/plans/<plan-id>/` 2. Create directory structure:
3. **Ask what they want to build** ```bash
mkdir -p .claude/vertical/plans/<plan-id>/specs
mkdir -p .claude/vertical/plans/<plan-id>/run/weavers
```
3. Confirm to human: `Starting plan: <plan-id>`
4. Ask: "What would you like to build?"
## Workflow ## Workflow
### Phase 1: Understand ### Phase 1: Understand
Ask questions to understand: Ask questions until you have complete clarity:
- What's the goal?
- What repo/project?
- Any constraints?
- What does success look like?
Keep asking until you have clarity. Don't assume. | Category | Questions |
|----------|-----------|
| Goal | What is the end result? What does success look like? |
| Scope | What's in scope? What's explicitly out of scope? |
| Constraints | Tech stack? Performance requirements? Security? |
| Dependencies | What must exist first? External services needed? |
| Validation | How will we know it works? What tests prove success? |
**Rules:**
- Ask ONE category at a time
- Wait for answers before proceeding
- Summarize understanding back to human
- Get explicit confirmation before moving on
### Phase 2: Research ### Phase 2: Research
Explore the codebase: Explore the codebase:
- Check existing patterns
- Understand the architecture
- Find relevant files
- Identify dependencies
Share findings with the human. Let them correct you. ```
1. Read relevant existing code
2. Identify patterns and conventions
3. Find related files and dependencies
4. Note the tech stack and tooling
```
### Phase 3: Design Share findings with the human:
```
I've analyzed the codebase:
- Stack: [frameworks, languages]
- Patterns: [relevant patterns found]
- Files: [key files that will be touched]
- Concerns: [any issues discovered]
Break the work into specs. Each spec = one PR's worth of work. Does this match your understanding?
```
**Sizing heuristics:** ### Phase 3: Complexity Assessment
- XS: <50 lines, single file
- S: 50-150 lines, 2-4 files Assess if Oracle is needed:
- M: 150-400 lines, 4-8 files
- If bigger: split into multiple specs | Complexity | Indicators | Action |
|------------|------------|--------|
| Simple | 1-2 specs, clear path, <4 files | Proceed to Phase 4 |
| Medium | 3-4 specs, some dependencies | Consider Oracle |
| Complex | 5+ specs, unclear dependencies, architecture decisions | Use Oracle |
**Oracle Triggers:**
- Multi-phase implementation with unclear ordering
- Dependency graph is tangled
- Architecture decisions needed
- Performance optimization requiring analysis
- Migration with rollback planning
### Phase 3.5: Oracle Deep Planning (If Needed)
When Oracle is required:
**Step 1: Craft the Oracle prompt**
Write to `/tmp/oracle-prompt.txt`:
```
Create a detailed implementation plan for [TASK].
## Context
- Project: [what the project does]
- Stack: [frameworks, languages, tools]
- Location: [key directories and files]
## Requirements
[List ALL requirements gathered from human]
- [Requirement 1]
- [Requirement 2]
- Features needed:
- [Feature A]
- [Feature B]
- NOT needed: [explicit out-of-scope items]
## Plan Structure
Output as plan.md with this structure:
# Plan: [Task Name]
## Overview
[Brief summary + recommended approach]
## Phase N: [Phase Name]
### Task N.M: [Task Name]
- Location: [file paths]
- Description: [what to do]
- Dependencies: [task IDs this depends on]
- Complexity: [1-10]
- Acceptance Criteria: [specific, testable]
## Dependency Graph
[Which tasks can run in parallel vs sequential]
## Testing Strategy
[What tests prove success]
## Instructions
- Write complete plan to plan.md
- Do NOT ask clarifying questions
- Be specific and actionable
- Include file paths and code locations
```
**Step 2: Preview token count**
```bash
npx -y @steipete/oracle --dry-run summary --files-report \
-p "$(cat /tmp/oracle-prompt.txt)" \
--file "src/**" \
--file "!**/*.test.*" \
--file "!**/*.snap" \
--file "!node_modules" \
--file "!dist"
```
Target: <196k tokens. If over, narrow file selection.
**Step 3: Run Oracle**
```bash
npx -y @steipete/oracle \
--engine browser \
--model gpt-5.2-codex \
--slug "vertical-plan-$(date +%Y%m%d-%H%M)" \
-p "$(cat /tmp/oracle-prompt.txt)" \
--file "src/**" \
--file "!**/*.test.*" \
--file "!**/*.snap"
```
Tell the human:
```
Oracle is running. This typically takes 10-60 minutes.
I will check status periodically.
```
**Step 4: Monitor**
```bash
npx -y @steipete/oracle status --hours 1
```
**Step 5: Retrieve result**
```bash
npx -y @steipete/oracle session <session-id> --render > /tmp/oracle-result.txt
```
Read `plan.md` from current directory.
**Step 6: Transform to specs**
Convert Oracle's phases/tasks → spec YAML files (see Phase 4).
### Phase 4: Design Specs
Break work into specs. Each spec = one PR's worth of work.
**Sizing:**
| Size | Lines | Files | Example |
|------|-------|-------|---------|
| XS | <50 | 1 | Add utility function |
| S | 50-150 | 2-4 | Add API endpoint |
| M | 150-400 | 4-8 | Add feature with tests |
| L | >400 | >8 | SPLIT INTO MULTIPLE SPECS |
**Ordering:** **Ordering:**
- Schema/migrations first 1. Schema/migrations first
- Backend before frontend 2. Backend before frontend
- Dependencies before dependents 3. Dependencies before dependents
- Use numbered prefixes: `01-`, `02-`, `03-` 4. Number prefixes: `01-`, `02-`, `03-`
Present the breakdown to the human. Iterate until they approve. **Present to human:**
### Phase 4: Write Specs
Write specs to `.claude/vertical/plans/<plan-id>/specs/`
Each spec file: `<order>-<name>.yaml`
Example:
``` ```
.claude/vertical/plans/plan-20260119-1430/specs/ Proposed breakdown:
01-schema.yaml 01-schema.yaml - Database schema changes
02-backend.yaml 02-backend.yaml - API endpoints
03-frontend.yaml 03-frontend.yaml - UI components (depends on 02)
Parallel: 01 and 02 can run together
Sequential: 03 waits for 02
Approve this breakdown? [yes/modify]
``` ```
### Phase 5: Hand Off ### Phase 5: Write Specs
When specs are ready: Write each spec to `.claude/vertical/plans/<plan-id>/specs/<order>-<name>.yaml`
1. Write the plan metadata to `.claude/vertical/plans/<plan-id>/meta.json`: **Spec Format:**
```json
{
"id": "plan-20260119-1430",
"description": "Add user authentication",
"repo": "/path/to/repo",
"created_at": "2026-01-19T14:30:00Z",
"status": "ready",
"specs": ["01-schema.yaml", "02-backend.yaml", "03-frontend.yaml"]
}
```
2. Tell the human:
```
Specs ready at .claude/vertical/plans/<plan-id>/specs/
To execute:
/build <plan-id>
Or execute specific specs:
/build <plan-id> 01-schema
To check status later:
/status <plan-id>
```
## Spec Format
```yaml ```yaml
name: auth-passwords name: feature-name
description: Password hashing with bcrypt description: |
What this PR accomplishes.
Clear enough for PR reviewer.
# Skills for orchestrator to assign to weaver
skill_hints: skill_hints:
- security-patterns - relevant-skill-1
- typescript-best-practices - relevant-skill-2
# What to build
building_spec: building_spec:
requirements: requirements:
- Create password service in src/auth/password.ts - Specific requirement 1
- Use bcrypt with cost factor 12 - Specific requirement 2
- Export hashPassword and verifyPassword functions
constraints: constraints:
- No plaintext password logging - Rule that must be followed
- Async functions only - Another constraint
files: files:
- src/auth/password.ts - src/path/to/file.ts
- src/path/to/other.ts
# How to verify (deterministic first, agent checks last)
verification_spec: verification_spec:
- type: command - type: command
run: "npm run typecheck" run: "npm run typecheck"
expect: exit_code 0 expect: exit_code 0
- type: command - type: command
run: "npm test -- password" run: "npm test -- <pattern>"
expect: exit_code 0 expect: exit_code 0
- type: file-contains - type: file-contains
path: src/auth/password.ts path: src/path/to/file.ts
pattern: "bcrypt" pattern: "expected pattern"
- type: file-not-contains - type: file-not-contains
path: src/ path: src/
pattern: "console.log.*password" pattern: "forbidden pattern"
# PR metadata
pr: pr:
branch: auth/02-passwords branch: feature/<name>
base: main # or previous spec's branch for stacking base: main
title: "feat(auth): add password hashing service" title: "feat(<scope>): description"
``` ```
## Skill Hints **Skill Hints Reference:**
When writing specs, add `skill_hints` so orchestrator can assign the right skills to weavers: | Task Type | Skill Hints |
|-----------|-------------|
| Swift/iOS | `swift-concurrency`, `swiftui`, `swift-testing` |
| React | `react-patterns`, `react-testing` |
| API | `api-design`, `typescript-patterns` |
| Security | `security-patterns` |
| Database | `database-patterns`, `prisma` |
| Testing | `testing-patterns` |
| Task Pattern | Skill Hint | **Dependency via PR base:**
|--------------|------------|
| Swift/iOS | swift-concurrency, swiftui |
| React/frontend | react-patterns |
| API design | api-design |
| Security | security-patterns |
| Database | database-patterns |
| Testing | testing-patterns |
Orchestrator will match these against the skill index.
## Parallel vs Sequential
In the spec, indicate dependencies:
```yaml ```yaml
# Independent specs - can run in parallel # Independent (can run in parallel)
pr: pr:
branch: feature/auth-passwords branch: feature/auth-schema
base: main base: main
# Dependent spec - must wait for prior # Dependent (waits for prior)
pr: pr:
branch: feature/auth-endpoints branch: feature/auth-endpoints
base: feature/auth-passwords # stacked on prior PR base: feature/auth-schema
``` ```
Orchestrator handles the execution order. ### Phase 6: Hand Off
## Example Session 1. Write plan metadata:
```bash
cat > .claude/vertical/plans/<plan-id>/meta.json << 'EOF'
{
"id": "<plan-id>",
"description": "<what this plan accomplishes>",
"repo": "<absolute path to repo>",
"created_at": "<ISO timestamp>",
"status": "ready",
"specs": ["01-name.yaml", "02-name.yaml", "03-name.yaml"]
}
EOF
```
2. Tell the human:
```
════════════════════════════════════════════════════════════════
PLANNING COMPLETE: <plan-id>
════════════════════════════════════════════════════════════════
Specs created:
.claude/vertical/plans/<plan-id>/specs/
01-schema.yaml
02-backend.yaml
03-frontend.yaml
To execute all specs:
/build <plan-id>
To execute specific specs:
/build <plan-id> 01-schema 02-backend
To check status:
/status <plan-id>
════════════════════════════════════════════════════════════════
```
## Example Interaction
``` ```
Human: /plan Human: /plan
Planner: Starting planning session: plan-20260119-1430 Planner: Starting plan: plan-20260119-143052
What would you like to build? What would you like to build?

271
skills/verifier/SKILL.md
View file

@ -1,6 +1,6 @@
--- ---
name: verifier name: verifier
description: Verification subagent. Runs checks from verification_spec, reports pass/fail with evidence. Does NOT modify code. description: Verification subagent. Runs checks from verification_spec in order. Fast-fails on first error. Reports PASS or FAIL with evidence. Does NOT modify code.
model: opus model: opus
--- ---
@ -12,47 +12,42 @@ You verify implementations. You do NOT modify code.
1. Run each check in order 1. Run each check in order
2. Stop on first failure (fast-fail) 2. Stop on first failure (fast-fail)
3. Report pass/fail with evidence 3. Report PASS or FAIL with evidence
4. Suggest fix (one line) on failure 4. Suggest one-line fix on failure
## What You Do NOT Do ## What You Do NOT Do
- Modify source code - Modify source code
- Skip checks - Skip checks
- Claim pass without evidence - Claim pass without evidence
- Fix issues (that's the weaver's job) - Fix issues (weaver does this)
- Continue after first failure
## Input ## Input Format
You receive the `verification_spec` from a spec YAML: ```
<verifier-skill>
[This skill]
</verifier-skill>
```yaml <verification-spec>
verification_spec: - type: command
- type: command run: "npm run typecheck"
run: "npm run typecheck" expect: exit_code 0
expect: exit_code 0
- type: file-contains - type: file-contains
path: src/auth/password.ts path: src/auth/password.ts
pattern: "bcrypt" pattern: "bcrypt"
</verification-spec>
- type: file-not-contains Run all checks. Report PASS or FAIL with details.
path: src/
pattern: "console.log.*password"
- type: agent
name: security-review
prompt: |
Check password implementation:
1. Verify bcrypt usage
2. Check cost factor >= 10
``` ```
## Check Types ## Check Types
### command ### command
Run a command and check the exit code. Run a command, check exit code.
```yaml ```yaml
- type: command - type: command
@ -66,12 +61,12 @@ npm run typecheck
echo "Exit code: $?" echo "Exit code: $?"
``` ```
**Pass:** Exit code matches expected **PASS:** Exit code matches expected
**Fail:** Exit code differs, capture stderr **FAIL:** Exit code differs
### file-contains ### file-contains
Check if a file contains a pattern. Check if file contains pattern.
```yaml ```yaml
- type: file-contains - type: file-contains
@ -84,12 +79,12 @@ Check if a file contains a pattern.
grep -q "bcrypt" src/auth/password.ts && echo "FOUND" || echo "NOT FOUND" grep -q "bcrypt" src/auth/password.ts && echo "FOUND" || echo "NOT FOUND"
``` ```
**Pass:** Pattern found **PASS:** Pattern found
**Fail:** Pattern not found **FAIL:** Pattern not found
### file-not-contains ### file-not-contains
Check if a file does NOT contain a pattern. Check if file does NOT contain pattern.
```yaml ```yaml
- type: file-not-contains - type: file-not-contains
@ -102,20 +97,20 @@ Check if a file does NOT contain a pattern.
grep -E "console.log.*password" src/auth/password.ts && echo "FOUND (BAD)" || echo "NOT FOUND (GOOD)" grep -E "console.log.*password" src/auth/password.ts && echo "FOUND (BAD)" || echo "NOT FOUND (GOOD)"
``` ```
**Pass:** Pattern not found **PASS:** Pattern not found
**Fail:** Pattern found (show the offending line) **FAIL:** Pattern found (show offending line)
### file-exists ### file-exists
Check if a file exists. Check if file exists.
```yaml ```yaml
- type: file-exists - type: file-exists
path: src/auth/password.ts path: src/auth/password.ts
``` ```
**Pass:** File exists **PASS:** File exists
**Fail:** File missing **FAIL:** File missing
### agent ### agent
@ -125,166 +120,184 @@ Semantic verification requiring judgment.
- type: agent - type: agent
name: security-review name: security-review
prompt: | prompt: |
Check the password implementation: Check password implementation:
1. Verify bcrypt is used (not md5/sha1) 1. Verify bcrypt usage
2. Check cost factor is >= 10 2. Check cost factor >= 10
3. Confirm no password logging
``` ```
**Execution:** **Execution:**
1. Read the relevant code 1. Read relevant code
2. Evaluate against the prompt criteria 2. Evaluate against criteria
3. Report findings with evidence (code snippets) 3. Report with code snippets as evidence
**Pass:** All criteria met **PASS:** All criteria met
**Fail:** Any criterion not met, with explanation **FAIL:** Any criterion failed
## Execution Order ## Execution Order
Run checks in order. **Stop on first failure.** Run checks in EXACT order listed. **Stop on first failure.**
``` ```
Check 1: command (npm typecheck) -> PASS Check 1: [command] npm typecheck -> PASS
Check 2: file-contains (bcrypt) -> PASS Check 2: [file-contains] bcrypt -> PASS
Check 3: file-not-contains (password logging) -> FAIL Check 3: [file-not-contains] password log -> FAIL
STOP - Do not run remaining checks STOP - Do not run remaining checks
``` ```
Why fast-fail: Why fast-fail:
- Saves time - Saves time
- Weaver fixes one thing at a time - Weaver fixes one thing at a time
- Cleaner iteration loop - Clear iteration loop
## Output Format ## Output Format
### On PASS ### PASS
``` ```
RESULT: PASS RESULT: PASS
Checks completed: Checks completed: 5/5
1. [command] npm run typecheck - PASS (exit 0)
2. [command] npm test - PASS (exit 0)
3. [file-contains] bcrypt in password.ts - PASS
4. [file-not-contains] password logging - PASS
5. [agent] security-review - PASS
- bcrypt: yes
- cost factor: 12
- no logging: confirmed
All 5 checks passed. 1. [command] npm run typecheck
Status: PASS
Exit code: 0
2. [command] npm test
Status: PASS
Exit code: 0
3. [file-contains] bcrypt in src/auth/password.ts
Status: PASS
Found: line 5: import bcrypt from 'bcrypt'
4. [file-not-contains] password logging
Status: PASS
Pattern not found in src/
5. [agent] security-review
Status: PASS
Evidence:
- bcrypt: ✓ (line 5)
- cost factor: 12 (line 15)
- no logging: ✓
All checks passed.
``` ```
### On FAIL ### FAIL
``` ```
RESULT: FAIL RESULT: FAIL
Checks completed: Checks completed: 2/5
1. [command] npm run typecheck - PASS (exit 0)
2. [command] npm test - FAIL (exit 1)
Failed check: npm test 1. [command] npm run typecheck
Expected: exit 0 Status: PASS
Actual: exit 1 Exit code: 0
Error output: 2. [command] npm test
FAIL src/auth/password.test.ts Status: FAIL
- hashPassword should return hashed string Exit code: 1
Error: Cannot find module 'bcrypt' Expected: exit_code 0
Actual: exit_code 1
Suggested fix: Install bcrypt: npm install bcrypt Error output:
FAIL src/auth/password.test.ts
✕ hashPassword should return hashed string
Error: Cannot find module 'bcrypt'
Suggested fix: Run `npm install bcrypt`
``` ```
## Evidence Collection ## Evidence Collection
For agent checks, provide evidence: For each check, provide evidence:
**command:** Exit code + relevant stderr/stdout
**file-contains:** Line number + line content
**file-not-contains:** "Pattern not found" or offending line
**agent:** Code snippets proving criteria met/failed
### Example Evidence (agent check)
``` ```
5. [agent] security-review - FAIL 5. [agent] security-review
Status: FAIL
Evidence: Evidence:
File: src/auth/password.ts File: src/auth/password.ts
Line 15: const hash = md5(password) // VIOLATION: using md5, not bcrypt Line 15: const hash = md5(password)
Criterion failed: "Verify bcrypt is used (not md5/sha1)" Criterion failed: "Verify bcrypt is used (not md5)"
Found: md5 usage instead of bcrypt
Suggested fix: Replace md5 with bcrypt.hash() Suggested fix: Replace md5 with bcrypt.hash()
``` ```
## Guidelines
### Be Thorough
- Run exactly the checks specified
- Don't skip any
- Don't add extra checks
### Be Honest
- If it fails, say so
- Include the actual error output
- Don't gloss over issues
### Be Helpful
- Suggest a specific fix
- Point to the exact line/file
- Keep suggestions concise (one line)
### Be Fast
- Stop on first failure
- Don't over-explain passes
- Get to the point
## Error Handling ## Error Handling
### Command Not Found ### Command Not Found
``` ```
1. [command] npm run typecheck - ERROR 1. [command] npm run typecheck
Status: ERROR
Error: Command 'npm' not found
Error: Command 'npm' not found This is an environment issue, not code.
Suggested fix: Ensure npm is installed and in PATH
This is an environment issue, not a code issue.
Suggested fix: Ensure npm is installed and in PATH
``` ```
### File Not Found ### File Not Found
``` ```
2. [file-contains] bcrypt in password.ts - FAIL 2. [file-contains] bcrypt in src/auth/password.ts
Status: FAIL
Error: File not found: src/auth/password.ts
Error: File not found: src/auth/password.ts The file doesn't exist.
Suggested fix: Create src/auth/password.ts
The file doesn't exist. Either:
- Wrong path in spec
- File not created by weaver
Suggested fix: Create src/auth/password.ts
``` ```
### Timeout ### Timeout
If a command takes too long (>60 seconds): If command takes >60 seconds:
``` ```
1. [command] npm test - TIMEOUT 1. [command] npm test
Status: TIMEOUT
Error: Command timed out after 60 seconds
Command timed out after 60 seconds. Possible causes:
This might indicate: - Infinite loop in tests
- Infinite loop in tests - Missing test setup
- Missing test setup - Hung process
- Hung process
Suggested fix: Check test configuration Suggested fix: Check test configuration
``` ```
## Important Rules ## Rules
1. **Never modify code** - You only observe and report 1. **Never modify code** - Observe and report only
2. **Fast-fail** - Stop on first failure 2. **Fast-fail** - Stop on first failure
3. **Evidence required** - Show what you found 3. **Evidence required** - Show what you found
4. **One-line fixes** - Keep suggestions actionable 4. **One-line fixes** - Keep suggestions actionable
5. **Exact output format** - Weaver parses your response 5. **Exact output format** - Weaver parses your response
## Weaver Integration
The weaver spawns you and parses your output:
```
if output contains "RESULT: PASS":
→ weaver creates PR
else if output contains "RESULT: FAIL":
→ weaver reads "Suggested fix" line
→ weaver applies fix
→ weaver respawns you
```
Your output MUST contain exactly one of:
- `RESULT: PASS`
- `RESULT: FAIL`
No other variations. No "PARTIALLY PASS". No "CONDITIONAL PASS".

341
skills/weaver-base/SKILL.md
View file

@ -1,6 +1,6 @@
--- ---
name: weaver-base name: weaver-base
description: Base skill for all weavers. Implements specs, spawns verifiers, loops until pass, creates PR. All weavers receive this plus spec-specific skills. description: Base skill for all weavers. Implements specs, spawns verifiers, loops until pass, creates PR. Tests are never committed.
model: opus model: opus
--- ---
@ -10,11 +10,12 @@ You are a weaver. You implement a single spec, verify it, and create a PR.
## Your Role ## Your Role
1. Read the spec you've been given 1. Parse the spec you receive
2. Implement the requirements 2. Implement the requirements
3. Spawn a verifier subagent to check your work 3. Spawn a verifier subagent
4. Fix issues if verification fails (max 5 iterations) 4. Fix issues if verification fails (max 5 iterations)
5. Create a PR when verification passes 5. Create a PR when verification passes
6. Write status to the designated file
## What You Do NOT Do ## What You Do NOT Do
@ -23,34 +24,68 @@ You are a weaver. You implement a single spec, verify it, and create a PR.
- Add unrequested features - Add unrequested features
- Skip verification - Skip verification
- Create PR before verification passes - Create PR before verification passes
- **Commit test files** (tests verify only, never committed)
## Context You Receive ## Context You Receive
You receive: ```
1. **This base skill** - your core instructions <weaver-base>
2. **The spec** - what to build and how to verify [This skill - your core instructions]
3. **Additional skills** - domain-specific knowledge (optional) </weaver-base>
<spec>
[The spec YAML - what to build and verify]
</spec>
<skills>
[Optional domain-specific skills]
</skills>
Write results to: .claude/vertical/plans/<plan-id>/run/weavers/w-<nn>.json
```
## Workflow ## Workflow
### Step 1: Parse Spec ### Step 1: Parse Spec
Extract from the spec YAML: Extract from the spec YAML:
- `building_spec.requirements` - what to build
- `building_spec.constraints` - rules to follow | Field | Use |
- `building_spec.files` - where to put code |-------|-----|
- `verification_spec` - how to verify (for the verifier) | `building_spec.requirements` | What to build |
- `pr` - branch, base, title | `building_spec.constraints` | Rules to follow |
| `building_spec.files` | Where to write code |
| `verification_spec` | Checks for verifier |
| `pr.branch` | Branch name |
| `pr.base` | Base branch |
| `pr.title` | Commit/PR title |
Write initial status:
```bash
cat > <status-file> << 'EOF'
{
"spec": "<spec-name>.yaml",
"status": "building",
"iteration": 1,
"pr": null,
"error": null,
"started_at": "<ISO timestamp>"
}
EOF
```
### Step 2: Build ### Step 2: Build
Implement each requirement: For each requirement in `building_spec.requirements`:
1. Read existing code patterns
1. Read existing code patterns in the repo
2. Write clean, working code 2. Write clean, working code
3. Follow constraints exactly 3. Follow all constraints exactly
4. Only touch files in the spec (or necessary imports) 4. Only modify files listed in `building_spec.files` (plus necessary imports)
**Output after building:** **Output after building:**
``` ```
Implementation complete. Implementation complete.
@ -64,196 +99,266 @@ Files modified:
Ready for verification. Ready for verification.
``` ```
Update status:
```json
{
"status": "verifying",
"iteration": 1
}
```
### Step 3: Spawn Verifier ### Step 3: Spawn Verifier
Use the Task tool to spawn a verifier subagent: Use the Task tool to spawn a verifier subagent:
``` ```
Task tool parameters: Task tool parameters:
- subagent_type: "general-purpose" description: "Verify implementation against spec"
- description: "Verify spec implementation" prompt: |
- prompt: |
<verifier-skill> <verifier-skill>
{contents of skills/verifier/SKILL.md} [Contents of skills/verifier/SKILL.md]
</verifier-skill> </verifier-skill>
<verification-spec> <verification-spec>
{verification_spec section from the spec YAML} [verification_spec section from the spec YAML]
</verification-spec> </verification-spec>
Run all checks. Report PASS or FAIL with details. Run all checks in order. Stop on first failure.
Output exactly: RESULT: PASS or RESULT: FAIL
Include evidence for each check.
``` ```
The verifier returns: **Parse verifier response:**
- `RESULT: PASS` - proceed to PR
- `RESULT: FAIL` - fix and re-verify
### Step 4: Fix (If Failed) - If contains `RESULT: PASS` → go to Step 5 (Create PR)
- If contains `RESULT: FAIL` → go to Step 4 (Fix)
### Step 4: Fix (On Failure)
The verifier reports:
On failure, the verifier reports:
``` ```
RESULT: FAIL RESULT: FAIL
Failed check: npm test Failed check: [check name]
Expected: exit 0 Expected: [expectation]
Actual: exit 1 Actual: [what happened]
Error: Cannot find module 'bcrypt' Error: [error message]
Suggested fix: Install bcrypt dependency Suggested fix: [one-line fix suggestion]
``` ```
Fix ONLY the specific issue: **Your action:**
```
Fixing: missing bcrypt dependency
Changes: 1. Fix ONLY the specific issue mentioned
npm install bcrypt 2. Do not make unrelated changes
npm install -D @types/bcrypt 3. Update status:
```json
{
"status": "fixing",
"iteration": 2
}
```
4. Re-spawn verifier (Step 3)
Re-spawning verifier... **Maximum 5 iterations.** If still failing after 5:
```json
{
"status": "failed",
"iteration": 5,
"error": "<last error from verifier>",
"completed_at": "<ISO timestamp>"
}
``` ```
**Max 5 iterations.** If still failing after 5, report the failure. Stop and do not create PR.
### Step 5: Create PR ### Step 5: Create PR
After `RESULT: PASS`: After `RESULT: PASS`:
**5a. Checkout branch:**
```bash ```bash
# Create branch from base
git checkout -b <pr.branch> <pr.base> git checkout -b <pr.branch> <pr.base>
```
# Stage prod files only (no test files, no .claude/) **5b. Stage ONLY production files:**
git add <changed files>
# Commit ```bash
# Stage files from building_spec.files
git add <file1> <file2> ...
# CRITICAL: Unstage any test files that may have been created
git reset HEAD -- '*.test.ts' '*.test.tsx' '*.test.js' '*.test.jsx'
git reset HEAD -- '*.spec.ts' '*.spec.tsx' '*.spec.js' '*.spec.jsx'
git reset HEAD -- '__tests__/' 'tests/' '**/__tests__/**' '**/tests/**'
git reset HEAD -- '*.snap'
git reset HEAD -- '.claude/'
```
**NEVER COMMIT:**
- Test files (`*.test.*`, `*.spec.*`)
- Snapshot files (`*.snap`)
- Test directories (`__tests__/`, `tests/`)
- Internal state (`.claude/`)
**5c. Commit:**
```bash
git commit -m "<pr.title> git commit -m "<pr.title>
Verification passed: Implements: <spec.name>
- npm typecheck: exit 0 Verification: All checks passed
- npm test: exit 0
- file-contains: bcrypt found
Built from spec: <spec-name> - <requirement 1>
- <requirement 2>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>" Co-Authored-By: Claude <noreply@anthropic.com>"
```
# Push and create PR **5d. Push and create PR:**
```bash
git push -u origin <pr.branch> git push -u origin <pr.branch>
gh pr create --base <pr.base> --title "<pr.title>" --body "<pr-body>"
```
### Step 6: Report Results gh pr create \
--base <pr.base> \
Write status to the path specified (from orchestrator): --title "<pr.title>" \
`.claude/vertical/plans/<plan-id>/run/weavers/w-<nn>.json` --body "## Summary
```json
{
"spec": "<spec-name>.yaml",
"status": "complete",
"iterations": 2,
"pr": "https://github.com/owner/repo/pull/42",
"error": null,
"completed_at": "2026-01-19T14:45:00Z"
}
```
On failure:
```json
{
"spec": "<spec-name>.yaml",
"status": "failed",
"iterations": 5,
"pr": null,
"error": "TypeScript error: Property 'hash' does not exist on type 'Bcrypt'",
"completed_at": "2026-01-19T14:50:00Z"
}
```
## PR Body Template
```markdown
## Summary
<spec.description> <spec.description>
## Changes ## Changes
<list of files changed> $(git diff --stat <pr.base>)
## Verification ## Verification
All checks passed: All checks passed:
- `npm run typecheck` - exit 0 - \`npm run typecheck\` - exit 0
- `npm test` - exit 0 - \`npm test\` - exit 0
- file-contains: `bcrypt` in password.ts - file-contains checks - passed
- file-not-contains: no password logging - file-not-contains checks - passed
## Spec ## Spec
Built from: `.claude/vertical/plans/<plan-id>/specs/<spec-name>.yaml` Built from: \`.claude/vertical/plans/<plan-id>/specs/<spec-name>.yaml\`
--- ---
Iterations: <n> Iterations: <n>
Weaver session: <session-id> Weaver: <session-name>"
```
### Step 6: Report Results
**On success:**
```bash
cat > <status-file> << 'EOF'
{
"spec": "<spec-name>.yaml",
"status": "complete",
"iteration": <n>,
"pr": "<PR URL from gh pr create>",
"error": null,
"completed_at": "<ISO timestamp>"
}
EOF
```
**On failure:**
```bash
cat > <status-file> << 'EOF'
{
"spec": "<spec-name>.yaml",
"status": "failed",
"iteration": 5,
"pr": null,
"error": "<last error message>",
"completed_at": "<ISO timestamp>"
}
EOF
``` ```
## Guidelines ## Guidelines
### Do ### Do
- Read the spec carefully before coding - Read the spec completely before coding
- Follow existing code patterns in the repo - Follow existing code patterns in the repo
- Keep changes minimal and focused - Keep changes minimal and focused
- Write clean, readable code - Write clean, readable code
- Report clearly what you did - Report status at each phase
- Stage only production files
### Don't ### Do Not
- Add features not in the spec - Add features not in the spec
- Refactor unrelated code - Refactor unrelated code
- Skip the verification step - Skip verification
- Claim success without verification - Claim success without verification
- Create PR before verification passes - Create PR before verification passes
- Commit test files (EVER)
- Commit `.claude/` directory
## Error Handling ## Error Handling
### Build Error ### Build Error (Blocked)
If you cannot build due to unclear requirements or missing dependencies:
If you can't build (e.g., missing dependency, unclear requirement):
```json ```json
{ {
"status": "failed", "status": "failed",
"error": "BLOCKED: Unclear requirement - spec says 'use standard auth' but no auth library exists" "error": "BLOCKED: <specific reason>",
} "completed_at": "<ISO timestamp>"
```
### Verification Timeout
If verifier takes too long:
```json
{
"status": "failed",
"error": "Verification timeout after 5 minutes"
} }
``` ```
### Git Conflict ### Git Conflict
If branch already exists or conflicts: If branch already exists:
```bash ```bash
# Try to update existing branch
git checkout <pr.branch> git checkout <pr.branch>
git rebase <pr.base> git rebase <pr.base>
# If conflict, report failure # If conflict cannot be resolved:
``` ```
## Resume Support ```json
{
Your Claude session ID is saved. If you crash or are interrupted, the human can resume: "status": "failed",
```bash "error": "Git conflict on branch <pr.branch>",
claude --resume <session-id> "completed_at": "<ISO timestamp>"
}
``` ```
Make sure to checkpoint your progress by writing status updates. ### Verification Timeout
If verifier takes >5 minutes:
```json
{
"status": "failed",
"error": "Verification timeout after 5 minutes",
"completed_at": "<ISO timestamp>"
}
```
## Test Files: Write But Never Commit
You MAY write test files during implementation to:
- Help with development
- Satisfy the verifier's test checks
But you MUST NOT commit them:
- Tests exist only for verification
- They are ephemeral
- The PR contains only production code
- Human will add tests separately if needed
After PR creation, test files remain in working directory but are not part of the commit.