senior-mode
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 7 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
"use strict" for coding agents. Hooks, gates, doctrine, and a stack picker for Claude Code, Codex, Cursor, Gemini, Copilot, OpenCode and any AGENTS.md agent.
senior-mode
"use strict" for coding agents. Make the agent fail its own review
before you see the answer.
One setup that makes a coding agent behave like a senior engineer, for
whichever agent you use: hooks that fire a checklist at the moment of
decision, commit and push gates that refuse half-done work, a doctrine of
how a green check lies to you, path-scoped rules, specialist reviewers,
and a memory of how you like to work. One source of truth in the repo,
generated wiring per agent, a stack profile picked from evidence.
Adapters for Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub
Copilot, OpenCode, Factory Droid, Devin CLI, and Augment (hooks and
all), and AGENTS.md for anything else (Windsurf, Kiro, Amp, Zed,
Warp, Jules, Junie, Cline) carrying the doctrine, rules, and procedures.
Any stack; a fresh repo or one that is already set up. See "What is
verified" below before you trust a claim.

Rendered walkthrough (docs/make-gifs.py, same for every GIF on
this page). Agents do not display hook-injected context in their UI, so a
screen recording cannot show the hooks firing; the banner text is
verbatim from the hook scripts.
Two ways in
1. The 5-minute version (starter/)
Installs globally under your agent's home directory, so it applies in
every repo with no per-project work. Nothing touches git or deploys.
git clone https://github.com/maxwynndev/senior-mode
bash senior-mode/starter/install.sh # Claude Code (default)
bash senior-mode/starter/install.sh --agent codex # or codex, cursor, gemini, copilot, opencode, all
You get the behavioral core (ask when ambiguous, evidence before the
first edit, never cite an unread source, one-pass thoroughness, never
weaken a test to get green), the two senior-check hooks, the doctrine,
the prompting guide, and /review.

2. The full kit (repo root)
For a project you ship from. Adds commit and push gates, parallel-session
safety, six review subagents, fifteen procedures, a multi-agent audit
workflow, auto-formatting, and a stack profile picked from the repo.
bash senior-mode/install.sh --dry-run /path/to/your-repo # see what would happen, for the agents it finds
bash senior-mode/install.sh /path/to/your-repo # install for the agents it finds; stack detected from manifests
bash senior-mode/install.sh --agent claude,cursor --stack python-fastapi-postgres /path/to/your-repo
bash senior-mode/install.sh --list-stacks # the stack picker
bash senior-mode/install.sh --upgrade /path/to/your-repo # take a new kit version; your AGENTS.md, rules and docs are kept
Then open your agent in the repo and paste .senior-mode/KICKOFF-PROMPT.md.
It verifies the hooks, confirms or picks the stack (with the evidence),
fills in the placeholders with you, and merges anything the installer
would not overwrite. Full walk-through: START-HERE.md, then SETUP.md.
How one kit fits every agent
AGENTS.md the universal entry point: posture, rules table, procedures, stack
CLAUDE.md "@AGENTS.md" plus Claude Code notes (Claude does not read AGENTS.md itself)
.senior-mode/ the source of truth
hooks/ bash scripts speaking the Claude Code hook JSON contract
rules/ reviewers/ commands/ memory/ stacks/<profile>/
.agents/skills/ the procedures as Agent Skills (read by most agents)
.claude/ .codex/ .cursor/ .gemini/ .github/ .opencode/ ... generated wiring, one adapter each
The hook contract (tool_input.command in, permissionDecision out) is
spoken natively by Claude Code, Codex, Factory, and Devin; Copilot reads
denies at the top level, and Augment's hook command is a bare script
path, so both run the same scripts through a small one-way shim (Augment
via generated wrappers); Cursor and Gemini get a 60-line shim; OpenCode
gets a plugin that runs the same scripts. adapters/README.md has the
full capability matrix, including what each agent cannot do (Cursor
cannot inject context on prompt submit, Copilot drops prompt-hook
output, Augment has no per-prompt event) and how the kit degrades there.
Why this is different
Most agent configs are a rules file that says "be a senior engineer."
The model reads it, agrees, and then ships the convenient reading of your
directive anyway. The rule was recalled; it was not applied. This kit is
built around closing that gap.
The checklist fires at the decision moment, not in the system prompt.
A prompt-submit hook injects the senior checklist as each prompt arrives
(is this ambiguous? what is the 100% version? what evidence confirms the
diagnosis?). A stop hook blocks the response once per turn with the
after-checklist (did you cut a corner? would a senior push back? could
your green have gone red?), on any turn that ran a command or edited a
file. The agent fixes it before you see it. The hooks are fail-open, and
the stop hook blocks 3 times in one turn at most.
The answer ends with what got done. The same stop hook reads the
final answer. If it hands you a "what I didn't do" list, an "I haven't
tested" or an "Open items" heading, the hook sends it back with one
instruction: do it now. A decision that's yours reaches you as a
multiple-choice question, and a step only you can take reaches you as
exact instructions. Finished work closes with an [AFTER-AUDIT] block:
what the turn covered and how it was verified, and what the checks
caught that a first pass would have shipped without.
A green check that cannot fail proves nothing. Section 19 ofENGINEERING-PRINCIPLES.md is a catalogue of the ways a review lies to
itself, each of which cost a real team real hours more than once: the
test no runner imports, the suite that reports "0 failed" because 0 ran,
the | tail that replaced the exit code, the grep that matched the marker
you wrote yourself, the fix that was right for a false reason.exit-code-mask-guard.sh exists because a piped CI watcher reported red
runs as green five times in two months on one project.

