agents-scaffold

Guardrails for Claude Code · Codex · Antigravity

AI coding agents break your rules. This blocks the commit.

One command installs an AGENTS.md project brain, path-scoped rules, skills, subagents, hooks and a real git pre-commit gate into your repo. No framework, no runtime, no registry — plain files you own.

$ curl -fsSL https://raw.githubusercontent.com/leeyudok/agents-scaffold/main/bin/agents-scaffold.sh | bash -s -- --lang en --stack nextjs --yes

Run it in your repository. Add --dry-run to see what it would write first, or pin and verify the download.

The actual output of the installed gate. It runs from .git/hooks/pre-commit, so it holds for any agent — and for a person at the terminal.
  • 3 agentsread one AGENTS.md natively
  • 13 stack presets12 with a build, type or lint gate
  • 169 testsbats regression suite for the installer
  • 0 runtimesMIT-licensed plain files in your repo

Demo

One command, then the gate does the arguing

A rule that lives only in a prompt gets ignored eventually. The scaffold turns the rule into a gate that stops the commit, and plants it in the repository.

Terminal recording: one command installs guardrails for Claude Code, Codex and Antigravity; the generated AGENTS.md, .claude, .codex and .agents tree is listed; then the real git hook blocks a commit that stages a .env file.
30 seconds: install → the generated tree → a secret commit is blocked. Recorded with vhs docs/assets/demo.tape.

Why it holds up

Enforcement lives outside the agent

Prompts are requests. These are the parts that do not depend on a model choosing to comply.

.git/hooks/pre-commit

Enforced by git, not by prompts

The gate blocks a staged .env and runs the selected stack's build, type or lint check. It is wired in worktrees, submodules and under core.hooksPath.

AGENTS.md

One source, three agents

Claude Code, Codex and Antigravity read the same AGENTS.md. Skills live once in .agents/skills; Codex and Antigravity adapters are generated from .claude/.

harness-matrix.json

Measured, not assumed

Each harness claim is a recorded measurement against a named CLI version. A weekly CI job fails when a full-tier measurement is older than 90 days.

paths:

Rules load when they apply

A path-scoped rule is loaded only while the agent touches matching files, so context is not spent on conventions for code it is not editing.

--dry-run · --update · --uninstall

Reversible by design

Preview before writing. Updating never overwrites a file you changed — the new version lands beside it as .new. Uninstall removes only untouched files.

offline bundle · Git Bash

Air-gapped and Windows ready

An offline bundle installs with no network. Windows runs through Git Bash with a .cmd launcher, and falls back to a checked copy where symlinks are unavailable.

What lands in your repo

Files you can read, edit and delete

Nothing is hidden in a package. This is an English install with one stack; a Korean install adds 14 Korean-language yd-* expert skills.

Diagram: one command produces a .claude directory you own — agents, skills, commands, rules, hooks, memory and AGENTS.md — and enforced gates that block a staged .env, a broken build and failing lint.
AGENTS.md              # rules: P0 / P1 / P2
.claude/
  rules/               # 5 files + 1 per stack
  agents/              # 7 subagents
  commands/            # /fix-issue, /sdlc-cycle
  hooks/pre-commit.sh  # the gate
  memory/              # project memory
  settings.json        # deny / ask rules, hooks
  .scaffold.json       # your install choices
  skills -> ../.agents/skills
.agents/skills/        # 10 skills
.git/hooks/pre-commit  # runs the gate

Harness support

Two tiers, stated plainly

baseline is what holds everywhere: the AGENTS.md policy body, including the selected stack's P0 rules, and the git gate. full adds the harness's own layers with every capability measured as passing or partial. Measured 2026-11-04.

