agentleFS
CapeOfGoodCodeCapeOfGoodCode/prepush-ci/AGENTS.md

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

The file

Files
AGENTS.md

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 Epic issues 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 label proposal and waits for a human.

    TypeUse it forUsual commit type
    Epicthe intent; its features are sub-issues (the first: #1)—
    Featurenew or changed behavior a user sees, improvements includedfeat
    Bugthe tool behaves differently from its spec or the intent; comes with a reproductionfix
    Refactoringa change inside the code that changes no behaviorrefactor
    Taskeverything without product behavior: docs, tooling, this harness, releaseschore, docs, test

    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 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.md starts with Issue: #<n>. Use the /opsx:* commands or the openspec-* skills.
  • The readme spec checks drift, not prose. Its requirements check only what can drift away from the code: every prepush-ci command 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 a docs: commit and no OpenSpec change. Bruce-lee sends the issue straight to turn:build, chuck-norris opens docs/<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.md or docs/ that says what prepush-ci does, prints or exits with names, in the change's design.md, the requirement in openspec/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 in openspec/specs/ always describe main.
  • npx openspec validate --all --strict must pass (part of scripts/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 of feat, 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 are docs: 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 with git commit --fixup=<sha>; before handing the branch back for review, fold them in with GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash origin/main and update with --force-with-lease. Fold down to logical commits, not to one. A reviewer sees what changed since the last round with git range-diff.
  • Every commit passes on its own. Rebase merge puts each commit on main, and git bisect needs 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 own docs: 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 on main.
  • Pull requests follow .github/pull_request_template.md, start with Closes #<n>, and carry a Proof section a human reads in one minute, in the form LOOP.md (Proof) gives for the change: a short demo when users see it, one line when it is internal, a decision note for request: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:decide or request:merge from its files and title, as .github/request-kinds.json lists them (a release, the rules in LOOP.md, AGENTS.md, .github/, .claude/ and scripts/ci, dependencies: decide). A request:decide pull request merges only on the human's approval; a request:merge one 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 latest main before handing over; update with git 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, the verify decision). 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 init in tmp_path), with hooks run by real git commit/git push. Never mock git. Start the CLI as sys.executable -m prepush_ci (in hook scripts too), never via uvx or PATH, 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 (uvx in 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% from tests/unit alone (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 an sh stub), including code the tests start as a subprocess through git. core/ does no I/O (a unit spec enforces it). Every # pragma: no cover carries 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-8 for it; otherwise it is the ANSI code page;
    • a spec that runs an sh script or needs the executable bit is POSIX_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 \n line endings (newline="\n");
    • deleting a file that a child process may still hold open tolerates PermissionError.

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 tag vX.Y.Z on main. A tag for the version already on main (e.g. a first upload that reserves the name) needs the human's yes in an issue instead. .github/workflows/release.yml refuses a tag that does not match the version, publishes to PyPI and creates the GitHub release.

Quality gates

  • scripts/ci is the full check: ruff, format, mypy --strict, pytest, OpenSpec validation. CI runs it, on Linux and Windows, on every ready pull request and again on main after each merge. scripts/ci --fast is 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 install installs 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, then uv 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-ci should 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.