flowchart TD
DEV([👤 Developer
Terminal + tmux]) -->|"/plan_to_build
'add feature X'"| PTB
DEV -->|"/build specs/plan.md"| BUILD
subgraph PLAN_PHASE ["📋 Plan Creation (plan_to_build.md)"]
PTB["Analyze codebase directly
no subagents — understand patterns"] --> DESIGN
DESIGN["Design solution
task type · complexity
architecture decisions"] --> TEAM_COMP
TEAM_COMP["Compose team
from agents/team/*.md
builder count · workstream split"] --> WRITE_SPEC
WRITE_SPEC["Write exhaustive spec
to specs/*.md
task IDs · deps · full descriptions"] --> SELF_VERIFY
SELF_VERIFY["Self-verify before save
count sections = 7
task descriptions ≥50 words"] --> HOOK_STOP
HOOK_STOP["Stop hook fires
validate_new_file.py
validate_file_contains.py
— 7 required sections?
— file created this session?"]
end
HOOK_STOP -->|"PASS → allow stop
FAIL → block + fix"| REPORT1
REPORT1["Plan report
+ EXECUTION DIRECTIVE
FORBIDDEN: direct implementation"]
REPORT1 -->|"'/build specs/plan.md'"| BUILD
subgraph BUILD_PHASE ["⚙️ Build Orchestration (build.md)"]
BUILD["Team Lead
reads spec
disallowed: Write, Edit, NotebookEdit"] --> TEAM_CREATE
TEAM_CREATE["TeamCreate
team named after plan"] --> TASK_GRAPH
TASK_GRAPH["TaskCreate × N
one per plan task
+ addBlockedBy deps
+ auto spec-updater task (blocked by all)"] --> DEPLOY
subgraph DEPLOY ["🚀 Parallel Deploy (run_in_background: true)"]
B1["builder-1
standing orders:
TaskList → claim → execute
→ complete → SendMessage → loop"]
B2["builder-2
(if plan has parallel work)
same standing orders"]
VAL_A["validator
standing orders:
claim validator tasks
run commands → PASS/FAIL
create fix tasks on FAIL"]
SPEC_U["spec-updater
standing orders:
runs last (blocked by all)
re-runs commands
writes Build Evidence to spec"]
end
DEPLOY --> MONITOR
MONITOR["Team Lead monitors
receives SendMessage reports
does NOT poll — event-driven"]
MONITOR -->|"Validation FAILED
fix_cycle < 2"| FIX_TASK
FIX_TASK["validator creates fix task
role: builder
+ re-validation task blocked by fix"]
FIX_TASK -->|"builders auto-discover"| DEPLOY
MONITOR -->|"FAILED max cycles"| ESCALATE
ESCALATE["Escalate to user
collect failure details
do NOT create more fix tasks"]
end
BUILD_PHASE --> SHUTDOWN
SHUTDOWN["SendMessage shutdown_request
to all agents
wait shutdown_response
TeamDelete"] --> BUILD_REPORT
BUILD_REPORT["Build Report
agents · tasks · validation results
fix cycles · spec evidence
files changed"]
subgraph HOOKS ["🪝 Hooks — Python via uv run (settings.json)"]
H1["PreToolUse
pre_tool_use.py — dangerous cmd guard
enforce_team_lead.py — write guard
require_team_create.py — team guard
validate_plan_format.py — 7 sections
validate_task_description.py — exhaustive desc
merge_gate.py — review gate
enforce_branch_discipline.py"]
H2["PostToolUse
post_tool_use.py
enforce_test_evidence.py
validate_bug_report.py
validate_pr_test_evidence.py"]
H3["Stop
stop.py → validate_new_file.py
+ validate_file_contains.py
blocks if spec incomplete"]
H4["SessionStart / SessionEnd
session_start.py — load CONTEXT.md
session_end.py — state persist
subagent_start/stop — audit log"]
end
style DEV fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a
style PLAN_PHASE fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a
style PTB fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a
style DESIGN fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a
style TEAM_COMP fill:#edf2fb,stroke:#2a5fa5,color:#7a7468
style WRITE_SPEC fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a
style SELF_VERIFY fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a
style HOOK_STOP fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a
style REPORT1 fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a
style BUILD_PHASE fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a
style BUILD fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a
style TEAM_CREATE fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a
style TASK_GRAPH fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a
style DEPLOY fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a
style B1 fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a
style B2 fill:#f0ecfc,stroke:#6450b4,color:#7a7468
style VAL_A fill:#f0ecfc,stroke:#2d7a4f,color:#1a1a1a
style SPEC_U fill:#f0ecfc,stroke:#2d7a4f,color:#7a7468
style MONITOR fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a
style FIX_TASK fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a
style ESCALATE fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a
style SHUTDOWN fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a
style BUILD_REPORT fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a
style HOOKS fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a
style H1 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468
style H2 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468
style H3 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468
style H4 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468