agent-sdlc¶

A software development lifecycle shipped as agent config for Claude Code and Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.

Why it exists¶

A coding agent writes the code and the tests for it. Tests written next to the code tend to agree with it, bugs included, so a green suite can tell you nothing.

On a mature, well-shaped suite, 57% of real bug-class mutants survived (measured 2026-09-10, see Rules → Testing).
Agents drift from the ask: extra files, extra abstractions, 400-line diffs for a 40-line change.
Intent gets lost. Design notes land in the tree, the ticket says one thing, the code another.
Destructive git slips through: reset --hard, add -A across branches, force-push over someone's work.

agent-sdlc makes a hook or the gate check each of these, so the agent doesn't have to remember them.

What it solves, and how¶

Problem	Mechanism	Where
Tests that pass but assert nothing	Mutation testing on the diff; a surviving mutant blocks the commit	Gate
Tests shaped to the code, not the ask	Adversary review that sees intent and tests, never the code	Techniques
Scope creep	40-line limit without a ticket reference; one ticket, one branch, one PR	SDLC
Lost intent	Intent lives in the tracker; new `.md` files in the tree are blocked	Rules → Tickets
Model code drifting from its spec	Model V&V: spec issue, `MS-n` citations, golden hashes, a blind pass	Techniques
Vague or inconsistent names	Vocabulary dictionary, naming molds, WordNet synonym check	Techniques
Destructive git	A PreToolUse hook that blocks `reset --hard`, `add -A`, force-push, and checkout or switch off the default branch in the primary worktree	Hooks and tools
AI tells in commits and PRs	Commit-message check for banned words and attribution trailers	CLI
Leaked identity or internal names	`no-leaks` scan on the staged diff and message	CLI

How the pieces fit¶

 ticket (model:* label)
        |
        v
 /kata -> branch -> red slice test -> implement <--------------+
                                         |                      |
                                         v                      |
                                    git commit                  |
                                    |        |                  |
                        pre-commit  |        |  commit-msg      |
                                    v        v                  |
                        +---------------+  +------------------+ |
                        | mutation-gate |  | commit-msg       | |
                        +---------------+  | diff-discipline  | |
                          |         |      | no-leaks         | |
                    pass  |         |      +------------------+ |
                          v         +---- survivor -------------+
                  adversary report
                          |
                          v
                  PR, Closes #N -> LGTM -> squash merge

Rules (rules/) say how to work. They sync into a repo as .claude/rules/*.md and an AGENTS.md block.
Commands (commands/) are slash commands that run a workflow: /kata, /done, /grill.
Skills (skills/) are playbooks the agent loads on demand: /diagnose, /sol-budget, /verify-generated-diff.
Hooks run without asking: a preflight check at session start, the git guardrail and host-exec before every Bash call, the gate at Stop.
The gate (mutation_gate/, the mutation-gate CLI) is the only part that can say no.

One example¶

A function and two tests that look fine:

def is_adult(age):
    return age >= 18


def test_adult():
    assert is_adult(30)


def test_child():
    assert not is_adult(5)

The gate mutates the changed lines and reruns the tests. Real output:

mutation-gate: 1 changed source file(s)
  [1/2] age.py:2:11 age >= 18 => age > 18
  [2/2] age.py:2:18 18 => 19

BLOCKED: 2 mutant(s) survived with no waiver.
  age.py:2:11:operator:age >= 18 => age > 18
  age.py:2:18:literal:18 => 19

Both tests pass whether the boundary is 18 or 19. Nothing pins it.
The fix is a test from the requirement, not from the code:

def test_eighteen_is_the_first_adult_age():
    assert is_adult(18)
    assert not is_adult(17)

mutation-gate: pass

Install¶

claude plugin marketplace add PavelGuzenfeld/agent-sdlc
claude plugin install agent-sdlc@agent-sdlc
git clone https://github.com/PavelGuzenfeld/agent-sdlc
cd agent-sdlc
./install.sh --deps

The plugin is the Claude Code install. install.sh covers Codex (--target codex) and dependencies, never ~/.claude.
--deps installs git gh jq docker python3 ast-grep pytest pre-commit and the gate; --deps=say adds the Kokoro voice stack.
A second run changes nothing.
Only the gate: pip install agent-sdlc (module mutation_gate, console script mutation-gate). Add agent-sdlc[vocabulary] for the WordNet check.

Details: Getting started and Hooks and tools.

Where to go next¶

You want to	Read
Install and see it work	Getting started
Go from install to a merged PR, step by step	Usage
Understand the ideas	Techniques
Follow the ticket-to-merge flow	SDLC
Get unblocked by the gate	Gate
Look up a flag or subcommand	CLI
Configure a repo	Config
Pick a slash command	Commands
See what runs on its own	Hooks and tools
Look up a term	Glossary