Open source · MIT Cursor · Claude Code · Codex Jira or Linear · GitLab or GitHub

Your AI agent says it's done. Make it prove it.

sdlc-kit takes a Jira or Linear ticket to a reviewed merge request on GitLab or GitHub. The agent plans before it codes, writes failing tests first, and can't say "done" until real check scripts agree.

git clone https://github.com/aniketshukla1/sdlc-kit.git
Get started Star on GitHub
  • 16 skills
  • 14 hook rules
  • 98 self-tests
agentDone ✓ All tests pass. $ bash .cursor/skills/run-checks/scripts/check_all.sh … === guards === [debug/ignore] backend/app/orders.py line 42: print("debug") --- guards: FAIL … FAIL: guards $ git push --force Blocked by the agent kit: force push. $
Real kit output, from a throwaway repo

01Why it works

Five shortcuts the agent can't take

The kit doesn't ask the model to be careful. It makes being careful the only way through.

  1. The agent says: I'll start coding.

    No code before a plan you approve

    Vertical-slice tasks, edge and abuse cases, and the exact expected result of every test. You type approve. No code before that.

  2. The agent says: The tests pass.

    Tests come first, and they fail first

    Every task starts with tests that fail. Then the code makes them pass. A test that passes before its code exists is rejected.

  3. The agent says: Looks done to me.

    check_all.sh decides

    Lint, types, tests, changed-line coverage, migrations and 11 kinds of guards, run on the diff. The model doesn't get a vote, and the MR shows the verdict for its exact commit.

  4. The agent says: I'll just force-push.

    A hook says no before it runs

    No force push, no merge, no wiping your uncommitted work, no remote servers. A command hook denies those commands before they run.

  5. The agent says: Merged it for you.

    It never merges

    It opens the MR, answers review threads and fixes failed jobs. You review. You merge. Always.

02How it works

Sized to the ticket

The ticket's type picks the track, so small tickets stay small (on Linear, a Bug label or a sub-issue). Every chat starts from PROGRESS.md, so Continue PROJ-123 picks up exactly where the last one stopped.

A failing test reproduces the bug, the agent finds the root cause and checks every caller, you approve a ten-line plan, then it fixes, checks and opens the MR.

  1. 1

    Reproduce

    A failing test shows the bug

  2. 2

    Root cause

    Found, every caller checked

  3. Plan

    You approve ten lines (human gate)

  4. 4

    Fix

    The failing test goes green

  5. 5

    Check

    ALL PASS

  6. 6

    MR

    Opened, same chat

  7. You merge

    Always you (human gate)

Intake, explore, plan, your approval, red then green per task, checks, self-review, MR.

  1. 1

    Intake

    Given / When / Then, no open BLOCKER

  2. 2

    Explore

    Pattern to copy, test setup, size limits

  3. Plan

    You type approve (human gate)

  4. 4

    Build

    Tests red, then code green, per task

  5. 5

    Check

    Only ALL PASS counts

  6. 6

    Self-review

    Fresh chat, five axes

  7. 7

    MR

    Opened, linked on the ticket

  8. 8

    Feedback

    Pipeline green, threads handled

  9. You merge

    Protected branches (human gate)

One roadmap for all of the sub-tasks, approved once; then each sub-task gets its own branch and MR, in dependency order.

  1. 1

    Intake

    The ticket and every sub-task

  2. 2

    Roadmap

    One plan for all of them

  3. Approve once

    The whole roadmap (human gate)

  4. 4

    Sub-tasks

    One branch and MR each, in dependency order

  5. 5

    Small ones

    Three plan tasks or fewer: one chat

  6. You merge

    Each MR, one by one (human gate)

Amber steps are human gates: the agent stops and waits for you.

03See it run

Watch it catch a cheat

The agent claims it's done. The tests start red, the checks catch a debug print, the hook blocks a force push. Real kit output.

Muted loop. Watch with sound

04Guardrails

Every guardrail is a script or a hook

Except the two gates that stay human.

  • The plan is approved before any codeyou type approve
  • Nothing merges without youprotected branches

  • No debug code, ignore comments, any, skipped or removed tests, secrets, stubs or swallowed errors

    check_guards.sh

  • No edits to .env*, production compose, CI config, search mappings or lint/test config

    check_guards.sh + human exceptions

  • Only the files in the approved plan change

    check_scope.sh

  • Lint, types and the full test suite pass

    check_backend.sh · check_frontend.sh

  • Migrations reverse cleanly, one head, no drift; never edit one already on main

    check_migration.sh · check_guards.sh

  • Tests and migrations only touch a local database

    db_guard.sh

  • Files ≤ 200 lines, React components ≤ 150

    check_size.sh

  • No force push, merge, reset --hard, ssh or kubectl; network only to localhost

    command hook · block_commands.py

  • The MR carries its proof: ALL PASS on exactly the commit under review, the logged red lines, the changed files

    proof_pack.sh

  • At least 90% of the changed production lines run in the tests; lowering the minimum needs a human

    check_coverage.sh

