Prepare a Change for Review

Purpose #

The full per-PR loop from "I picked up a task" to "PR ready for review": brief, scope, code, tests, changeset, conformance, dogfood, and the PR checklist.

Big Picture #

The repo runs a one-package-per-PR discipline (CLAUDE.md §9.2). Cross-package refactors are separate PRs. Every behaviour-changing PR needs a changeset, tests, and (where applicable) ADR + dogfood + conformance.

How It Works #

1. Confirm scope #

• Open the task brief in agent-artifacts/task-briefs/ or the matching Beads issue.
• Identify the single package the task names.
• List the in-scope files. If you're tempted to touch a second package, stop and ask the maintainer; that's a separate PR.

2. Read the relevant spec section #

Cite a section in your PR. The repo's source-of-truth ordering from CLAUDE.md §9.3:

1. v4 kit base parts
2. specs in .docs/docs/specs/
3. ADRs
4. README / ROADMAP / ARCHITECTURE
5. predecessor kit versions
6. Claude Code official docs (for Claude Code primitives)
7. user instructions
8. general knowledge

If a v4 base doc conflicts with a spec, flag the conflict as > [!TODO] and ask. Do not silently pick.

3. Decide if you need an ADR #

You need an ADR for changes touching:

• Adapter contract shape
• Stack-pack contract shape
• MCP catalog shape
• Runtime / language / monorepo tooling
• Distribution
• Anything else genuinely architectural

Use the template at .docs/docs/architecture/decisions/0000-template.md. Numbering is monotonic; do not reuse.

4. Write code + tests #

• Co-locate unit tests with source.
• Add an integration test if your change affects emitted output.
• Run the conformance harness for the package you touched (pnpm --filter @aidokit/<pkg> test).
• If you touched @aidokit/adapter-claude-code or @aidokit/base-skills, also update the hand-built .claude/ and re-run the dogfood byte-compare.

5. Add a changeset #

Every PR that changes published behaviour:

pnpm changeset

Choose: patch / minor / major. Pre-1.0, minor allows breaking changes (ADR-0004 §4). Commit the generated .changeset/<slug>.md.

6. Update documentation #

• Spec in .docs/docs/specs/* if you changed a contract.
• ADR added (Proposed → Accepted).
• CHANGELOG.md entry under [Unreleased] for narrative work (Changesets generates per-package CHANGELOGs at release time; the root narrative survives as a curated overview).
• Wiki page(s) updated if you affected an architecture, concept, or contract documented here.

7. Run the full local verification #

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Then the targeted runs:

pnpm --filter @aidokit/<the-package-you-touched> test
pnpm --filter aidokit test test/integration/init-emit.test.ts   # if emitted output affected

For dogfood:

mkdir /tmp/dog && cd /tmp/dog && git init
node /path/to/aidokit/packages/cli/dist/bin/aidokit.js init --adapter claude-code --stack node-ts --yes
diff -r /path/to/aidokit/.claude ./.claude

Should be empty.

8. Self-review against contributing/review-checklist.md #

The shared checklist. The high-bar items:

• ADR present if required.
• Changeset present.
• Dogfood byte-compare clean (post-Phase 8).
• No template engine sneaking in.
• No upward layer imports.
• No LLM call, no telemetry, no auto-install of prereqs.

9. Open the PR #

Title:

feat(<package>): <short imperative summary>
fix(<package>): ...
docs: ...
chore: ...

PR body should:

• Link to the task brief / Beads issue.
• Cite the spec section(s) read.
• Note ADR added / spec updated.
• Note any intentional dogfood-compare reference update with rationale.
• Note any open follow-ups.

Example PR loop #

A contributor wants to add a new check to the conformance harness:

1. Spec section: .docs/docs/specs/conformance-levels.md Appendix B.1 for the existing check ids.
2. Spec change: add the new check id to Appendix B (append-only).
3. Code: add the predicate to packages/core/src/conformance/checks.ts.
4. Tests: unit test against synthetic fixtures from Appendix A.
5. Update @aidokit/adapter-claude-code and other adapters if they fail the new check; if intentional gap, document in manifest.gaps.
6. Changeset: minor bump for @aidokit/core (new check is additive); patch for affected adapter(s).
7. Wiki: update reference/conformance-reference.md.
8. PR.

Common Mistakes #

• Touching multiple packages in one PR. Split.
• Shipping a behaviour change without a changeset. CI will eventually catch this; reviewers will catch it sooner.
• Skipping the spec update. Drift between code and .docs/docs/specs/* is a CI gate (when it lands per CLAUDE.md §9.2).
• Auto-progressing a PR after one approval without re-running the full local verification. The dogfood gate is a permanent CI gate; if you skipped local, CI will block.
• Editing dist/ files directly. They are generated.

Checklist #

• [ ] Scope is a single package.
• [ ] Relevant spec section cited in PR body.
• [ ] ADR present if architectural.
• [ ] Tests added or updated; conformance harness green.
• [ ] Dogfood byte-compare clean (if adapter-claude-code or base-skills touched).
• [ ] Changeset filed.
• [ ] CHANGELOG / wiki updated as needed.
• [ ] Local lint + typecheck + test + build green.

Related Pages #

• ../contributing/contribution-guide.md
• ../contributing/review-checklist.md
• ../how-to-guides/how-to-write-an-adr.md
• ../how-to-guides/how-to-run-tests-and-byte-compare.md
• CLAUDE.md §9