Act V · Apply it
AI Factory · Framework
One policy, one profile, one kit
aisdlc) that runs gates by exit code, enforces ratchets and keeps the evidence.- G0Intakeissue + requirement
- G1Planchange record, real issue
- G2Rednew tests fail
- G3Verifysuite · lint · ratchets
- G3Pre-PRpipeline · docs
- G4Mergeheavy CI · review
- G5Releasedeploy · smoke
Ten principles, each earned by an incident
Policy first
One document prevails over every agent file, rule and prompt — and names no tool.
Spec before code, red before green
No code without a change record; no implementation before a failing test.
Mechanical over aspirational
A rule that can be a command is a gate. Prose is for what cannot be checked.
Machines check machines, humans check meaning
Agents' claims are never evidence; reviewers check what gates cannot.
Gate integrity
Final commit, full suite, live references. Light green is not green.
Ratchet, do not big-bang
Debt shrinks monotonically; quality floors only rise.
Serialize scarce, publish in-flight
Heavy CI, shared files and merges go one at a time; work lives on the remote.
Least context, least privilege
A small always-loaded card; rules and skills on demand; narrow tokens.
Traceable end to end
Issue → change record → tests → commits → PR → release evidence.
Size the process, measure its tax
Pick an adoption level; track the share of work spent on the process itself.
Components
Agents are interchangeable and read the policy; they run the stages through the kit; the kit calls your existing tools and writes the evidence. Only the profile knows the project.
Stages and hard gates
| Stage | Gate | Done when | In Notaire |
|---|---|---|---|
intake | G0 ready | Issue exists, states the problem, links its requirement | Issue template + Use Case |
plan | G1 specified | Change record complete; the issue resolves live | validate-sdlc-plan.sh |
red | G2 tests fail first | New tests exist and fail (expect = "fail") | mvn / vitest single test, path-scoped |
pre-push | G3 verified | Suite, lint, ratchets, process checks | preflight.sh (+ ratchet, skills lint) |
pre-pr | G3 verified | Full local pipeline, docs updated | run_pipeline.sh |
merge | G4 reviewed | Full CI on the final commit, review resolved | check-heavy-ci.sh, archive hygiene |
release | G5 shipped | Deployed, smoke-tested, issue closed | version coherence, health smoke |
A gate is name · stage · run · expect · required · timeout · paths. expect = "fail" makes the red step of TDD mechanical; paths skips slow gates when nothing they cover changed.
Notaire's profile, the first adopter
[project]
name = "notaire"
policy = "CONSTITUTION.md"
level = 3 # fleet: Owner + Foreman + Workers
[[gates]]
name = "OpenSpec plans conform (live issue check)"
stage = "plan"
run = "bash workspace/sdlc/validate-sdlc-plan.sh"
[[gates]]
name = "backend test fails"
stage = "red"
run = "mvn -q -B test -pl backend-api -Dtest={test}"
expect = "fail"
paths = ["backend-api/src/test/**"]
[[gates]]
name = "heavy CI green on the PR head"
stage = "merge"
run = "bash workspace/sdlc/check-heavy-ci.sh {pr}"
[[ratchets]]
name = "ArchUnit hexagon baseline (R1–R6)"
kind = "baseline"
file = "backend-api/src/test/resources/architecture/hexagon-baseline.txt"$ cp -R framework/ai-sdlc your-repo/tools/ai-sdlc$ python3 tools/ai-sdlc/bin/aisdlc init --name shop --level 2 created .aisdlc/agents/foreman.md … created aisdlc.toml$ python3 tools/ai-sdlc/bin/aisdlc doctor WARN gate red/new test fails is a placeholder WARN gate pre-push/test suite is a placeholderdoctor: shop · level 2 · 7 gates in 3 stages · 0 ratchets · 4 roles — OK (0 errors, 4 warnings)$ python3 tools/ai-sdlc/bin/aisdlc gate pre-push --base HEAD~1 PASS commit subjects (exit 0, 0.1s) TODO test suite — placeholder; configure its command in the profilestage pre-push: PASSED
The kit
| Command | Does |
|---|---|
aisdlc init --name N --level L | Scaffold policy, agent card, AGENTS.md, profile, role agents |
aisdlc doctor | Validate the profile; warn on placeholders and what the level lacks |
aisdlc gate <stage> | Run the stage's gates by exit code; path-scoped; one ledger record |
aisdlc ratchet | Baselines may not grow against the base; floors must hold |
aisdlc change new | check | Built-in change records with a live issue check |
aisdlc skills · budget · commits · tdd | Catalog lint, context budget, commit subjects, tests with code |
aisdlc report · cost | Gate pass rates and durations; token cost per model and agent |
Exit 0 passed, 1 a gate or check failed, 2 usage or configuration error. Nothing an agent says counts.
Adoption levels
Guided · One developer with an assistant
Policy, card, profile, change records, plan and pre-push gates
Gated · Small team; agents write most code
Red gates, ratchets, CI mirror, evidence report
Fleet · Parallel agents, one human Owner
Roles with a merge rule, merge gate, serialization, claims, continuous publication
Autonomous · Bounded autonomous runs
Release gate, cost prices, harness-owned ledgers, measured autonomy
The learning loop
What is not proven yet
- Adoption by a second real project and team (the kit is validated on Notaire, a fresh repository and four example stacks).
- Whether near-zero human review time is safe for high-risk changes; the merge rule may need a risk threshold.
- Real cost per merged change:
aisdlc costexists, but no harness records tokens yet.