Repo Architecture, Explained
What's actually inside aidlc-workflows (v2.8.1), and why it's split the way it is.
In plain English: Almost all of the "smarts" live in one shared place (
core/). Each tool (Claude Code, Cursor, etc.) just gets a tiny translator folder on top, so the same brain works everywhere without being rewritten seven times.
Top-Level Layout
| Folder | What's in it |
|---|---|
core/ |
The engine — stages, agents, hooks, knowledge, sensors, scopes. Shared by every tool. |
harness/<name>/ |
A thin adapter per tool — one manifest + a few tool-specific files. |
plugins/<name>/ |
Optional add-ons — extra stages, sensors, agents. |
scripts/ |
Build tooling. package.ts is the compiler. |
docs/ |
guide/ · harness-engineering/ · reference/ |
tests/ |
Smoke, unit, integration, e2e — one matrix per harness. |
dist/, dist-release/ |
Generated, git-ignored — appear only after a build. |
Why Split This Way
flowchart LR
C["core/agents/architect.md"] -->|manifest.ts maps it| H1["dist/claude/.claude/agents/"]
C -->|same file| H2["dist/cursor/.cursor/agents/"]
C -->|same file| H3["dist/kiro/.kiro/agents/"]
One core/ file, mapped into every tool's own folder shape by that tool's manifest.ts (a small "translation map" — it says "this core file goes here in Cursor's format, there in Claude's format"). Rebuilding must produce byte-identical output (run the build twice, get the exact same files, down to the last byte) — enforced by bun scripts/package.ts --check in CI (an automatic check that runs on every change, so nobody can accidentally break that guarantee). Most of the intelligence lives in the ~30% of the repo that's shared; harness/<name>/ is just a thin costume on top.
The Methodology, in Numbers
A quick glossary before the table: a Phase is one of the 5 big chapters of building something (Ideation, Inception, Construction, Operation, plus Initialization). Each phase is broken into Stages — smaller, checkable steps, like "write the requirements" or "design the database." An Agent is one of the AI's specialist personas (e.g., "architect," "tester"). A Workflow profile is a preset — how deep or how skipped-over the process is for a given job (a tiny bug fix doesn't need all 33 stages; a new product probably does). An Audit event is one line in the permanent record — "this stage started," "this file was approved," and so on.
| Phases | 5 |
| Stages | 33 |
| Agents | 14 (11 experts + 2 reviewers + 1 composer) |
| Workflow profiles | 11 |
| Audit events | 95 |
Human approval gates sit at every stage boundary — meaning after each of those 33 steps, the AI stops and waits for you. You always get exactly two buttons: Request Changes (send it back to redo this step) or Continue to Next Stage (looks good, move on).
How We Verified This
Read straight from the source — manifest.ts files, core/templates/onboarding.md, the per-harness guides under docs/guide/harnesses/ — not from marketing copy.
Continue to: How We Use This Repo or What It Installs, Tool by Tool