A reusable AI product-development operating system for solo builders working with Claude, Notion, and Git. It turns feature development into a deterministic 13-stage state machine with living documents, hard quality gates, and full resumability — any session can die at any moment and the next one picks up exactly where it left off.
Version: v1.4.1 · consumed by projects as a version-pinned git submodule · improve a rule once here, every project inherits it at its next pin bump.
┌─────────────────────────────┐
│ YOU (three gates) │
│ direction · design · final │
└──────▲───────────────▲───────┘
terminal│ │Telegram plugin
│ │(extensions/, opt-in)
┌──────────────────────────────┴───────────────┴──────────────────────────────┐
│ WORKFLOW ORCHESTRATOR │
│ state-machine executor · stage routing · model routing · │
│ gate enforcement · loop ceilings · resume-from-state │
│ AI/orchestrator.md │
└───────┬───────────────────────┬───────────────────────┬─────────────────────┘
│ reads config │ reads/writes state │ loads process
┌───────▼────────────┐ ┌───────▼────────────┐ ┌───────▼─────────────────────┐
│ PROJECT MANIFEST │ │ LIVING BRD │ │ Workflows/ (15 stages) │
│ project repo │ │ Notion, per feature│ │ Skills/ (16 roles) │
│ │ │ properties = state │ │ Standards/ Templates/ │
│ SCREEN CONTRACT │ │ S01–S16 = content │ │ Checklists/ Prompts/ │
│ project repo │ │ │ │ Playbooks/ │
└────────────────────┘ └─────────▲──────────┘ └─────────────────────────────┘
│ MCP
External services: Notion (MCP) · GitHub (gh) ·
browser (prototype review) · your project repo
The orchestrator is the only component that advances state. Everything it needs to resume lives in the three sources of truth — never in the session. Full wiring: Architecture/integration-map.md.
- Single source of truth — every fact has exactly one home (manifest, BRD, or Screen Contract). Workflows consume, never re-ask, never duplicate.
- AI executes, human directs — Claude runs all 13 stages; you decide at three gates. See Decision Boundaries.
- Stage-based development — features move through a gated state machine with checklisted exits, not freeform prompting.
- Resume from state, not session — machine position is reconstructed from Notion properties + the S16 Decision Log. Kill any session, nothing is lost.
- Modular & versioned — single-responsibility modules, semver-tagged, consumed as a pinned submodule. Projects upgrade deliberately.
- Plugin-based integrations — the core never depends on extensions; adapters (Telegram today) talk only to the orchestrator.
1. Three sources of truth, nothing duplicated.
| Artifact | Truth for | Lives in |
|---|---|---|
project-manifest.yaml |
project configuration (stack, design, integrations, git) | project repo |
| Living BRD (one Notion page per feature) | requirements, decisions, progress, history | Notion database |
Screen Contract (screens/) |
design → development traceability per screen | project repo |
Workflows consume these; they never re-ask what an artifact already answers. Feature knowledge evolves in the BRD mid-work — findings land the moment they're discovered, never in side documents.
2. A gated state machine runs every feature.
Ready → Analysis → Planning → Design → Design Review → Dev Planning →
Implementation → QA → Tech Review → PR → Human Review → Merged → Released
🚦 Direction Gate 🚦 Design Gate 🚦 Final Gate
Claude runs every stage; you only act at the three gates (approve scope → review the running prototype → approve the PR). Everything else — research with citations, edge-case enumeration, prototype, code, evidence-based QA, 7-dimension review — executes and logs itself to the BRD. Loops are bounded (no infinite revision), approvals go stale if content changes after them, and nothing ships with unmet acceptance criteria.
3. State lives in Notion, never in the session. Every transition writes the BRD's Decision Log (S16) and its status properties. Kill any session; the next one reconstructs everything from Notion alone.
What actually happens when you say "pick up the ready BRD" — every stage, every session:
User request
↓
Workflow Orchestrator (AI/orchestrator.md)
↓ manifest gate: load + validate project-manifest.yaml
↓ load Living BRD — properties give exact machine position
↓ check Screen Contract (blocks Dev Planning if mappings incomplete)
↓ load the stage's Workflow + Skill + referenced Standards, at routed model tier
↓
Execute current stage → findings written to the BRD as discovered
↓
Run exit validation (Checklists/) — fail → bounded retry with corrective constraint
↓
Update BRD: status + S16 transition entry (atomic)
↓
Next stage — or stop and present a decision package if a human gate is pending
The orchestrator loads only what the current stage needs; nothing global sits in context. Contract details: AI/orchestrator.md · Architecture/workflow-state-machine.md.
Layer 1 · CORE ENGINE orchestrator, state machines, model routing
fires transitions, enforces gates — the only writer of machine state
↓
Layer 2 · PROJECT CONFIGURATION project-manifest.yaml, project-overrides.md
tells the engine what this project is; validated before any work
↓
Layer 3 · DEVELOPMENT SYSTEM Living BRD, Screen Contract, Workflows,
Skills, Standards — what each stage does and to what quality bar
↓
Layer 4 · COMMUNICATION extensions/ — Telegram v1 (Slack/Discord
possible later); adapters that relay gates, never advance state
↓
Layer 5 · EXTERNAL SERVICES Notion (MCP), GitHub (gh), browser
where state, code, and review surfaces physically live
Lower layers never depend on higher ones; extensions and services are replaceable without touching the engine.
- Requirements: Claude Code (or Claude with MCP), Node 18+,
ghCLI authenticated, Notion MCP connected. - Create the BRD database — one database for all projects. Say to Claude:
(Exact properties, views, and page scaffold: Documentation/notion-setup.md.)
Create the BRD database per toolkit Documentation/notion-setup.md. - Optional — Telegram gate approvals on your phone: create a bot via @BotFather,
export TELEGRAM_BOT_TOKEN=…in your shell profile. Wiring happens per-project at onboarding. (extensions/telegram/README.md)
Register a new project per toolkit project-onboarding step 0:
name <Name>, code <XX>, <product type>, stage <idea|mvp|...>, stack <headline>.
Identity + BRD-ID code reserved in Notion. A registered project with no repo yet is a valid resting state.
# new project (or cd into an existing repo — onboarding detects the stack)
npx create-next-app@latest <project> --typescript --tailwind --eslint --app --src-dir --use-npm --yes
cd <project>
git submodule add https://github.com/Chheng64/Dev-toolkit.git toolkit
cd toolkit && git fetch --tags && git checkout v1.4.1 && cd ..
git add -A && git commit -m "chore: pin toolkit v1.4.1"Run toolkit/Workflows/project-onboarding.md for this project.
~5 minutes: detects your stack (asks only what it can't detect) → validates every integration and URL → seeds known screens with stable Screen IDs → generates project-manifest.yaml + context/ (AI session-bootstrap summaries) → asks about Telegram once (yes / no / later — "later" is never re-asked) → commits. Then push and protect main (PR-only + CI).
In the BRDs database: new page → [BRD-<XX>-001] <feature> → write a one-paragraph problem seed in S01 → set Project + Priority → tick Ready. Keep the first feature small — you're proving the loop.
Act per toolkit/AI/orchestrator.md. Pick up the ready BRD for <project>.
The machine runs. You'll be stopped at the Direction Gate first: a summary of the analyzed scope with a recommendation and cut-line. Reply approve / request-changes / reject. Same pattern at Design (review the prototype at localhost:8765) and Final (review the PR).
| Situation | Say |
|---|---|
| Continue work | Act per toolkit/AI/orchestrator.md. Resume <BRD-ID> (or just "pick up where we left off") |
| New feature idea | Create the BRD page, tick Ready, then "pick up the ready BRD" |
| Check state | Status of all in-flight BRDs (or /status in Telegram) |
| Something's broken | Run toolkit/Workflows/debug.md on: <symptom> |
| Production emergency | Run the hotfix playbook: <symptom> |
| Project config changed | toolkit onboard --update (targeted re-onboarding) |
| Enable/change Telegram | toolkit configure communication |
Up to 3 BRDs run in parallel (one branch + one PR each); the orchestrator serializes anything whose planned code areas overlap.
End-to-end, from nothing to shipped — the three 🚦 marks are the only places you act:
Register → Onboard → Create BRD (Ready)
↓
Analysis ──🚦 Direction Gate (approve scope)
↓
Planning → Design → Design Review ──🚦 Design Gate (review running prototype)
↓
Dev Planning → Implementation → QA → Tech Review → PR
↓
Human Review ──🚦 Final Gate (approve PR)
↓
Merged → Released
Approvals are scoped to what you saw — if gated content changes afterward, the approval is revoked and the gate re-raises.
- Requirements need falsifiable acceptance criteria; QA never marks pass without evidence.
- Every feature designs its non-happy paths (error/empty/loading/offline/interrupted) — happy-path-only work bounces.
- UI composes from the design system first; ad-hoc styling is a defect, gaps become Extension Notes.
- Silent deviation from plan is forbidden — deviate and log, or route back.
- Reviews cover 7 dimensions (correctness, standards, security, performance, accessibility, DS conformance, plan conformance) on every diff.
- Screens carry stable SCR-IDs from onboarding through QA (
C_CONTRACTblocks implementation on incomplete mappings). - Approvals are scoped to what you saw — content changes revoke them automatically.
- Model routing: heavyweight reasoning (Opus-tier) only where wrong judgment cascades — Planning, UX, Dev Planning, Review; mechanical work rides cheap tiers. (AI/model-routing.md)
| Human decides | AI executes |
|---|---|
| Business direction & scope (Direction Gate) | Analysis, research with citations |
| Design approval (Design Gate) | Planning, UX, prototype, implementation |
| Merge approval (Final Gate) | QA with evidence, 7-dimension review, documentation |
If a decision isn't at a gate, it's Claude's — bounded by the permission matrix and logged in S16. (Architecture/permission-matrix.md)
Dependencies point down toward Architecture/ — it depends on nothing; Playbooks/ alone composes across modules.
| Dir | Purpose | Depends on | Edit when | Claude loads |
|---|---|---|---|---|
| Architecture/ | Contracts: BRD schema (S01–S16), permission matrix, state machines, manifest, screen contract, stack profiles, versioning | nothing (foundation) | contract changes — semver-gated | always (via orchestrator) |
| AI/ | Runtime: orchestrator, entry contract, BRD update protocol, model routing, MCP setup | Architecture | runtime behavior changes | every session entry |
| Workflows/ | 15 stage procedures (analysis → release, debug, onboarding) | Architecture | a stage's procedure improves | per stage |
| Skills/ | 16 roles with decision boundaries | Architecture | a role's judgment improves | per stage |
| Standards/ | 17 tech standards (TS, React, Next.js, Tailwind v4, a11y, security, …) | Architecture | a quality bar changes | as referenced by stage |
| Templates/ | 15 artifact formats (requirements, PR, bug report, mappings, …) | Architecture | an artifact format changes | when producing that artifact |
| Checklists/ | 12 machine-checkable gates | Architecture | an exit criterion changes | at stage exit |
| Prompts/ | 11 invocation patterns | Architecture | an invocation improves | when you invoke one |
| Playbooks/ | full-feature · parallel-brds · hotfix · design-only | everything (composition layer) | a composed flow changes | when a playbook is invoked |
| extensions/ | Opt-in adapters (Telegram v1) | orchestrator contract only | adding/changing an adapter | only if enabled in manifest |
| Documentation/ | Module index · Onboarding · Notion setup · Changelog | — | docs drift | on demand |
New functionality goes where its single responsibility says: process → Workflows/, judgment → Skills/, quality bar → Standards/, contract → Architecture/, adapter → extensions/.
Deep-dive order for a new reader: this file → integration-map → workflow-state-machine → module-index.
The core toolkit never depends on an extension. Extensions are adapters — they relay gate events out and approvals in through the Workflow Orchestrator, which remains the only component that advances state. Telegram ships today (extensions/telegram/README.md); Slack, Discord, email, or custom MCP adapters follow the same contract: outbox events at the four triggers, inbox events applied under normal gate rules, nothing else.
Register → Onboard → Configure → Develop features (BRD loop, above)
→ Maintain (debug/hotfix playbooks) → Upgrade toolkit pin → Archive
A project can rest at any point — registered-without-repo is valid, and an archived project's history stays fully readable in Notion.
cd <project>/toolkit && git fetch --tags && git checkout <new-tag> && cd ..
git add toolkit && git commit -m "chore: upgrade toolkit <old> -> <new>"Projects upgrade independently and deliberately — never track main. Major bumps: read the changelog migration notes first. In-flight BRDs finish under their pinned version unless you decide otherwise. Semver rules: Architecture/versioning.md.
Lessons flow back: retro findings → edit the module here → changelog entry → tag → projects inherit at next bump. Weak prompt/workflow output? Use Prompts/prompt-improvement.md — evidence-based, fix the instruction class, re-run the failing case as proof.
- Single responsibility per file; composition only in
Playbooks/. - Dependencies point down toward
Architecture/only. - Zero project-specific business logic — project deviations live in each project's
project-overrides.md. - No secrets, ever (tokens are env-only).
- This README stays an entry point — overviews link out; detail lives in modules.