docs/features/payment-retries/ · state: BUILD, next: aisdlc-implement
Agents write code. aisdlc runs the process.
EARS specs, six evidence gates, and an evidence log your agent cannot fake. Local-first, any harness. Your laptop is the sandbox.
npx aisdlc-cli init- discover
- spec
- plan
- tasks
- build
- verify
- accept
- release
- operate
“All tests pass” is a sentence. A run is a file.
The agent wrote the sentence it predicted you wanted. Nothing ran. aisdlc only counts a run it recorded itself: command, exit code, output hash, timestamp, appended to an evidence log in your repo, reviewable in a PR.
And when a requirement quietly drifts to match the code at 2 a.m., aisdlc turns the edit into a delta, invalidates the stale approvals, and moves the state backwards on purpose. The agent tried to approve its own plan? Refused.
# example session: the author tried to approve their own plan; the tool said no $ npx aisdlc-cli verify payment-retries -- npm test … 41 passed (41), exit 0, 8.2s evidence/20260906T154412-full.json recorded sha256:e3f1…9b7c · label: full $ npx aisdlc-cli approve G1 payment-retries refused: you authored plan.md segregation of duties: approver ≠ author $ npx aisdlc-cli next payment-retries --json state: VERIFY · blocking: acceptance.md unsigned next skill: aisdlc-verify · owner: agent
Six gates between an idea and production. Each one is a file check.
The agent runs npx aisdlc-cli next, gets the state and the skill to load, does the work, and runs it again.
Humans are asked for exactly two things: signatures and approvals. Skipped lanes show as skipped, and they
are not failures.
- plan.md is real, not a stub
- approval bound to the plan's hash
- approver ≠ author
- spec passes EARS validation
- §5 signed by a human
- every requirement traced to a task
- secrets scan clean
- full test run recorded as evidence
- latest run exit code 0
- every scenario has an evidence file
- every row passes
- independent human sign-off
- rollout has concrete rollback steps
- release owner approval on rollout hash
- budgets: latency, errors, cost
- named kill switch
- runbook with symptoms → actions
Eight invariants, written to every project the CLI touches.
They land in docs/constitution.md and in your agent's instructions file. You add your own below the
line; the tool enforces these eight so you never have to remember them.
Code is generated output. Intent changes go through a delta, never a quiet edit.
No evidence, no progress. The CLI refuses to move the state forward.
Segregation of duties is enforced by the tool, and agents cannot approve at all.
Approved-by lines are human-signed. Underscores mean unsigned.
Every test run is captured with command, exit code and output hash. Claims without artifacts do not count.
aisdlc next derives the truth from files. Same files, same answer, any machine, any model.
Eight pattern families, placeholder-aware, blocks G3.
Infra down means IMPLEMENTED-NOT-VERIFIED, not PASS.
20 skills. One entry point per scenario.
Plain Markdown in the open Agent Skills format, read identically by Claude Code, Codex, Cursor, Gemini, Copilot, Windsurf and OpenCode. Browse the full index →
cross-cutting
| aisdlc-delta | Handle any change of intent after the spec is signed - new requirement, changed behaviour, removed scope, a bug that reveals the spec was wrong. |
| aisdlc-flow | The aisdlc router. |
| aisdlc-grill | Relentless, structured interview that turns a vague plan, idea, spec, or design into shared understanding before anything is built. |
| aisdlc-handoff | Compact the current session into a handoff document so a fresh session, a different agent, or a human can continue without loss. |
discover
| aisdlc-brainstorm | The front door for any new request. |
| aisdlc-brownfield | Safe entry into an existing codebase. |
| aisdlc-discover | Double-Diamond discovery intake for a new idea or feature in the standard or regulated lane. |
specify
| aisdlc-spec | Write or repair an EARS specification (spec.md) that passes `npx aisdlc-cli check spec`. |
plan
| aisdlc-plan | Produce plan.md with architecture, explicit decisions (alternatives, ponytail ladder rung), seams, work breakdown as tracer bullets, risks, and a Traceability table that maps every spec requirement to tasks, then request human G1 approval. |
tasks
| aisdlc-tasks | Generate or repair tasks.md from the plan's work breakdown so every task is a small tracer bullet, traceable to a requirement, checkable, and ordered by its blocking edges, then pass gate G2 (artifact consistency). |
build
| aisdlc-craft | Bridge to code-craft, the line-level clean-code discipline (the ladder before writing, smell→fix on touched lines only, dead-code deletion with dynamic-reference checks, honest types, rule of three). |
| aisdlc-debug | Disciplined, evidence-backed debugging loop for bugs, flaky tests, performance regressions and "it works on my machine". |
| aisdlc-implement | Implement one task at a time, test-first at the agreed seam, with the ponytail ladder applied, recorded evidence, and zero scope creep. |
verify
| aisdlc-quality | Bridge to code-quality-tools, the runner guide for lint, autofix, dead-code, complexity and security CLIs on JS/TS and Python (fallow, eslint, biome, knip, tsc, ruff, mypy, vulture, bandit, semgrep - which tool, in what order, what mutates vs detects). |
| aisdlc-verify | Run the merge-safety gate G3 honestly - full test run recorded as evidence, secrets scan, and kind-specific verification (visual diff, a11y, integration smoke, dry-run, evals). |
accept
| aisdlc-review | Act as an independent reviewer for the acceptance gate G4 - a two-axis review (Spec axis: does the diff faithfully implement every scenario? Standards axis: does it follow the repo's taste, smell baseline and ponytail minimalism?) that audits evidence against each spec scenario, fills acceptance.md, files findings, and prepares the human sign-off. |
release
| aisdlc-release | Prepare and gate a release - rollout.md with strategy and rollback (G5, human approved), then guardrails.yaml and runbook.md for runtime budgets, kill switch and on-call actions (G6). |
| aisdlc-retro | Close the loop on a finished feature, incident, or sprint so the process gets better instead of just longer. |
Short answers.
Is this a SaaS? Do I need an account?
No. It is a folder of SKILL.md files and a zero-dependency Node CLI. Everything runs on your machine against your own repo. There is no server, no telemetry and nothing to sign up for.
Which model or subscription do I need?
Whatever you already have. The skills are plain Markdown in the open Agent Skills format, so Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot, Windsurf, OpenCode and local open-weight models all read them the same way.
What is the difference between the skills and the CLI?
Skills tell the agent how to behave at each stage. The CLI is the referee: it validates EARS specs, derives the state, runs the six gates, records evidence and holds the approval chain. Skills without the CLI still work; the CLI is what makes “done” mean something.
How is this different from Spec Kit or BMAD?
Those give you excellent templates and advice. aisdlc adds enforcement: approvals bound to artifact hashes that go stale when you edit, an evidence log that cannot be faked by prose, and segregation of duties the agent cannot bypass.
Can I use it on an existing codebase?
Yes, that is what aisdlc-brownfield is for: baseline, characterization tests and named seams before any delta-only change is allowed.
Is it free?
MIT licensed. Fork it, vendor it, ship it inside your company. If you find it useful, star the repo and file issues.
Install it in the repo you are working on right now.
Then tell your agent: use aisdlc-brainstorm, I want to build …. It picks the lane, asks only what
changes the outcome, and hands you a spec you can sign.
npx aisdlc-cli init