Skip to content

How to ship a change

A how-to guide. Goal: take a change from idea to tagged release. The skills drive each step; the team rules live in .procoder/github/WORKFLOW.md and are yours to edit.

Assumes Procoder is installed and the repository is onboarded. New here? Start with the tutorial.

flowchart TD
    S[1 spec] --> P[2 plan] --> T[3 track] --> B[4 branch and build]
    B --> TE[5 test] --> G{6 check} --> PR[7 PR]
    PR --> RV[8 answer every review thread] --> M[9 merge]
    M --> SP{10 close the sprint} --> REL{11 release}
    G -->|"any blocking finding"| B
    SP -->|"story unfinished or without evidence"| B
    REL -->|"version · changelog · tree · gate · suite"| B

Dotted arrows are refusals: the step that sends you back, and what it checks before it does.

1. Write the spec

/procoder:spec <feature>

The skill classifies the work first and says which path it took. Small, bounded changes to a flow that already exists skip the spec file entirely.

The skill runs the controller for you, and it blocks while a section is empty, an OPEN: question is unresolved, or an acceptance criterion is untestable.

2. Write the plan

/procoder:plan <feature>

Turns a COMPLETE spec into .procoder/plans/<feature>.md: Goal, Architecture, Constraints verbatim, and ## Task N: blocks carrying files, interfaces, and test-first steps.

Its controller blocks placeholders and tasks with no files or steps.

3. Track the work

For a project with a shape worth planning:

/procoder:backlog seed .procoder/specs/<feature>.md
/procoder:sprint open "<goal>"
/procoder:sprint pull <story-id>

seed makes an epic and one story per acceptance criterion. One sprint is active at a time.

For standalone work not born from a spec:

/procoder:todo add "<task>"

Same closing rigor, no project layer.

4. Branch and build

git worktree add ../<feature> -b <feature>

A worktree per feature is what .procoder/github/WORKFLOW.md prescribes. It is plain git — Procoder creates and removes nothing.

While you write, the write hook (PostToolUse) checks each file in the same turn and hands back the formatted result plus the domain findings. Use the index instead of grep:

/procoder:index find <symbol>
/procoder:index refs <symbol>
/procoder:index impact <file>

5. Run the suite

/procoder:test

Each detected ecosystem's canonical runner. NOT run is never green. With [test] policy = "block" in .procoder/config.toml, the suite joins the close controllers.

For a performance claim:

/procoder:perf

Compares against the saved baseline. Go only.

6. Clear the gate

/procoder:check

Formatting, hygiene, lint, secrets, docs, CI and infra rules — the same code path CI runs. Must be clean before a PR exists.

7. Open the PR

/procoder:pr

The skill summarises the real diff, fills the template from .procoder/github/, scrubs attribution, verifies the blast radius with procoder index impact, and shows you everything before gh pr create.

Keep the title at 72 characters or fewer — it becomes the squash-commit subject.

8. Answer every review thread

Every thread — human or bot, Copilot included — is either fixed (commit, push, reply saying what changed) or answered with a concrete reason. Resolve a thread only after that, never to clear the list.

9. Merge and clean up

/procoder:merge

Squash-merge when every check is green and every thread is answered, then delete the remote branch, delete the local branch, remove the worktree, and git fetch --prune.

Anything that escaped to a reviewer becomes a .procoder/github/LESSONS.md entry with the adaptation that closes its class — in the same PR.

10. Close the sprint

/procoder:backlog close story <id>
/procoder:sprint close

The story close refuses without checked criteria, recorded evidence, and a clean gate. The sprint close refuses while a committed story is neither done nor carried back with a reason, then scaffolds the retro. That retro is the price of the next sprint open.

11. Release

/procoder:release <version>

Verifies the version across [release] files, the changelog entry, a clean tree, the gate, and the suite — every failure listed at once. On success it prints the git tag command for you to run.

It tags nothing itself.

Common pitfalls

  • Do not skip procoder check because the write hook was quiet. The hook sees one file at a time; the gate sees the whole changed set, including staged junk and conflict markers in files you never opened.
  • Do not weaken an acceptance criterion to make a close controller pass. The refusal names a real gap; softening the criterion hides it.
  • Do not resolve a review thread to tidy the list. Resolve it because it is answered.
  • Do not treat a green write hook as a green suite. Formatting and tests are different questions.

Next