A portable four-phase SDLC for AI coding agents, in any codebase and any domain.
Intent → Plan → Build → Evidence. Parallel scouts before code, an adversarial reviewer after it, and a scored, routed proof at the end.
Coding is fast now. Being wrong is still expensive. An agent that starts by writing code finds the side effects last, and an agent that checks its own work finds few. sdlc-kit puts understanding first and independent proof last, and keeps everything in between small.
It is adapted from Anthropic's AI-Native SDLC playbook and needs no particular harness: the core loop is Markdown plus one shell script. The personal to-do is an optional Node 18+ add-on.
sdlc-kit is an independent project and is not affiliated with Anthropic.
flowchart LR
I["1 Intent"] -->|you approve| P["2 Plan"]
P -. gap found .-> P
P -->|plan approved| B["3 Build"]
B -. FAIL: fix, re-review .-> B
B -->|review PASS| E["4 Evidence"]
E -. plan was wrong, or same failure twice .-> P
E -. code failed .-> B
E -->|every must passes, 95%+ overall| D(["ship"])
E -->|no environment to run it| H(["you decide"])
| Phase | What happens | Goes back when |
|---|---|---|
| 1 Intent | What you asked, what the agent understood, and the risks in it, scored for clarity across six areas. Below 90% the agent explores, reproduces the bug, researches the spec or asks the requester on the ticket, issue or pull request. It reads top-down in plain words — At a glance (What changes, Not included, Your call), What was asked, Why this came up (marked (inferred) when the agent had to infer it, with its evidence), What we will do with its Done when criteria, Risks, Shipping and Questions for you — and keeps the agent's evidence (Key terms, How sure we are, Facts) at the bottom; you approve it by answering "is this what you want?". |
— |
| 2 Plan | Parallel scouts map source of truth, data, logic and user flow into refs/; one PLAN.md holds AS-IS → TO-BE, side effects and the scenarios QA will run. |
the gap check finds holes |
| 3 Build | The smallest complete change, committed, then a separate adversarial reviewer. | the review FAILs: fix it, review again |
| 4 Evidence | Real checks, then every scenario as its persona through the real interface. sdlc.sh score scores and routes it; the agent does not judge. |
the plan was wrong or the same failure came twice → Plan; code failed → Build |
Every way back is capped at three — three review FAILs, three returns to Plan,
three to Build — then the loop stops for you, and only
sdlc.sh approve plan --human resumes it. A scenario that could not run counts
as failed, only you can remove a scenario, and every PASS needs its log.
No runtime: Markdown prompts the agent reads, one Bash script that records and routes, and an optional Node to-do. Full map: docs/architecture.md.
flowchart LR
K["SKILL.md · phases/ · roles/"] --> A["agent (author)"]
A -->|writes| W[".sdlc/work/slug/<br/>intent.md · PLAN.md · review.md · evidence.md"]
SUB["scouts · reviewer · QA<br/>(fresh contexts)"] -->|write| W
W --> S["sdlc.sh<br/>awk parsers + .state"]
HU["you"] -->|approve --human| S
S -->|"next: exit 0/10/20/30<br/>status --json"| A
T["todo/ (Node, optional)"] -->|status slug --json| S
Key decisions (ADRs):
- Approvals bind bytes.
approvestores the sha256 ofintent.mdorPLAN.md(the plan also stores the intent hash it was approved against) and who approved; any edit closes the gate (gate_intent,gate_planinsdlc.sh, ADR 0002). - Reviewed code is shipped code. A review PASS records every bound repo's
HEAD;
scoreandcloserefuse a different or dirty commit (review_heads,validate_commitsinsdlc.sh). - The script routes, not the agent.
sdlc.sh scoresends failures to Plan or Build, or to you, with fixed caps of three (ADR 0003). - One script, four phases. v2 replaced six stages and about 7,000 script
lines with
sdlc.sh(about 600 lines today) (ADR 0001, v2.0.0 changelog). - Independent eyes by contract. Scouts, reviewer and QA are separate role
prompts (
roles/) run as subagents; this is a rule inSKILL.md, not something the script can enforce.
# 1. Install once, and link it where your agent finds skills
git clone https://github.com/cskwork/sdlc-kit ~/sdlc-kit
ln -s ~/sdlc-kit ~/.claude/skills/sdlc-kit # Claude Code; use your harness's skills folder
# 2. Seed a project (or one shipping unit of a monorepo)
cd /path/to/your-project
~/sdlc-kit/sdlc.sh init
$EDITOR .sdlc/config.md # build, test, lint, run, e2e, qaWithout a skills folder, add For SDLC work, read ~/sdlc-kit/SKILL.md and follow it. to the harness's instruction file (AGENTS.md, CLAUDE.md,
GEMINI.md). Then ask for a change in plain words — "add CSV export",
"fix the login redirect" — and the agent runs the loop. sdlc.sh next <slug>
always says what comes next.
.sdlc/work/<slug>/
intent.md what was asked and why, what we will do, risks, and how sure we are
refs/ scout findings and the intent check: source.md data.md logic.md flow.md learnings.md intent-check.md
PLAN.md one page: understanding, AS-IS → TO-BE, side effects, changes, scenarios
review.md reviewer rounds, each ending in VERDICT
evidence.md checks, one result row per scenario, shipping
logs/ raw output behind every PASS and FAIL; scripts/ re-runs each scenario
Closed features move to .sdlc/archive/, with reproducible caches under
logs/ (gradle-home, node_modules, build, … — config.md prune:)
removed. Verified facts move to the memory folder: what the project taught
us that the code cannot tell cheaply, each fact line ending in its basis and
date ([verified: <path> @ <sha> | as-of: <date>], [source: <slug or transcript> | as-of: <date>] or [unconfirmed]). Agents write a page when
they verify such a thing or hit a trap, not only at close. Its INDEX.md
starts with a hand-kept ## Core — the few rules every agent needs, one line
and a link each, at most 25 lines and memory_core_kb — above a generated
list of one line per page (sdlc.sh memory index rebuilds it; close
refreshes it). The index also lints: links to missing files, MOVED TO
stubs, pages without a basis tag, pages over memory_page_kb, and pages over
8,000 bytes without a ## Current picture. Agents read the index first, then
only the pages it names, and grep memory when it has no entry.
close <slug> shipped needs a Memory: line in evidence.md's Shipping: the
pages updated, or none — <why>. Its glossary.md holds the project's terms:
Intent matches each request's terms against it, and Evidence adds the terms a
feature settled.
sdlc.sh dream --check exits 10 once 3 slugs closed (shipped or dropped)
since the last dream, or 14 days passed with at least one close — never with
none — and prints the count, e.g. due: 3/3 closes since <time>.
sdlc.sh dream then prints a brief (roles/dreamer.md) for a fresh agent,
recording nothing: it verifies memory against the code at HEAD and, for what
happened in a session, against the slug's transcripts and logs/; fixes,
supersedes or deletes stale notes; merges duplicates; turns mistakes repeated
across sessions into rules; promotes and demotes ## Core rules; harvests the
closed slugs and keeps memory within budget. Its last step,
sdlc.sh dream --done [--through <time>] [--note <text>], records the run in
.dream-state (the brief names the --through time, so slugs closed after
the brief stay due) and adds a .dream-log.md line if the dreamer wrote none.
A scheduler that fails to start the dreamer loses nothing.
Transcripts are the session record dreaming checks notes against. Set
transcripts: to a shell command, run in the project root with {slug} and
{since} (the last dream's UTC time) replaced, that prints the paths or
path:line hits of that slug's session transcripts or logs, for example
transcripts: grep -rln {slug} ~/agent-sessions. The brief lists at most
transcripts_max hits per slug, as path or path:line only — no transcript
text — and the dreamer greps them rather than reading whole files.
Each kind of knowledge has one home: the memory folder holds project
knowledge; other memory stores you run (an assistant's personal memory, a
notes system) keep their own kind, such as preferences or raw history. List
them in peers: (space- or comma-separated paths, ~ and globs allowed,
relative to the project root). The brief lists each with its file count and
size, never its content; the dreamer greps them for the facts it touches,
never edits them, and reports each duplicate or contradiction as
peer: <peer file> duplicates|contradicts <memory page> — propose: keep in <page>, remove from peer for a person to act on. Nothing is moved in bulk.
Optional config.md keys, with their defaults: transcripts: and peers:
(empty: none),
transcripts_max: 20, memory_core_kb: 2, memory_page_kb: 16,
memory_top_kb: 64 and memory_total_kb: 256 (index warnings),
dream_every: 3 and dream_max_days: 14,
prune: gradle-home .gradle node_modules build .m2 target (empty prunes
nothing) and archive_warn_mb: 50.
.sdlc/config.md is the only project-specific file: the build, test,
lint, run and e2e commands, the qa tool that drives screens or APIs,
an optional qa_runner adapter with its qa_session sign-in command,
human_gates (default intent; add plan to approve every plan yourself — a
plan with a risk flag always asks), the memory folder, and repos (the
repositories a review binds — list them when the project root holds many,
or name them per review with sdlc.sh review <slug> pass --repos "<path> ..." "<note>";
empty means every one under it). .sdlc/ stays
out of git through .git/info/exclude; point memory: at a tracked folder
to share what the team learns.
adapters/e2e/ is one such runner: with qa_runner: e2e, QA writes each
browser or mobile scenario as an e2e
test with a deterministic layer (the evidence, no model) and an optional
agent layer that replays without model calls on later rounds. The kit
vendors e2e's agent guide (Apache-2.0, pinned) so it works offline;
adapters/e2e/update.sh [version] refreshes it.
- Authority is not a gate. Data loss, migrations, public API changes, security-sensitive code, infra changes, push, merge or deploy, and a comment posted on a ticket need your prior words at every setting.
- Independent eyes. Scouts, reviewer and QA run in fresh contexts, never in the one that wrote the work.
- Proof, not claims. No environment means BLOCKED, never PASS. A bug fix needs a test that failed before the fix; a test for new behavior is seen failing once without it.
- Shipped means what was verified. Before any push, merge or deploy,
sdlc.sh check ship <slug>printsGATE OPENonly on a current deliver route, at the commit QA verified, with authority for the target.closerefuses a shipped tree that differs from the verified commit.
Build follows the ponytail approach — the smallest complete change — with the rules written into the phase file, so no other skill is needed.
sdlc.sh status --json lists every feature with its phase, state, score and
route. sdlc.sh next <slug> exits 0 ready, 10 needs a human, 20
blocked, 30 done. The scripts record and report; they never run a model. An
unattended run ships no further than your recorded words allow — a local
commit unless you said more. Windows: run sdlc.sh in Git Bash or WSL.
Keep work across projects in one human-readable ~/.sdlc/todo.md.
A tray app, a TUI and a localhost web page show and update the same file live.
Set SDLC_TODO to use another file.
This optional add-on requires Node 18+; the core loop still needs only bash.
cargo build --release --manifest-path ~/sdlc-kit/todo/app/Cargo.toml # once, for the app (Rust 1.88+)
SDLC_TODO_LANG=ko bash ~/sdlc-kit/todo/app/install-macos.sh # macOS: also add it to ~/Applications
node ~/sdlc-kit/todo/todo.mjs # the app (TUI with its web link if the app is not built)
node ~/sdlc-kit/todo/todo.mjs --ui tui,web # any of tui, web, app
node ~/sdlc-kit/todo/todo.mjs web --open # web page only
node ~/sdlc-kit/todo/todo.mjs add "Fix login ~/code/web https://acme.atlassian.net/browse/WEB-123" --by jira
node ~/sdlc-kit/todo/todo.mjs next # first Open item
node ~/sdlc-kit/todo/todo.mjs take <id> --json # one item a worker owns, with its repliesThe TUI and web page show English or Korean: pass --lang ko (TUI or web) or set SDLC_TODO_LANG=ko; the flag wins, an unknown variable means English, and English is the default.
Press L in the TUI or use the page's language menu to switch until restart or reload.
Statuses say who acts next: your turn (approve intent, approve plan or answer), working now (an agent marked it with working within the last 3 minutes; it shows how long and on what), agent's turn (nobody is on it yet), answered — not picked up yet, not started, blocked — fix needed, or done; the row where agents stop says so.
An item may carry a markdown brief (brief <id> <absolute path> or add --brief PATH, stored as - brief: <path>); the app and page show it like an sdlc work document (At a glance, Questions for you, full text folded) without approval. Write it from todo/brief.md, the one format the app reads (Your call, What changes, AI pick, Phase, Background, Why); leave out a line you cannot fill.
An item may also name the repositories its change touches (repos <id> web-api,admin-api, stored as - repos: web-api, admin-api; no name clears it). The app card, the page row and detail, and the TUI row and detail always show them.
A decision can offer one-click answers (choices <id> "proceed | fix first | hold" [--pick N], stored as - choices: proceed | fix first | hold and - pick: N; up to 6 labels, no labels clears them). On an open item the app card, the page detail (above the reply box) and the TUI (number keys) show one button per label; a click sends that exact label as an ordinary reply, and the picked one comes first, marked Recommended. Open items that need you and share a ticket link sit together under that ticket in the app and page.
An agent can also prefill the answer it recommends (suggest <id> "answer", stored as - suggest: answer; a human reply or no text clears it). The app card, the page reply box and the TUI reply line (r) start with that text, so sending it as-is takes one press; an edit is never overwritten, and a new suggestion replaces only an unedited one. On the app card the "agent is asking" box shows only the brief's Your call and AI pick (the waiting line only when the brief asks nothing), with What changes as one muted line below it.
An agent working on an item right now marks it with todo.mjs working <id> ["step"] (e.g. build, dev QA), repeats it at least every 60 s, and clears it with working <id> --off. The mark lives in todo-working.json beside the to-do file (owner-only), never in todo.md, and expires 3 minutes after its last refresh, so the mark of a worker that died disappears by itself. Every view shows it as "Working now · 12 min · build" with a pulsing green dot; an open item no agent has marked reads "Agent's turn". list --json and the web API carry it as working: {what, since, beat} or null.
When the human has to run something (a VPN login that asks for an OTP, say), the agent records it with run <id> "command" ( - run: command; a reply, resume, done or no text clears it). The app card shows the command and an Open in Terminal button: on macOS with zsh, Terminal opens with the command typed at the prompt but not run, so you read it and press Enter; elsewhere the button copies it. The page and TUI details show the command.
A reply shows "answered — no agent has picked it up yet" until an agent reads it with next or take; after an sdlc wait the item then waits for you again until sdlc.sh moves on. A worker that waits on you outside sdlc (an approval, a ticket answer) records it with wait and drops it with resume. When someone else must answer first (QA, a planner), others <id> "who" marks it "waiting on someone else": it leaves Needs you, next passes it by (take exits 15), and a reply, wait or resume clears it.
All surfaces share one server: the first launch writes its port and token to todo-web.json beside the to-do file (owner-only), and later launches, the app and todo.mjs serve reuse it while it answers.
A pinned item (todo.mjs pin <id>), such as a setting switched with its choices, stays at the top of every app tab and is not counted as needing you. The app (todo/app, macOS and Windows) sits in the menu bar or tray with a count of items that need you, notifies you when one appears, and shows the decisions that need you one at a time, like pages of a book (the page number and arrows sit at the foot; the arrow keys turn the page), with approvals, blocks and questions the agent recommends no answer for first: the question, the situation, what happens once you answer, why, the agent's pick and what each choice does (the phase, repos and full work document fold away under More). On a wide window a decision opens as a two-page spread, what to read on the left and how to answer on the right. You can keep a memo of your own on an item and set the text size and font (Pretendard is built in); both stay in todo-app.json beside the session file and never reach agents. It opens the related tickets, and answers, approves and requests fixes through the same web API, so it never writes todo.md itself; closing the window keeps it in the tray, and Quit stops the server it started. On macOS, todo/app/install-macos.sh [DIR] builds sdlc To-do.app (name: SDLC_TODO_APP_NAME) in ~/Applications; its Info.plist records the kit, node, language and SDLC_TODO, because Finder starts apps without a shell PATH. Run it again after updating the kit or moving node.
Fix by agent (app and page button, TUI f) on a blocked sdlc item records fix requested; the next next or take hands the block to an agent once (exit 0, "fix": true), then it stops the queue again until cleared.
To start an agent right away, put a command in todo-agent.json beside the to-do file, for example {"fix": ["claude", "-p", "follow {kit}/todo/AGENT.md; take {id} and clear its block"]}; {id}, {kit} and {project} are filled in and it runs detached in the project.
To add a language, copy todo/locales/en.mjs to todo/locales/<code>.mjs, translate name and every message, and add its import to locales in todo/i18n.mjs.
The flag, the TUI key, the page menu and the served files follow that registry; the parity test fails on a missing key or {placeholder}, and a missing key shows in English.
Agents and programs use todo.mjs add to attach a project path and ticket link, including Jira links.
The kit makes no Jira API calls.
Every sdlc slug, new or resumed, has a to-do item.
Have a host follow todo/AGENT.md to work proactively.
It includes Claude Code /loop, cron/launchd and Paseo recipes; the kit never runs a model.
next exits 0 workable, 10 waiting for the human, 20 blocked with error text, or 30 nothing to do; it passes items waiting on someone else, which take returns with 15.
Agents must stop at a waiting or blocked first item and never skip to a lower one.
Gate approvals and intent Questions for you surface through sync; the agent stops without adding an explicit wait.
Use wait only for questions sdlc.sh does not track, such as which project or a question outside an sdlc artifact.
Decide in the TUI, web page or chat; replies inform the artifact and never count as approval.
The web page shows intent or plan before approval.
Completed items are checked, struck through and moved to Done, newest first.
Done keeps 30 items; older ones move to todo-archive.md beside the to-do file.
History records local time as YYYY-MM-DD HH:MM, with the author and action.
You can edit the file directly; saving an old editor buffer can overwrite newer changes.
Web access stays on 127.0.0.1, with Host/Origin checks and a per-run token held in memory by the server and page.
The kit never writes the token to disk; the browser may keep the opened URL in history. The token dies when the process exits.
Approve binds the bytes shown through sdlc.sh approve <intent|plan> <slug> --human "<words>" --sha <hex>; changed bytes are refused.
Same-user programs are outside this boundary, as with --human.
v2 is a new contract. Your records stay where they are.
- Features started under v0 show as
legacyinsdlc.sh status. Finish them with the old kit (git -C ~/sdlc-kit checkout v0.27.0) or close them:sdlc.sh close <slug> dropped "<reason>". lazymodekeeps working: 0–1 →human_gates: intent plan, 2–3 →intent, 4 → none. Writehuman_gates:to choose explicitly; a word other thanintentorplanmeans both..sdlc/memory/is the default memory folder, as in v0; aknowledge:line still names the folder, andsdlc.shreports a default folder that is not it.init.sh→sdlc.sh init;gates/status.sh --jsonandtools/auto.sh next→sdlc.sh status --jsonandsdlc.sh next(same exit codes). spec.md, summary.md, delivery.md, qa-guide.md, map.md, harvest, verification receipts, handoff, tripwire, refcheck and the QA-mode switch are gone: their jobs live in PLAN.md, evidence.md,sdlc.sh closeand configqa:.
Why: v2.0.0 changelog.
bash tests/selftest.shWord budgets for every prompt, the gate and routing rules, and one real
feature driven through all four phases on a small CLI fixture. CI runs it on
Linux, macOS and Windows. When node is on PATH, the selftest also runs the
to-do suites (node --test tests/todo*.test.mjs).
Last observed (2026-11-02, bash tests/selftest.sh in CI on main, macos-latest):
133 selftest checks passed and the to-do suites reported 192 tests, 192
passed, 0 failed, 0 skipped. Linux also passed 133 checks; Windows passed 131 and
skipped 2 that need POSIX signals or permissions
(run 40613802450).
The full selftest takes several minutes because it creates many throwaway git
repositories.
- Independence of the reviewer and QA depends on the harness supporting subagents or fresh sessions; the script records verdicts but cannot prove who wrote them.
--humanis a recorded claim, not authentication: any program running as the same user can call it.- Parsing is awk over Markdown tables, so artifacts must keep the template's headings and columns; the script reports a malformed row instead of guessing.
- The selftest is slow (it builds many throwaway git repositories), and there is no shellcheck step in CI.
MIT