Shipping Work

A change is not done when the code works. It is done when the team understands why it exists, the implementation has been reviewed, the risk has been tested, the docs match reality, and the release can be verified.

The shipping loop

flowchart LR
  subgraph Human["Human work"]
    Plan["Plan and review"]
    Build["Build the smallest useful increment"]
    PR["Open a focused PR"]
  end
  subgraph Automation["Automation"]
    Verify["Run checks and review"]
  end
  subgraph Deploy["Deployment"]
    Ship["Deploy and verify"]
  end
  Plan --> Build
  Build --> PR
  PR -->|on push| Verify
  Verify -->|if approved| Ship
  style Ship fill:#dcfce7,stroke:#16a34a,color:#14532d

AI tools may help with implementation, but the engineer owns the plan, review, tests, and shipped behavior.

Definition of done

A change isn’t done when the code works. It’s done when someone else could understand it, trust it, and maintain it without you in the room. Check each box or note why it doesn’t apply.

Intent

• The PR description says what changed
• The PR description says why it matters
• The PR description says how to tell it worked

Scope

• The diff does one thing — the thing the ticket asked for
• The code follows the conventions already in the repo
• No unrelated cleanup, renames, or reformatting snuck in

Verification

• Automated checks pass (or the gaps are called out)
• Manual checks or review notes show it behaves as expected
• There’s proof it works, not just a claim that it does

Handoff

• Docs are updated if the change affects setup, usage, or behavior
• Config and rollback notes are current if the change needs them
• Known limitations or follow-ups are written down

Documentation baseline

Documentation is team infrastructure. It makes onboarding faster, review less fragile, audits easier, and operational memory durable after people move on.

Every repo should keep these files current.

File	Purpose	Required	Reference
README.md	Human onboarding, setup, usage, and links	Yes	GitHub README guide
humans.txt	Public credit, ownership, and human contact metadata for a site	Yes for public sites	humans.txt standard
llms.txt	LLM-facing index of important documentation and canonical context	Yes for public docs or product sites	llms.txt proposal
AGENTS.md or local agent guidance	Repo-specific instructions for code agents and contributors	Yes when agents operate in the repo	AGENTS.md format
CONTRIBUTING.md	Development workflow and contribution expectations	Yes for multi-contributor repos	GitHub contributing guidelines
CHANGELOG.md	Release history	Yes for versioned releases	Keep a Changelog and SemVer
ADRs	Significant technical decisions and consequences	Yes when a durable decision is made	ADR guidance and Nygard template

Technology defaults

Use the default stack for production systems and long-lived internal tools unless a project has an approved exception. Proofs of concept may use lighter tools when that lowers delivery friction.

Area	Default
Frontend apps	React
Full-stack React apps	Next.js
Content-heavy sites	Astro
Component development	Storybook
Backend services	Go
Frontend and full-stack language	TypeScript
Scripting and data work	Python
Durable relational data	PostgreSQL
Lightweight local or prototype data	SQLite
Cache and simple queueing	Redis
Container orchestration	Kubernetes
GitOps delivery	ArgoCD
Packaging	Helm
Infrastructure as code	Terraform
CI/CD	GitHub Actions
Observability	Prometheus and Grafana
Cloud	AWS
Secrets	1Password

Exceptions

Document every production exception in the repo setup notes. Record what was chosen, why the default did not fit, who maintains it, and what would trigger reconsideration. Verbal exceptions do not count.

Where to go next

• 00 — Team Operating Model — principles and maturity expectations
• 02 — Ownership and Systems — ownership, repos, vendors, and integration rules
• ATO — Delivery — review, release, deployment, and evidence workflow
• ATO — Environments — how changes promote through isolated tiers