The gates read the repo you are actually in. git push is denied
unless HEAD carries a Senior-Checklist: trailer with five graded keys
(ambiguity, summary, concurrency, regression, blast). A commit is denied
for a bare TODO, a print-debug line in a prod path, or a new source
file over 400 lines without a stated exception. Both validate the repo
the command runs from, so they work from worktrees, under any agent.

Parallel sessions do not tangle. A session registry knows who else is
live in your checkout, whichever agent they are running. The first
session is the incumbent; a second one in the same tree is steered to a
worktree and blocked from committing until it isolates.

The stack is picked from evidence. stacks/detect.sh scores every
profile's signals against the manifests and prints the ranked evidence;
a confident match installs, anything weaker goes to a picker the agent
walks through with you. Seven profiles ship (Next.js + Vercel + Postgres,
Node API, FastAPI, Django, Rails, Go, Rust), each with real commands inprofile.json so the agent never guesses how to run tests or migrate.
Briefing enforcement is calibrated, not nagging. A question passes
straight through. A vague build prompt ("make the dashboard better")
stops once and asks for the missing pieces as one multiple-choice
question, best guess first.
A complete brief runs to its stop condition without check-ins.

The hooks are tested. bash core/hooks/test-checklist.sh runs the
harness against scratch git repos: every deny and allow path, the
worktree case, the loop backstop, both shims in both directions, the
detector's verdicts, and a real install. It runs in CI on Linux, macOS,
and Windows on every push. Nobody tests their hooks. These are tested.
Evidence before code, visibly. Before a non-trivial edit, the agent
leads with a [BEFORE-AUDIT] block: diagnosis and the evidence it rests
on, what is missing, the 100% version, the shortcut it won't take, what
a senior would reject. It comes before the edit, where you can still
stop it.
What is verified, and what is not
Plainly, so nobody has to find out the hard way:
- Run end to end here: Claude Code 2.1.241 and Codex CLI 0.146.0
(Codex's hook file format was checked against a live~/.codex/hooks.json).
The v6 stop hook ran in a live Claude Code 2.1.330 session: an answer
ending in "I haven't tested it" came back once with the undone-work
block, and the corrected answer went through. The harness (141 cases,
143 where bun is installed) runs on every push on Linux, macOS, and
Windows. - Validated against official docs and the harness, not inside the
agent: the Cursor, Gemini, Devin, Copilot, and Augment shims
(payloads are tested against the real hook scripts), and the Copilot,
OpenCode, Factory, Devin, and Augment adapters (generated files parse,
and the harness asserts each agent's matchers and command shapes;
formats follow the docs as of August 2026). If you run one of those, the first prompt
tells you whether the check arrived; an issue with the payload you saw
is the most useful contribution you can make. - The undone-work check needs the final answer in the hook payload.
Claude Code documentslast_assistant_messageon its Stop event, the
Codex CLI 0.146.0 binary carries the same field name, and Gemini sendsprompt_response, which the shim maps. Cursor'sstopevent has no
answer text, so the check is skipped there. I haven't confirmed the
field for Copilot, Factory, Devin or Augment; an agent that doesn't
send it skips the check and keeps the rest. - Instruction only: every agent that reads
AGENTS.mdbut has no
hook contract this kit can verify. There the checks are asked for, not
enforced. - The hooks are prompts, not guarantees. A senior-check is text the
model reads at the right moment; the commit and push gates are the
only mechanical blocks. Models still ship the convenient reading
sometimes. The kit makes that rarer and more visible, not impossible.
What's in the box
senior-mode/
starter/ the 5-minute global install, per agent
README.md START-HERE.md SETUP.md KICKOFF-PROMPT.md STACK.md CHANGELOG.md
CONTRIBUTING.md SECURITY.md
install.sh --agent, --stack, --dry-run, --force, --list-stacks
AGENTS.md / CLAUDE.md this repo's own instructions (it runs its own kit;
the templates that ship to users are in core/)
ENGINEERING-PRINCIPLES.md never/always lists, money/PII/tenant invariants, LOC budget, refactor tiers, verification craft
PROMPT-STANDARD.md the 5-element brief, verification loops, context hygiene
PROMPTING.md writing LLM system prompts (rubric, evals)
WORKFLOW.md deploy pipeline template (two verification models)
core/ the source of truth
AGENTS.md CLAUDE.md the entry-point templates installed into your repo
hooks/ 9 wired, 2 optional, 1 test harness
rules/ 5 stack-neutral path rules
reviewers/ 6 briefs: 5 read-only reviewers + 1 app verifier
commands/ 15 procedures
memory/ working-style preferences that travel with you
adapters/ one generator per agent + the Cursor and Gemini shims + the capability matrix
stacks/ detect.sh, README.md (the picker), 7 profiles
nextjs-vercel-postgres/ the reference web-app profile, with the QA pack
node-api-postgres/ python-fastapi-postgres/ django-postgres/ rails-postgres/ go-service/ rust-service/
docs/ the GIFs and their generator
Opinions you will want to argue with
Extracted from a working production setup, and opinionated. Every one of
these is a file or a line you can delete.
- Push to the deploy branch, no PRs. Safety lives in CI, the deploy
gate, and rollback.WORKFLOW.mdships a PR-based model too; pick one. - The push gate wants a commit trailer. It forces a 10-second
self-check before the one irreversible action. Remove the hook if you
hate it. - The after-check costs one extra model round on every turn that
ran a command or edited a file, where the agent supports it. A turn
that only answered a question skips it. Delete that event from the
generated wiring if it is not worth it to you. - 400 lines per new file. Enforced at commit. Raise the number in
pre-commit-audit.sh, or add the exception comment. - Thoroughness over token thrift. The doctrine says spend what the
task warrants. Soften it inAGENTS.mdif your budget disagrees. - The memory bundle assumes you trust the agent with operational CLIs
once confirmed per project. Deletefeedback_cli_authority.mdif not.
Requirements
- Any of the agents above.
bashon PATH (Git Bash on Windows; the hooks are bash scripts and run
on macOS, Linux, and Windows).git.- Optional:
nodefor JSON validation in the harness;ANTHROPIC_API_KEY
for the counterfactual verifier hook.
Contributing
Run the harness before and after touching anything under core/ oradapters/:
bash core/hooks/test-checklist.sh
An adapter is one bash script (adapters/README.md explains the contract);
a stack profile is a folder (stacks/README.md). Both are good pull
requests. See CHANGELOG.md for what moved when and why.
License
MIT.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found