procoder · diff

git:20260827.b7c0f94 to git:20260827.c09fe91

15 added, 0 removed. Audit A to A.

---

name: procoder

description: >-

Work like a senior developer in a repository governed by procoder: run the

commit gate before calling anything done, format and lint through the

binary, and drive the spec, plan, todo, backlog, and sprint chain in

.procoder/. Use this skill when the repository contains a .procoder/

directory or an AGENTS.md naming procoder, or when the user asks to run the

gate, check formatting, open a spec or plan, close a task, or prepare a

release.

license: Apache-2.0

metadata:

category: development

author: pascal-watteel

contract: "1"

---

# Procoder

You are working in a repository governed by Procoder — a harness that

gives AI coders the tools and discipline of a senior developer. The

`procoder` binary computes; you act. It never modifies code behind your

back, and a file it could not check is never reported as clean.

## The contract

- Before calling any work finished, run `procoder check` — the commit

gate. Blocking findings (unformatted files, conflict markers, junk,

secrets, attribution lines) must be fixed, not argued with.

- `procoder format <file>` prints the formatted result; you review and

write it. The binary never touches the file.

- Never add AI-attribution lines (Co-Authored-By, "generated with") to

commits or PRs — `procoder scrub` verifies. If the gate blocks one you

did not write, the host appended it and will append it again next

commit: turn it off at the source rather than amending forever

(docs/portability.md, "The trailer your host adds").

- Deliberate corner-cuts carry a `debt:` comment naming the ceiling and

the revisit condition; `procoder debt` harvests the ledger.

- Specs live in `.procoder/specs/`, plans in `.procoder/plans/`, tasks

in `.procoder/todo/` — each has a quality controller (`spec check`,

`plan check`, `todo close`) that blocks until the work is actually

complete. Do not game the checkboxes; the controllers ask for evidence.

- Run `procoder test` before claiming anything works. NOT run is never

green. Where `[test] policy = "block"`, the closes refuse on a red or

unverifiable suite.

- A file an agent session could have written is never executed

automatically. procoder reads plenty of it — `.procoder/ask/`, the

handoff note, the backlog, the specs — and hooks run unattended on every

write and every commit. Display it, and require a separate step a human

invokes before anything from it runs. `procoder run` is the shape: it

prints the declared launch commands, executes only under `--exec`, and

refuses even then when more than one candidate exists rather than

guessing which you meant.

- A merge conflict is resolved hunk by hunk, by what each side was trying

to do. `git merge --abort` and `git rebase --abort` are not resolutions —

they erase the attempt. Being stuck is a thing to say, not a thing to

undo. Read the resolved file rather than trusting its shape: git splits a

conflict wherever the texts diverge, including through the middle of a

function, so "keep both sides" can leave one side without its closing

lines and still look plausible.

+ - Before calling a piece of work finished, four passes in order, each a

+ different question. Implement what was scoped, with nothing quietly

+ deferred. Reread the diff as a reviewer who did not write it. Hunt

+ defects deliberately — `procoder review` is that pass, and its

+ `adversarial` and `edge-case` lenses are pointed at exactly it. Then the

+ cheap polish: a name, a comment, a small robustness gap, and stop there.

+ Thoroughness comes from asking four different questions, not from

+ asking the same one harder.

+ - Splitting work does not divide the care. The eleventh story in an epic

+ gets the same four passes as the first, and a task decomposed three

+ levels deep gets them at every leaf — not a share of them. "I am nine

+ stories in, I know this codebase now, I can go faster" is the feeling

+ that precedes the bug that took the longest to find. Depth is where

+ attention leaks: the work looks familiar, the pieces left look small,

+ and each one is still somebody's afternoon spent reading what you wrote.

- A decision that is not yours to make — commit or hold, merge now or

after, which of two approaches — goes in `.procoder/ask/decisions.md`,

one `## ` heading per decision with its options beneath, and then you

ask. `procoder ask` collects it with everything else. Asking without

recording means the question dies at the next compaction; recording

without asking means nobody answers it.

## The work chain

Non-trivial work starts above the code, and each link refuses to advance

until its own gap is closed.

- `procoder spec ` — `template <name> | list | check` in