HarnessTierMeasured as workingLimits
Claude Code 2.1.318 full AGENTS.md, path-scoped rules, skills, subagents, the git gate Its own hooks fire only when the session commits through its Bash tool — early feedback, not the enforcement line
Codex codex-cli 0.166.0 baseline AGENTS.md with inlined stack P0, skills, generated subagents and hooks, the git gate No file-path-scoped instructions. .codex/ loads only for a trusted project
Antigravity agy 1.5.0 baseline AGENTS.md with inlined stack P0, skills, generated subagents and hooks, the git gate Glob-triggered rules stopped loading on 1.5.0. Hooks run without a trust prompt — read .agents/hooks.json in a repo you did not write

The source of truth is docs/harness-matrix.json, with the evidence for every verdict. This table is checked against it.

Stack presets

13 stack presets, composed into one gate

Pick any combination with --stack nextjs,python. Each preset adds a rule file scoped to its paths and, where a tool can check it, a step in the pre-commit gate. --list-stacks prints the names; a misspelt one is an error, not a silent skip.

  • nextjstsc --noEmit
  • bunbunx tsc --noEmit
  • pythonruff check, mypy
  • gogo build, vet, golangci-lint
  • rustcargo check, clippy
  • springbootgradlew build
  • javawebmaven / gradle / ant compile
  • dotnetdotnet build, format, test
  • ruby-railsrubocop, rspec
  • php-laravelcomposer validate, pint, phpunit
  • androidktlintCheck, detekt
  • flutterdart format, analyze, test
  • opsrules only, no gate step

GitHub or GitLab workflow with --forge. Rules and messages in English (--lang en) or Korean (the default).

After install

Four steps, and the installer prints them too

Paths assume the clone from the quickstart, in agents-scaffold/.

  1. Fill in AGENTS.md

    Three sections are left empty for you: Project overview, Stack, Commands. Everything else is ready.

  2. Prove the gate works

    This commit must fail with Blocked. Then unstage the file.

    echo X=1 > .env && git add -f .env && git commit -m test
    git rm --cached -q .env && rm .env
  3. Commit what was installed

    The hook itself lives in .git/, so each clone wires it once — --update does that.

    git add AGENTS.md .claude .agents .gitattributes
    git commit -m "chore: add agents-scaffold"
  4. Update or remove, later

    Your choices are recorded in .claude/.scaffold.json and replayed. --dry-run previews either.

    agents-scaffold/bin/agents-scaffold.sh --update .
    agents-scaffold/bin/agents-scaffold.sh --uninstall . --dry-run

Stuck? The troubleshooting guide covers a blocked commit, an ignored AGENTS.md, .new files, husky and Windows symlinks.

How it compares

Categories, not products

Check any specific tool against the rows. For a small repo with one agent, a hand-written file is the right answer.

QuestionHand-written CLAUDE.md / AGENTS.mdRule packs and frameworks inside one vendor's runtimeagents-scaffold
Where a rule is enforced In the prompt. The model can ignore it Inside that agent's session. A commit made outside it is not checked In .git/hooks/pre-commit, outside any agent. It also runs when a person commits
Can it be bypassed Nothing to bypass Work outside that runtime Yes — git commit --no-verify. Keep CI as the backstop; the scaffold does not install CI
Several agents, one repo One file per tool, kept in step by hand Typically one vendor One AGENTS.md for three; Codex and Antigravity at the baseline tier
What you keep upgrading Nothing A plugin, package or CLI Nothing running — but roughly 60 to 190 files committed to your repo
Getting new versions You edit the file The vendor's update channel --update; changed files are kept and the new one is written as .new to merge
Offline install It is just a file Depends on reaching a registry or marketplace An offline bundle

Docs

Read it in your language

The README and the reference docs are maintained in four languages. The installed rules come in English or Korean.

README

Overview, quickstart, after install.

All options

Stacks, forge, harness, language, update, uninstall.

Internals

The generated tree and the design patterns.

Troubleshooting

Blocked commits, ignored rules, hooks, Windows.

Skills

Skill sets, the plugin marketplace, npx skills.

Offline and Windows

Air-gapped bundle, Git Bash, python3.

Also: security policy, changelog, contributing, and llms.txt for language models. Version 1.0.0 is in preparation; no release has been tagged yet.