repo root

CONTRIBUTING.md

CONTRIBUTING.md

Contributing to Son of Anton

Thanks for your interest. Son of Anton is a delivery orchestrator — the codebase is the same tool it uses to ship itself, so the best way to understand a contribution is to run the workflow end to end at least once before changing it.

New here? Read How Son of Anton Works — A Newcomer’s Mental Model first. It builds the mental model (no prior knowledge assumed) and maps every concept to where it lives in the code, so the rest of this guide makes sense.

By participating, you agree to abide by our Code of Conduct. New here or contributing through a course? It opens with a short note for you.

Prerequisites

Setup

git clone https://github.com/cesarnml/son-of-anton.git
cd son-of-anton
bun install
bun run ci          # format check + lint + tests — should all pass on a clean clone

Repo layout

tools/delivery/     core orchestrator logic (TypeScript)
scripts/            bun entry points (deliver.ts, closeout-stack.ts, etc.)
tests/              bun:test test suite
docs/template/      delivery workflow docs the orchestrator reads at runtime
  delivery/         orchestrator internals: TDD workflow, PR templates, review templates
  overview/         start-here.md — read this before working on orchestrator behavior
.agents/            agent-facing skills and delivery state
  skills/           Claude Code skills used in orchestrated delivery
notes/              design stance docs and proposals (public/ is checked in)

Dev commands

CommandWhat it does
bun run formatBiome + Prettier — run this before every commit
bun run verifyFormat check + lint (no writes)
bun run ciFull check: verify + tests
bun testTests only

Format before you stage. The CI enforces it. If you commit without formatting first, the next CI run rewrites the file and leaves a dirty tree.

Making a change

  1. Read docs/template/overview/start-here.md before touching orchestrator behavior. It describes the four gates and how delivery state flows.
  2. Fork the repo and create a branch from main.
  3. Make your change. For anything touching orchestrator logic, add or update a test in tests/.
  4. Run bun run format, then bun run ci. Fix anything that fails.
  5. Open a PR.

Commit style

Conventional Commits: type(scope): description.

Common types: feat, fix, docs, chore, refactor, test.

feat(tdd): add refactor-review subagent gate
fix(reconciliation): handle missing ledger rows on skipped tickets
docs(template): clarify post-red trigger conditions

Keep the subject line under 72 characters. No period at the end.

Pull requests

There is no formal review SLA. Smaller, focused PRs move faster.

What “advisory” means in this repo

Several tools in the orchestrator run as “advisory” subagents — they report findings but do not commit or modify files. If you are building on the orchestrator, keep that invariant: subagent runners are stdout-only. The primary agent adjudicates and decides what to apply.

Picking an issue (difficulty points)

Issues are labeled with a difficulty estimate on a Fibonacci scale, so you can match an issue to your comfort level. Higher is harder — it reflects breadth, design judgment, and how much of the codebase you have to hold in your head, not just lines of code.

LabelMeaning
difficulty: 1Trivial — a one-liner or typo fix.
difficulty: 2Easy — a focused change with a clear pattern to copy.
difficulty: 3Moderate — the sweet spot; some breadth or judgment.
difficulty: 5Involved — touches multiple areas or needs design care.
difficulty: 8Hard — architectural; not a first issue.

No issue is rated above 8. If you’re new, start with a 2 or 3 — that’s the sweet spot for a satisfying first contribution. Save the 5s and 8s for after you’ve landed one. Browse open issues by difficulty:

gh issue list --label "difficulty: 2"
gh issue list --label "difficulty: 3"

Getting oriented