tdd-ship

name	tdd-ship
description	Default delivery workflow for tracked repo changes. Use when the user asks to fix, add, implement, update, refactor, rename, bump, tweak, or otherwise end in a file change. Do not use for read-only questions or investigation.

TDD → Issue → PR → CI → Merge

This is how tracked changes ship in this repo: issue -> branch -> red/green TDD -> review -> PR -> CI -> auto-merge.

REQUIRED SUB-SKILL: Use agent-delivery-contract. Normalize the target, scope, authority, terminal state, verification, and failure policy before the first mutation. This repo authorizes the default auto-merge path below unless the user requests a different terminal state.

When this applies

Apply the full pipeline when the request modifies a tracked file: code, config, docs, tests, or deploy files.

Skip it for pure questions, explanations, research, or read-only investigation ("how does X work?", "where is Y defined?", "explain this") — answer those directly. If a question turns into "…so fix it," the pipeline kicks in at that point.

If the user explicitly asks to edit locally without a PR, honor that scope but keep the branch, tests, and reporting discipline.

The pipeline

Run these in order.

1. Open a GitHub issue

Capture the intent before writing code.

gh issue create --title "<concise imperative title>" \
  --body "<what & why; acceptance criteria as a checklist>" \
  --label "ready-for-agent"

Keep the title in the repo's voice (fix:/feat: style matches commits). Always apply ready-for-agent; the issue body needs context, file references, scope, acceptance criteria, and test expectations.

2. Branch off an up-to-date main

Never commit to main directly, and never start from a stale base. Sync with origin/main first, then branch:

git fetch origin
git switch main && git pull --ff-only
git switch -c <type>/<short-slug>-<issue#>   # e.g. feat/share-internal-123

If you're already on a feature branch for this work (e.g. a worktree where you can't git switch main), stay on it — but rebase it onto the freshly fetched base before you write anything: git fetch origin && git rebase origin/main. Starting from an up-to-date main keeps the diff clean and avoids merge conflicts when you push.

3. TDD — write the failing test first

• Red: add/modify a test that encodes the new behavior. Run it; confirm it fails because the behavior is missing (not because of a typo or import error).
• Green: write the minimum implementation to make it pass.
• Refactor: clean up code and test while keeping the suite green.

Match the repo's test conventions and run the gates locally before pushing — defer to the language skills for exact commands and patterns:

• Python / backend changes → follow python-dev (pytest needs source .env && make test; ruff + mypy + ty + pyrefly must pass).
• TypeScript / React / frontend changes → follow typescript-dev (vitest, eslint --max-warnings 0, prettier, tsc).

In a fresh worktree (no .venv, node_modules, or .env), run scripts/bootstrap-worktree.sh first and keep .venv/bin on PATH so the pre-commit and pre-push hooks find their tools. Do not print secret values from .env.

Push only after the relevant tests and type/lint gates pass locally.

4. Review and verify the diff

CI only re-runs the tests you just wrote, so the diff needs one independent check before it heads for auto-merge:

• Run the code-review skill on the working diff (medium effort) and fix confirmed findings before pushing.
• For user-facing changes (UI, API responses, CLI output), run the verify skill to see the change working in the running app — a green unit suite is not the same as the feature working.

Completion: every confirmed finding is fixed or explicitly dismissed with a stated reason. Don't chase speculative findings, and don't loop — one review pass, one fix pass, done.

5. Rebase on origin/main, open the PR, and queue it for merge

Rebase immediately before pushing, re-run gates if the rebase changes the base, push, open the PR, then queue auto-merge:

git fetch origin && git rebase origin/main
git push -u origin HEAD
gh pr create --fill --base main \
  --body "Closes #<issue#>\n\n<summary of the change and the test that backs it>"
gh pr merge --squash --auto

The Closes #<issue#> line is required. End the PR body with the standard trailer: 🤖 Generated with [Claude Code](https://claude.com/claude-code).

Always open PRs with auto-merge enabled (--auto). Branch protection uses a merge queue; do not pass --delete-branch with queued merges.

Do not bypass the queue with gh pr merge --admin or a direct push to main.

6. Watch CI and the merge queue

CI (.github/workflows/ci.yml) runs on every PR to main. Watch it:

gh pr checks --watch

If a check fails, read the logs (gh run view <run-id> --log-failed), fix the cause on the branch, push, and let CI re-run. Required checks are Lint & typecheck and Test & build; both must pass on the PR and merge queue.

7. Confirm the merge completed

Once CI is green, confirm auto-merge landed (gh pr view <pr#> --json state,mergedAt), confirm the issue closed, delete the remote branch if GitHub did not, and report the PR/issue numbers.

Reporting back

After merge, give the user a one-line summary with links: the issue, the PR, and confirmation that CI passed and the branch was deleted. If anything blocked the pipeline (flaky CI, a check that needs secrets, a merge conflict), surface it instead of silently stopping.

During execution, report only state transitions defined by agent-delivery-contract; do not narrate unchanged test or CI polling.

Guardrails

• Authorization to merge is built in — the user has opted into auto-merge on green CI for this repo, so you don't need to re-ask before each merge. But never force-merge past a failing or pending required check.
• One issue/PR per logical change. If a request bundles unrelated changes, split them so each PR stays reviewable.
• If the user explicitly says "just edit, don't open a PR" or is clearly working in a throwaway/experimental context, honor that and skip the pipeline for that request.