/procoder

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: "3"

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 <sub>` — `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 <sub>` — `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 <sub>` — the project layer in `.procoder/backlog/`:

`milestone | epic | story | bug | seed <spec> | list | board | close`. 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 <sub>` — `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 <sub>` — `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 <sub>` — `new <title> | list | check` in

`.procoder/adr/`. Records are immutable: a changed mind supersedes, never rewrites. Check r