🏗️ architecture · SDLC state machine

How GreatCTO orchestrates your SDLC.

A deterministic state machine. Every box maps to a real agent on GitHub. Human gates highlighted. Memory feedback loop visible. No prompt-wrapper magic.

View the diagram ↓ Agents on GitHub ↗
The state machine

From npx great-cto init to a shipped feature.

One linear pipeline with two parallel fan-outs (implementation + review) and two human gates. Memory feedback loop runs on the right. Total wall-time for a small feature: ~45 min. Total LLM cost: ~$0.80–$2.40 depending on archetype.

0 · init 1 · plan 2 · gate 3 · decompose 4 · implement 5 · review 6 · gate 7 · deploy 8 · operate $ npx great-cto init scaffold + detect stack archetype detect 15 signals → 25 archetypes $0.00 · local architect ARCH.md · ADR · cost est. $0.15–0.40 · Sonnet ⚐ GATE: PLAN human decision #1 — approve scope ~30 s · 1 click pm decompose · beads tasks · Gantt $0.05–0.15 · Sonnet senior-dev #1 TDD · claim task · ship $0.20–0.60 senior-dev #2 parallel · isolated worktree $0.20–0.60 senior-dev #N scales with task count $0.20–0.60 qa-engineer type · lint · test · cov $0.10–0.30 security-officer OWASP · CVE · secrets $0.15–0.40 performance-eng SLO · k6 · flame graph $0.10–0.30 archetype-reviewer PCI / HIPAA / GDPR / … $0.20–0.50 code-reviewer 12-angle review $0.20–0.50 ⚐ GATE: SHIP human decision #2 — approve deploy ~30 s · 1 click devops CI · canary · health checks $0.05–0.15 l3-support on-call · P0 triage · postmortem $0.10–0.40 / incident continuous-learner extract pattern → lessons.md $0.05 / session-end memory L1–L4 project · brain · global local files · git-backed injects prior lessons into next iteration totals · small feature ~45 min wall-clock $0.80 – $2.40 LLM cost 2 clicks your involvement 34 agents on call
Stages · 8 of them

What runs at each stage.

STAGE 0–1 · INIT + PLAN

Local-first scaffold

Stack detection runs in your shell (no LLM call). The architect drafts ARCH.md + ADR + cost estimate. You see a diff before anyone touches code.

~$0.15–0.40 · 2 min
STAGE 2 · GATE: PLAN

Human decision #1

Approve scope, reject, or edit. Without your green light, no implementation starts. The gate writes to a local file — auditable, version-controlled.

~30 s · 1 click
STAGE 3–4 · IMPLEMENT

Parallel senior-dev pool

PM decomposes into beads tasks with explicit dependencies. Independent tasks run in parallel worktrees. Each senior-dev follows TDD (RED → GREEN → IMPROVE).

~$0.60–1.80 · 10–25 min
STAGE 5 · REVIEW

Specialist fan-out

5 reviewers run concurrently: QA, security, performance, archetype-specific (PCI / HIPAA / GDPR / EU AI Act / OWASP LLM), and 12-angle code review.

~$0.75–2.00 · 5–8 min
STAGE 6 · GATE: SHIP

Human decision #2

You see the full review verdict — APPROVED / BLOCKED / FAIL with rationale per reviewer. Approve to deploy, or send back with comments. Same audit trail.

~30 s · 1 click
STAGE 7 · DEPLOY

devops + canary

CI runs your existing pipeline. devops watches health checks, error rates, p99 latency. Auto-rollback if SLO burn rate spikes within 10 min.

~$0.05–0.15 · 3–5 min
STAGE 8 · OPERATE

l3-support on call

Monitors Grafana / Sentry / Cloudflare. P0 → immediate triage + postmortem. P1/P2 → beads task with severity tag. All decisions logged.

~$0.10–0.40 / incident
FEEDBACK LOOP

continuous-learner

At session end (or every 50 commits), extracts repeatable patterns. Promotes to ~/.great_cto/decisions.md after ≥3 occurrences. Injects into agent Step 0 next iteration.

~$0.05 / session-end
Memory architecture · L1–L4

The 4 memory layers.

Memory is the difference between each iteration starting from zero and each iteration starting from everything you've already learned. Stored locally, git-backed, never sent to a vendor.

L1 · project memory per-repo
Lessons specific to this repo's stack, patterns, gotchas. Lives in .great_cto/lessons.md. Survives session restarts because it's plain markdown in git.
path: .great_cto/lessons.md scope: this repo
L2 · codebase patterns in-repo
Architecture conventions, naming, style. Auto-detected from existing files. Examples: "uses Drizzle, not Prisma" or "all handlers use Result<T,E>".
extractor: architect agent ttl: until refactor
L3 · your brain cross-project
Decisions you've made across every project. "Always use Sigstore for npm publishes." "Never deploy on Fridays." Lives in ~/.great_cto/decisions.md. Yours, not the agent's.
path: ~/.great_cto/decisions.md scope: all your projects
L4 · global patterns opt-in
Anonymized rollup of patterns that have helped ≥ 3 teams. Gated until WAU ≥ 100 to avoid noise. Opt-in, off by default. Powers cross-project memory.
status: collecting · not yet published opt-in: --telemetry=patterns

Retrieval: at agent Step 0, the kernel grep-ranks lessons by pattern_hash similarity to the current task, picks top-N (default 3), and injects them into the agent's context. Latency: ~50ms. Misses are logged and analyzed weekly.

Reading the code

Every node in the diagram is a file on GitHub.

No black boxes. Click any node above to jump to its source. Want the full agent index?

All 34 agents on GitHub ↗ ARCHITECTURE.md ↗ ← Back to home