Skip to main content

agent-sdlc

CI

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

Docs: https://pavelguzenfeld.com/agent-sdlc/

Why

A coding agent writes the code and the tests for it, and tests written next to the code tend to agree with it, bugs included. We planted small realistic bugs in a mature, well-tested project, and the suite stayed green for 57% of them. Unit tests can each pass while the feature, entered the way a user enters it, still fails. agent-sdlc puts those checks, plus scope, intent and git safety, into hooks and a gate instead of leaving them to the agent's memory.

Problem What catches it
Tests that pass but assert nothing mutation-gate: a surviving mutant blocks the commit
Tests shaped to the code An adversary review that sees intent and tests, never the code
Unit tests green, feature broken One vertical-slice test per ticket, entered where a real consumer enters, red before any code
Scope creep 40-line limit without a ticket; one ticket, one branch, one PR
Code bloat Smallest-change and zero-comment rules; an opt-in no_comments check in mutation-gate; every added line must kill its mutants
Design notes rotting in the tree New .md files are blocked; intent lives in the tracker
Destructive git A hook that denies reset --hard, add -A, force-push
AI tells and leaked identity in commits commit-msg and no-leaks hooks

How it fits together

x marks a blocker. [name] is the rule in rules/ that applies.

 rules/*.md sync into .claude/rules and AGENTS.md; every session loads them

  idea
   |  /grill, or gh issue create
   v
 +--------------------------+
 | ticket                   |  intent lives here, not in the tree  [tickets]
 +--------------------------+
   |  triage: model:* label + assignee
   v                       x assigned to someone else: /kata stops
                           unlabelled or unassigned: /kata asks first
 +--------------------------+
 | /kata N                  |  one ticket, one branch, one PR      [tickets]
 | branch off origin/main   |
 +--------------------------+
   v
 +--------------------------+
 | red slice test           |  enters where a user enters,         [testing]
 |                          |  watched failing first
 +--------------------------+
   v
 +--------------------------+
 | implement                |  smallest change           [diff-discipline]
 |                          |  no comments, canonical names
 +--------------------------+         [code-clarity] [naming]
   |  every Bash call: git-guardrail  x reset --hard, add -A, force-push, checkout in the primary worktree
   |                   host-exec      host python3/pytest/make run in test_image
   v
 +--------------------------+
 | git commit               |
 |  pre-commit              |
 |   rules-check            |  x .claude/rules drifted from the pack
 |   mutation-gate ---------+- x surviving mutant --> new test, or waiver
 |   no-new-docs            |  x new .md file not allowlisted
 |  commit-msg              |
 |   commit-msg             |  x banned words, AI attribution    [voice]
 |   diff-discipline        |  x over 40 lines, no ticket ref
 |   no-leaks               |  x email, private IP, home path
 +--------------------------+
   |  gate green -> adversary review: sees intent and tests, never
   |  the code; reports, never blocks; answer every finding
   |  Stop hook: runs the same gate if no commit did
   v
 +--------------------------+
 | push, PR "Closes #N"     |  x CI red
 +--------------------------+
   v
 +--------------------------+
 | you review, type LGTM    |  squash merge, branch deleted
 +--------------------------+
   v
  /done: handoff, follow-up tickets --> back to "ticket"

Example

def is_adult(age):
    return age >= 18

def test_adult():
    assert is_adult(30)

def test_child():
    assert not is_adult(5)
BLOCKED: 2 mutant(s) survived with no waiver.
  age.py:2:11:operator:age >= 18 => age > 18
  age.py:2:18:literal:18 => 19

Add assert is_adult(18) and assert not is_adult(17), and the gate passes.

Install

Claude Code:

claude plugin marketplace add PavelGuzenfeld/agent-sdlc
claude plugin install agent-sdlc@agent-sdlc

Tools the gate needs, and Codex:

git clone https://github.com/PavelGuzenfeld/agent-sdlc
cd agent-sdlc
./install.sh --deps
Want Do
Claude Code The plugin above; --scope local or --scope project keeps it to one repo
Codex ./install.sh --target codex, or add the repo as a Codex marketplace source
Gate dependencies ./install.sh --deps (--deps=say adds voice)
Only the gate pip install agent-sdlc (WordNet check: agent-sdlc[vocabulary])
The gate on a repo Add .mutation-gate.toml, wire the pre-commit hooks
  • install.sh links skills/ into ~/.codex and renders commands/ as Codex skills. It installs nothing into ~/.claude. A second run changes nothing.
  • Installed an older install.sh into ~/.claude? ./install.sh --uninstall-legacy removes those links and hooks, or every hook fires twice.
  • ast-grep-cli adds an sg shim that can shadow the system sg; call ast-grep.

Use it

In Claude Code (Codex: $name instead of /name):

  1. Install the plugin and ./install.sh --deps
  2. In your repo: touch .mutation-gate.toml && mutation-gate rules sync
  3. claude, then /grill <idea> or gh issue create …
  4. Approve the ticket: gh issue edit 42 --add-label model:sonnet
  5. /kata 42: a worker writes the failing slice test, implements, gates, opens the PR
  6. Review, then type LGTM: it squash-merges and cleans up
  7. /done to close out the session

Full walkthrough, and what differs in Codex: https://pavelguzenfeld.com/agent-sdlc/usage/

With standard

standard runs C++ and Python quality gates on the PR. agent-sdlc runs before the commit. Use both:

 agent session  ->  git commit  ->  PR  ->  merge
 '------ agent-sdlc -------'       '-- standard --'

Run standard's setup first, then mutation-gate rules sync. Copying its AGENTS.md afterwards drops the rules block. In CI, the agent-sdlc diff checks need --range, because pre-commit run --from-ref doesn't enforce them. Setup order, the CI job and the docs/ allowlist: https://pavelguzenfeld.com/agent-sdlc/usage/#with-standard

What's inside

Path What
rules/ How to work; synced into a repo with mutation-gate rules sync
commands/ Slash commands: /kata, /done, /grill, /rectify …
skills/ On-demand playbooks: /diagnose, /sol-budget, /verify-generated-diff …
bin/ Hooks and helpers: session-preflight.sh, git-guardrail.sh, the /say stack. mutation_gate/host_exec.py is the host-exec hook
mutation_gate/ The gate and the mutation-gate CLI

CI runs scripts/no-leaks.sh on every PR. It flags emails, RFC1918 addresses, user-at-host references, /home/<user>/ paths and non-personal ghcr.io/ paths, and prints only file:line.

MIT, see LICENSE and NOTICE.md for one vendored third-party skill. Contributions: CONTRIBUTING.md, bound by CODE_OF_CONDUCT.md. Security: SECURITY.md.

Metadata

Release files for agent-sdlc 0.5.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-sdlc 0.5.7
File Size Uploaded Provenance Actions
agent_sdlc-0.5.7.tar.gz 87.5 kB With provenance Details for agent_sdlc-0.5.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-sdlc 0.5.7
File Interpreter ABI Platform Actions
agent_sdlc-0.5.7-py3-none-any.whl Python 3 none any Details for agent_sdlc-0.5.7-py3-none-any.whl

Total release size: 190.2 kB

Release files / agent_sdlc-0.5.7.tar.gz

Download URL agent_sdlc-0.5.7.tar.gz
Size 87.5 kB
Tags Source
SHA-256 checksum
How to use checksums
39d4549a7c8c1ce201564d8f904025037560930e8adc50a1f2ac9b7027014c40
BLAKE2b-256 checksum
How to use checksums
e055a56397026d64d1ea8190652dac8ffc74e872aa9befb7358e3b630429c32c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / agent_sdlc-0.5.7-py3-none-any.whl

Download URL agent_sdlc-0.5.7-py3-none-any.whl
Size 102.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f880be3f2465e37749a26a6c2d52057e855e84a5347eab776ed6636d1ab7b6ef
BLAKE2b-256 checksum
How to use checksums
a038d42e2b76f329223a061ed0e8511e48aa8277ffe64d09690822336cdcbd46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for agent-sdlc 0.5.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_sdlc-0.5.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page