prepush-ci
AGENTS.md10 starsChanged 36 days agoMITView on GitHub
The rulebook for everyone who changes this repository, human or agent. README.md says what the tool is; LOOP.md says how the loops that build it work together. Follow them; don't restate them. The organization also offers Improvement and Sub-task; this repository does not use them. - Every issue says why. Its body opens with ## Why: one to three sentences on whose problem it solves and what goes wrong without it. A pointer is not a reason: a slice says…
- Deletes or force-pushes
- Commits and pushes
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- prepush-ci-setupSkill
The file
Files
AGENTS.md
The rulebook for everyone who changes this repository, human or agent. README.md says what the tool is; LOOP.md says how the loops that build it work together. Follow them; don't restate them.
Language
- Everything in this repository is English: code, comments, tests, specs, commits, issues, pull requests, this file. This holds whatever language the conversation is in.
Scope and backlog
- The open
Epicissues are the intent. Each is the scope contract for what it describes; #1 was the first release. A step an epic leaves for later is out of scope until the human decides on it. Decisions an epic leaves open are made by whoever picks them up, with a one-line rationale in the commit body (#1 asked for exactly this). Every piece of work is an issue with an issue type. Ideas, follow-ups and bugs become issues right away (
gh issue create --type …), never TODO comments. Anything outside the intent gets the labelproposaland waits for a human.Type Use it for Usual commit type Epicthe intent; its features are sub-issues (the first: #1) — Featurenew or changed behavior a user sees, improvements included featBugthe tool behaves differently from its spec or the intent; comes with a reproduction fixRefactoringa change inside the code that changes no behavior refactorTaskeverything without product behavior: docs, tooling, this harness, releases chore,docs,testThe organization also offers
ImprovementandSub-task; this repository does not use them.- Every issue says why. Its body opens with
## Why: one to three sentences on whose problem it solves and what goes wrong without it. A pointer is not a reason: a slice says the reason in its own words, then cites its section of its epic; "the owner asked" is not a reason, the owner's reason is. For a bug, the why is what it costs the user. An open issue without one gets it from bruce-lee before its spec starts. - Structure is native, not prose: slices of the intent are sub-issues of their epic (
--parent <epic>); dependencies are "blocked by" relations (--blocked-by <n>). Pick up an issue only when nothing blocks it. - Types say what an issue is; labels say whose move it is (
LOOP.md).
OpenSpec
- Behavior is specified before it is built. A feature or a behavior-changing bug fix is an OpenSpec change named
<issue>-<name>(e.g.openspec new change 4-pre-push-hook);proposal.mdstarts withIssue: #<n>. Use the/opsx:*commands or theopenspec-*skills. - The
readmespec checks drift, not prose. Its requirements check only what can drift away from the code: everyprepush-cicommand and flag the README uses exists, the reference names every command and every flag, the config keys and their defaults, the exit statuses, the command in the agent prompt, and the plugin commands against the manifests. What the README says, asks or names, the order of its steps and the form of its words are not pinned there; for them, "Docs say only what is pinned or run" holds. - A change to README text alone is a
Task. When it changes no behavior of the tool, it gets adocs:commit and no OpenSpec change. Bruce-lee sends the issue straight toturn:build, chuck-norris opensdocs/<issue>-<name>, and the drift checks still pass on it. It changes no code of the tool, so it skips the attack (LOOP.md, step 4). - Specs use SHALL and scenarios (
#### Scenario:with WHEN/THEN). Every scenario is covered by at least one test whose name says the same thing. - Docs say only what is pinned or run. A sentence in
README.md,SKILL.mdordocs/that says what prepush-ci does, prints or exits with names, in the change'sdesign.md, the requirement inopenspec/specs/that pins it; one that no requirement pins is run against the head before review, with the command and its output. A sentence neither backs is cut. This holds for the spec that asks for the text and for the text the builder writes. - Archive before merge. The implementation pull request ends with archiving its change (
openspec archive <change>), so specs inopenspec/specs/always describemain. npx openspec validate --all --strictmust pass (part ofscripts/ci), and before a spec goes to build it must also pass with the change archived: in a scratch worktree of the head,npx openspec archive <change> -y, then the same validation. A delta can pass on its own while the spec it merges into fails (a requirement over 500 characters), and the builder would find out only at the archive, with the code done. Bruce-lee runs this before each hand-over to spec review, and robocop checks it before approving a spec.
Commits
- Conventional Commits:
type(scope): subject, type one offeat, fix, docs, refactor, test, chore; subject imperative, lowercase, at most 100 characters. Enforced by commit-check (cchk.toml). - Scope is the OpenSpec change (
feat(4-pre-push-hook): …) or the issue number (fix(12): …). Bootstrap commits may omit it. - Type is the primary intent. A feature's tests and docs ride in its
feat:commit. OpenSpec artifacts aredocs:commits of their own. - Atomic: one logical change per commit. If the subject needs "and", split it.
- Fold review rounds before they land. Rebase merge puts every branch commit on
main, so "address review" commits must not survive. Fix a commit withgit commit --fixup=<sha>; before handing the branch back for review, fold them in withGIT_SEQUENCE_EDITOR=: git rebase -i --autosquash origin/mainand update with--force-with-lease. Fold down to logical commits, not to one. A reviewer sees what changed since the last round withgit range-diff. - Every commit passes on its own. Rebase merge puts each commit on
main, andgit bisectneeds each one to pass the tests it has. A fix folds into the first commit whose tests need it, never an earlier one. The archive commit only moves the change (openspec archive) and ticks its last task; a spec amendment goes into the change's owndocs:commit, through spec review (LOOP.md, step 5). Agent commits end with trailers naming the model and, for a loop, the loop:
Co-Authored-By: <Model Name> <noreply@anthropic.com> Loop: <loop name>- Nothing private in public text. This repository is public: no session links (
Claude-Session:), local paths, e-mail addresses or other links only you can open, in commits, pull requests or issues.
Branches and pull requests
- One branch per issue:
<type>/<issue>-<name>, e.g.feat/4-pre-push-hook. Nothing but bootstrap is committed onmain. - Pull requests follow
.github/pull_request_template.md, start withCloses #<n>, and carry a Proof section a human reads in one minute, in the formLOOP.md(Proof) gives for the change: a short demo when users see it, one line when it is internal, a decision note forrequest:decide. The acceptance criteria with their tests and the check result go into the reviewer's details. CI fails a pull request without a proof. - The human decides, the checks verify: the factory labels every pull request
request:decideorrequest:mergefrom its files and title, as.github/request-kinds.jsonlists them (a release, the rules inLOOP.md,AGENTS.md,.github/,.claude/andscripts/ci, dependencies: decide). Arequest:decidepull request merges only on the human's approval; arequest:mergeone is merged by the factory's merger once the last loop has handed it over and every check passed on its head. The last loop before that turns on auto-merge (rebase only): terminator when its attack passes, or robocop for a pull request that changes no code of the tool; no loop merges directly. Rebase onto the latestmainbefore handing over; update withgit push --force-with-lease, never--force.
Testing
- Tests are specs: they live in
tests/, files are named*_spec.py(pytest collects nothing else), and test names read as sentences about behavior:test_pre_push_refuses_a_trailer_commit_when_the_worktree_is_dirty. - Tiers, all run by
scripts/ci:tests/unit/: pure logic, no I/O (trailer parsing, config, ref lines, theverifydecision). Keep that logic in modules that do no I/O so it can be tested here.tests/integration/: the behavior a user sees, against real temporary git repositories (git initintmp_path), with hooks run by realgit commit/git push. Never mock git. Start the CLI assys.executable -m prepush_ci(in hook scripts too), never viauvxorPATH, so coverage measures it.tests/harness/: the repository's own tooling (agent hooks); not part of the product.
- End-to-end use of the released tool (
uvxin throwaway repositories) is not part of the suite; terminator does it (LOOP.md). - Never weaken a test to make it pass, never skip one silently. A test that cannot run fails.
- Coverage (branch, gated in
scripts/ci):src/prepush_ci/core/at 100% fromtests/unitalone (a branch only an integration test reaches does not count), everything at 100% overall on Linux (95% on Windows, which skips the specs that need the executable bit or anshstub), including code the tests start as a subprocess through git.core/does no I/O (a unit spec enforces it). Every# pragma: no covercarries a comment saying why. - Windows traps. The Windows job is the slowest, so a red that only it shows costs a whole round. Before
gh pr ready, check new code and specs against the traps this suite has already hit:- a subprocess's output is UTF-8 on Windows only when the spec sets
PYTHONIOENCODING=utf-8for it; otherwise it is the ANSI code page; - a spec that runs an
shscript or needs the executable bit isPOSIX_ONLY; - paths and test ids stay short: Windows refuses a path over 260 characters, and a long parameter needs
pytest.param(..., id=...); - a printed path is compared in the form the tool prints (
as_posix()), not with/written into the test; - a file that git commits is written with
\nline endings (newline="\n"); - deleting a file that a child process may still hold open tolerates
PermissionError.
- a subprocess's output is UTF-8 on Windows only when the spec sets
Versioning
- Semantic versioning; the version lives only in
pyproject.toml. Until 1.0.0, a minor bump may break the CLI or config; say so in the release notes. - A human decides every release, a loop carries it out: bruce-lee bumps the version in a
chore(release): …pull request; the human's approval of it is the release decision. Once it is merged, bruce-lee pushes the tagvX.Y.Zonmain. A tag for the version already onmain(e.g. a first upload that reserves the name) needs the human's yes in an issue instead..github/workflows/release.ymlrefuses a tag that does not match the version, publishes to PyPI and creates the GitHub release.
Quality gates
scripts/ciis the full check: ruff, format,mypy --strict, pytest, OpenSpec validation. CI runs it, on Linux and Windows, on every ready pull request and again onmainafter each merge.scripts/ci --fastis the same without the tests.- The suite runs once per commit, on GitHub. Locally, run the specs your change touches while you work (
uv run pytest tests/…); don't run the full suite before pushing, and never twice on the same commit. A red CI run is the finding: read its log (gh run view --log-failed), fix, push. - Hooks:
uv run pre-commit installinstalls commit-msg (commit-check), pre-commit (ruff) and pre-push (scripts/ci --fast). Claude Code also runs ruff after every edit and blocks a few dangerous commands (.claude/hooks/). - Never bypass hooks (
--no-verify).
Working in this repository
- uv for Python, npm only for the OpenSpec CLI:
uv sync && npm ci, thenuv run <tool>. GitHub CLI 2.100 or newer (gh issue create --type/--parent/--blocked-by). - Layout:
src/prepush_ci/(the tool, standard library only;core/without I/O),tests/(specs),openspec/(specs and changes),skills/(the agent skill the tool ships),scripts/ci(the full check),.claude/(hooks and skills for agents working on this repository). - No runtime dependencies unless an OpenSpec change argues for one:
uvx prepush-cishould start fast and install nothing. - Decide and proceed: make implementation decisions (file layout, internal APIs, test structure) yourself, with a one-line rationale in the commit body. Pause only when a decision changes the intent's scope or contradicts a spec.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