The same guards catch deleted or skipped tests, weakened lint and test config, secrets, edits to migrations already on main, stubs left over from test-first, and swallowed errors.

05What's inside

16 skills, one short checklist each

Long instructions make cheaper models skip steps. Each skill loads only in its phase, and each standards file only when a matching file is edited.

Plan phases 1–3

ticket-intake
The ticket and its sub-tasks as Given / When / Then; questions batched as BLOCKERs.
codebase-explore
Finds the pattern to copy, the test setup and the files near the size limit.
implementation-plan
Vertical slices, abuse cases, exact expected results. Stops for approve.

Build, test first phase 4

write-tests
Writes each task's tests before its code and shows them failing.
db-migration
Model and Alembic migration with an up → down → up round trip.
backend-implement
FastAPI route → service → repository until the red tests pass.
frontend-implement
React + TypeScript + shadcn/ui with loading, empty, error and success states.

Check and ship phases 5–8

run-checks
One command, one verdict: ALL PASS or FAIL.
self-review
Reviews the diff in a fresh chat on five axes.
gitlab-mr
Explicit git add, typed commits, the MR from a template with a Proof section.
mr-feedback
Fixes failed jobs, handles open threads, merges main on conflicts.

Shortcuts and teammates any time

quick-fix
The whole quick track in one chat.
chat
No ticket? A request typed in chat becomes a local ticket with testable criteria, then the normal track.
jira-create
A detailed Jira or Linear ticket from one sentence, using your team's templates.
mr-review
Reviews any MR against its ticket; posts labelled threads only after you type post.
ticket-qa
A pass/fail QA plan from the acceptance criteria, with evidence.

06Proof

Tested like production code

The checks are what make the kit trustworthy, so they're tested too. Read a recorded run on a sample repo.

  • 98

    Self-tests

    The real scripts run in throwaway git repos against every bypass we know. Each new case was first proven to fail against the old script.

  • 7

    Holes found, all fixed

    The first version printed ALL PASS on bad changes in 7 ways. Read the audit

  • 25

    Skills reviewed

    Every one of Addy Osmani's agent-skills compared with the kit. Read the review

  • 14

    Hook rules

    Risky commands are denied before they run, not flagged after.

07Quick start

Five minutes to your first ticket

You need Cursor, Claude Code or Codex, GitLab with glab or GitHub with gh, a Jira or Linear MCP server, git, python3 and ripgrep. The standards target FastAPI + React; other stacks mostly mean editing paths.

  1. Install it into your repo

    It never overwrites your files, adds Claude Code or Codex when your repo uses them, and ends with a checklist. Linear: add --tracker linear.

    git clone https://github.com/aniketshukla1/sdlc-kit.git
bash sdlc-kit/install.sh path/to/your-repo --key PROJ

  2. Connect your tools

    Run glab auth login or gh auth login, and add your Jira or Linear MCP server to your agent. The kit reads GitLab or GitHub from your origin remote.

  3. Trust the workspace

    Trust it when your agent asks, then prove the hook works: ask the agent to run git push --force --dry-run. It must be blocked. Codex has no hook yet; your protected branches are its gate.

  4. Commit the kit

    Through a normal MR. Rerun the checklist any time:

    bash .cursor/skills/run-checks/scripts/doctor.sh

  5. Start a ticket

    In your agent's chat:

    Start ticket PROJ-123. Follow the ticket workflow rule.

08FAQ

Questions people ask

Something else? Open an issue.

Will the agent ever merge, deploy or touch production?

No. The hook denies merge, approve and force push, and blocks kubectl, ssh, p4, and network tools aimed at anything but localhost. The database checks refuse any host that isn't local, and protected branches stay the final gate.

Does it burn a lot of tokens?

Less than one big prompt. A bug is one chat. Skills load only in their phase and standards only for matching files, so the context stays small where the work is small.

Does it work with Claude Code, Codex or Copilot?

Cursor, Claude Code and Codex are supported. Claude Code gets the same rules, the 16 skills as slash commands and the same command hook. Codex reads AGENTS.md and the skills; it has no command hook yet, so your protected branches are its gate. Other agents can follow AGENTS.md: everything is plain Markdown and shell.

Do I need Jira or Linear?

No. Type the request with /chat: it drafts a local ticket with testable acceptance criteria and a CHAT-<n> key, you type start, and the same tracks, tests and checks run. The MR quotes the request, so reviewers still see what was asked.

GitHub instead of GitLab? Linear instead of Jira?

GitHub works: the kit reads the host from your origin remote and does every MR step through gh, with pull requests, checks and review threads. Linear works too: write linear in .agent/tracker.txt; a Bug label or a sub-issue takes the quick track.

My stack isn't FastAPI + React.

The workflow, tracks, hook and guards are stack-agnostic. Point the standards files and the backend and frontend check scripts at your own linters and test runners.

It never merges. You do.

Ticket in. Reviewed MR out. Scripts decide when it's done.

git clone https://github.com/aniketshukla1/sdlc-kit.git
Get started Star on GitHub