harivansh-afk/claude-code-vertical
1
0
Fork 0
mirror of https://github.com/harivansh-afk/claude-code-vertical.git synced 2026-04-16 13:04:07 +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

441
skills/orchestrator/SKILL.md
View file

@ -1,6 +1,6 @@
---
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
---
@ -11,10 +11,13 @@ You manage weaver execution. You run in the background via tmux. The human does
## Your Role
1. Read specs from a plan
2. Select skills for each spec from the skill index
3. Launch weavers in tmux sessions
4. Track weaver progress
5. Report results (PRs created, failures)
2. Analyze dependencies and determine execution order
3. Select skills for each spec from the skill index
4. Launch weavers in tmux sessions
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
@ -25,54 +28,87 @@ You manage weaver execution. You run in the background via tmux. The human does
## Inputs
You receive:
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
You receive via prompt:
## 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`
2. Read all specs from `.claude/vertical/plans/<plan-id>/specs/`
3. Analyze dependencies (from `pr.base` fields)
4. Create execution plan
Execute the plan. Spawn weavers. Track progress. Write summary.
```
## 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
For each spec, match `skill_hints` against `skill-index/index.yaml`:
```yaml
# From spec:
skill_hints:
- 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]
# Read the index
cat skill-index/index.yaml
```
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
```
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
### Session Naming
```
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
```
### Launching a Weaver
### Generate Weaver Prompt
For each spec, create `/tmp/weaver-prompt-<nn>.md`:
```bash
# Generate the weaver prompt
cat > /tmp/weaver-prompt-01.md << 'PROMPT_EOF'
<weaver-base>
$(cat skills/weaver-base/SKILL.md)
@ -94,150 +131,268 @@ $(cat .claude/vertical/plans/<plan-id>/specs/01-schema.yaml)
</spec>
<skills>
$(cat skill-index/skills/security-patterns/SKILL.md)
$(cat skill-index/skills/<matched-skill>/SKILL.md)
</skills>
<verifier-skill>
$(cat skills/verifier/SKILL.md)
</verifier-skill>
Execute the spec. Spawn verifier when implementation is complete.
Write results to: .claude/vertical/plans/<plan-id>/run/weavers/w-01.json
Begin now.
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
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
### Launch Tmux Session
```bash
# Check if session is still running
tmux has-session -t "vertical-<plan-id>-w-01" 2>/dev/null && echo "running" || echo "done"
# Capture recent output
tmux capture-pane -t "vertical-<plan-id>-w-01" -p -S -50
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 claude-opus-4-5-20250514; echo '[Weaver complete]'; sleep 5"
```
## State Management
Write orchestrator state to `.claude/vertical/plans/<plan-id>/run/state.json`:
### Update State
```json
{
"plan_id": "plan-20260119-1430",
"started_at": "2026-01-19T14:35:00Z",
"status": "running", // running | complete | partial | failed
"weavers": {
"w-01": {"spec": "01-schema.yaml", "status": "complete", "pr": "https://github.com/..."},
"w-02": {"spec": "02-backend.yaml", "status": "building"},
"w-03": {"spec": "03-frontend.yaml", "status": "waiting"} // waiting for w-02
"w-01": {
"spec": "01-schema.yaml",
"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
When all weavers complete:
When all weavers are done (complete, failed, or blocked):
1. Update state to `complete` or `partial` (if some failed)
2. Write summary to `.claude/vertical/plans/<plan-id>/run/summary.md`:
### 1. Determine Overall Status
```markdown
# Build Complete: plan-20260119-1430
| Condition | Status |
|-----------|--------|
| 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
| Spec | Status | PR |
|------|--------|-----|
| 01-schema | complete | #42 |
| 02-backend | complete | #43 |
| 03-frontend | failed | - |
| 01-schema | ✓ complete | [#42](url) |
| 02-backend | ✓ complete | [#43](url) |
| 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
### 03-frontend
- Failed after 3 iterations
- Last error: TypeScript error in component
- Session ID: xyz789 (use `claude --resume xyz789` to debug)
- **Error**: TypeScript error in component
- **Iterations**: 5
- **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
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
## Commands
```bash
# List all sessions for a plan
tmux list-sessions | grep "vertical-<plan-id>"
# View PR list
gh pr list
# Kill all sessions for a plan
tmux kill-session -t "vertical-<plan-id>-orch"
for sess in $(tmux list-sessions -F '#{session_name}' | grep "vertical-<plan-id}-w-"); do
tmux kill-session -t "$sess"
done
# Merge PRs in order
gh pr merge 42 --merge
gh pr merge 43 --merge
# Attach to a weaver for debugging
tmux attach -t "vertical-<plan-id>-w-01"
# Debug failed weaver
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
```
1. Read plan meta.json
1. Read meta.json
2. Read all specs from specs/
3. Create run/ directory structure
4. Analyze dependencies
5. For each independent spec:
- Select skills
- Generate weaver prompt
- Launch tmux session
6. Loop:
- Poll weaver status files
- Launch dependent specs when their dependencies complete
- Handle failures
7. When all done:
- Write summary
- Update state to complete/partial/failed
4. Analyze dependencies (build graph)
5. Write initial state.json
6. For each independent spec:
a. Match skills from index
b. Generate weaver prompt file
c. Launch tmux session
d. Update state
7. Poll loop:
a. Check weaver status files every 30s
b. Check if tmux sessions still running
c. Launch dependents when their deps complete
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
```