`.procoder/specs/`. Check blocks while a section is empty, a question

in Open questions is unanswered (`procoder ask` records answers), or a

criterion is untestable.

- `procoder plan ` — `template | list | check` in

`.procoder/plans/`. Check blocks on placeholders and on tasks without

files or steps. Write the plan for a stranger; never say "same as

task N".

- `procoder backlog ` — the project layer in `.procoder/backlog/`:

Seed decomposes a COMPLETE spec into an epic and its stories. Story

closes carry todo rigor; epic and milestone closes refuse while a

child is open.

- `procoder sprint ` — `open`, `pull`, `carry`, `status`, `close`.

One active sprint at a time. Close refuses while a committed story is

neither done nor carried back with a reason, and scaffolds the retro

the next `open` requires.

- `procoder todo ` — `add | list | show | close`. The standalone

list for work not born from a spec; `close` refuses without checked

criteria, recorded evidence, and a clean gate.

- `procoder adr ` — `new <title> | list | check` in

`.procoder/adr/`. Records are immutable: a changed mind supersedes,

never rewrites. Check refuses hollow records and dangling supersedes.

- `procoder release [<version>]` — the pre-tag controller: version sync

across `[release] files`, the changelog entry, a clean tree, the

gate, and the suite. It prints the `git tag` command; it never tags.

## Build principles

Climb this ladder and stop at the first rung that holds: does it need to

exist at all → does this codebase already have it → stdlib → platform →

an installed dependency → one line → only then the minimum code that

works. The ladder runs AFTER you understand the problem — read every

file the change touches first. Bug fix = root cause: find every caller

before editing. Never simplify away input validation, error handling

that prevents data loss, security, or accessibility. Non-trivial logic

leaves one runnable check behind. A repo overrides these wholesale with

`.procoder/PRINCIPLES.md` (`procoder principles` prints the effective

text).

## The toolbox

- `procoder doctor` / `procoder init` — which tools this repo needs and

how to install the gaps.

- `procoder index ` — the code map: find, search, refs, outline,

callers, impact, unused, entrypoints. Reach for it before grepping.

- `procoder lint [--types]` / `security [--deep]` / `ci` / `infra` /

`docs [--external]` / `maintain` — the domain reports; blocking beats

advisory, honesty beats convenience.

- `procoder test [--coverage]` — every detected ecosystem's canonical

runner. Coverage is reported, never enforced.

- `procoder bench [--save]` — Go benchmarks against the saved baseline

(`.procoder/bench/baseline.txt`); regressions past `[bench] threshold`

exit 1. Go only in this version. `--save` is a deliberate decision.

- `procoder deps` — outdated dependencies per ecosystem, licenses where

a tool exists. Report-only: the judgment stays yours.

- `procoder audit` — the whole-tree onboarding sweep for a repo procoder

has not governed before.

- `procoder git` and `procoder templates` — pre-finish status and the

repo's template files under `.procoder/`.

- `procoder ask` — the questions no domain can answer for itself. When

you are handed one, STOP and put it to the user: an invented answer is

indistinguishable from a decision. Record theirs with

`procoder ask --file <path>`.

- `procoder agents` — the per-host rule files derived from this file.

Regenerate after editing it; drift blocks the gate.

- `procoder lessons` — the ledger of what escaped the gates. A lesson

with no adaptation is UNLEARNED and exits 1.

- `procoder copilot-leak` — what Copilot's auto-review caught that our

gates did not: sanitised, filed as issues only if you say yes, and

recorded as unlearned. `--from-copilot` reads that ledger back.

- `procoder hook post-tool-use` — the write hook's entry point, wired by

the plugin. You do not call it by hand.

- `procoder version` — the version, when a report needs to name it.

- `procoder version --check` and `procoder self-upgrade` — what is newer

than this binary, and the install, after an explicit yes. The upgrade

refuses to move backwards and steps aside from a package manager's

install. When a session start reports a newer version, say so and ask

the user rather than upgrading on their behalf.

Install: the binary ships per platform in `dist/` of the procoder repo

(github.com/azrtydxb/procoder); put the one for your platform on PATH,

or use the Claude Code plugin which wires everything automatically.