procoder: Instructions file for Codex

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.