prompts iteration

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

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...]
---
@ -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
```
## What Happens
## What You Do
1. Read plan from `.claude/vertical/plans/<plan-id>/`
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/`
When `/build <plan-id>` is invoked:
## Execution Flow
```
/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:
### Step 1: Validate Plan Exists
```bash
# List tmux sessions
tmux list-sessions | grep vertical
if [ ! -f ".claude/vertical/plans/<plan-id>/meta.json" ]; then
echo "Error: Plan not found: <plan-id>"
echo "Run /status to see available plans"
exit 1
fi
```
# Attach to orchestrator
tmux attach -t vertical-plan-20260119-1430-orch
### Step 2: Generate Orchestrator Prompt
# Attach to a weaver
tmux attach -t vertical-plan-20260119-1430-w-01
```bash
cat > /tmp/orch-prompt-<plan-id>.md << 'PROMPT_EOF'
<orchestrator-skill>
$(cat skills/orchestrator/SKILL.md)
</orchestrator-skill>
# Capture weaver output
tmux capture-pane -t vertical-plan-20260119-1430-w-01 -p
<plan-id><plan-id></plan-id>
<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
When complete, find results at:
- `.claude/vertical/plans/<plan-id>/run/state.json` - Overall status
- `.claude/vertical/plans/<plan-id>/run/summary.md` - Human-readable summary
- `.claude/vertical/plans/<plan-id>/run/weavers/w-*.json` - Per-weaver status
| File | Contents |
|------|----------|
| `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
If a weaver fails, you can resume its session:
### Resume a Failed Weaver
```bash
# 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>
```
Or attach to the tmux session if still running:
### Attach to Running Weaver
```bash
tmux attach -t vertical-<plan-id>-w-01
@ -101,20 +155,40 @@ tmux attach -t vertical-<plan-id>-w-01
## Killing a Build
```bash
# Kill all sessions for a plan
# Source helpers
source lib/tmux.sh
vertical_kill_plan plan-20260119-1430
# Kill all sessions for this plan
vertical_kill_plan <plan-id>
# Or kill everything
vertical_kill_all
```
## Implementation Notes
## What Happens Behind the Scenes
This command:
1. Loads orchestrator skill
2. Generates orchestrator prompt with plan context
3. Spawns tmux session with `claude -p "<prompt>" --dangerously-skip-permissions --model opus`
4. Returns immediately (orchestrator runs in background)
The orchestrator handles everything from there.
```
/build plan-20260119-1430
├─→ Create orchestrator prompt
├─→ Launch tmux: vertical-plan-20260119-1430-orch
│ │
│ ├─→ 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
```

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]
---
@ -14,52 +14,100 @@ Start a planning session. You become the planner agent.
/plan Add user authentication with OAuth
```
## What Happens
## What You Do
1. Load the planner skill from `skills/planner/SKILL.md`
2. Generate a plan ID: `plan-YYYYMMDD-HHMMSS`
3. Create plan directory: `.claude/vertical/plans/<plan-id>/`
4. Enter interactive planning mode
When `/plan` is invoked:
## Planning Flow
### Step 1: Load Planner Skill
1. **Understand** - Ask questions until the task is crystal clear
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>`
Read and internalize `skills/planner/SKILL.md`.
## 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
03-frontend.yaml
════════════════════════════════════════════════════════════════
PLANNING COMPLETE: <plan-id>
════════════════════════════════════════════════════════════════
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
When specs are ready:
When specs are ready, the human runs:
```
Specs ready. To execute:
/build <plan-id>
To execute specific specs:
/build <plan-id> 01-schema 02-backend
To check status:
/status <plan-id>
/build <plan-id>
```
This launches the orchestrator in tmux, which spawns weavers.
## Multiple Planning Sessions
You can run multiple planning sessions in parallel:
Run multiple planning sessions in parallel:
```
# Terminal 1
@ -67,16 +115,27 @@ You can run multiple planning sessions in parallel:
# Terminal 2
/plan Add payment processing
# Terminal 3
/plan Add notification system
```
Each gets its own plan-id and can be built independently.
## Resuming
## Resuming a Planning Session
Planning sessions are Claude Code sessions. Resume with:
```
```bash
claude --resume <session-id>
```
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?

View file

@ -10,13 +10,49 @@ Check the status of plans and weavers.
## Usage
```
/status # All plans
/status plan-20260119-1430 # Specific plan
/status # All plans
/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 ===
@ -31,7 +67,67 @@ vertical-plan-20260119-1445-orch
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 ===
@ -44,70 +140,74 @@ Started: 2026-01-19T14:35:00Z
03-frontend.yaml
=== Weavers ===
w-01 complete 01-schema.yaml https://github.com/owner/repo/pull/42
w-02 verifying 02-backend.yaml -
w-03 waiting 03-frontend.yaml -
w-01 complete 01-schema.yaml https://github.com/...
w-02 verifying 02-backend.yaml -
w-03 waiting 03-frontend.yaml -
=== Tmux Sessions ===
vertical-plan-20260119-1430-orch running
vertical-plan-20260119-1430-w-01 done
vertical-plan-20260119-1430-w-02 running
vertical-plan-20260119-1430-orch
vertical-plan-20260119-1430-w-01
vertical-plan-20260119-1430-w-02
```
## Weaver Statuses
## Weaver Status Reference
| Status | Meaning |
|--------|---------|
| waiting | Waiting for dependency |
| waiting | Waiting for dependency to complete |
| building | Implementing the spec |
| verifying | Running verification checks |
| fixing | Fixing verification failures |
| complete | PR created successfully |
| failed | Failed after max iterations |
| 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
# Source helpers
source lib/tmux.sh
# List all sessions
# List all vertical sessions
vertical_list_sessions
# Status for all plans
# Full status
vertical_status
# Weaver status for a plan
vertical_weaver_status plan-20260119-1430
# Capture recent output from a weaver
# Capture recent output
vertical_capture_output vertical-plan-20260119-1430-w-01
# Attach to a session
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.