Review Checklist

Purpose #

The shared checklist every reviewer applies and every contributor self-applies before opening a PR. Distilled from CLAUDE.md, the specs, and the cardinal ADRs.

Pre-flight (contributor self-review) #

• [ ] PR title follows the feat(<pkg>): … / fix(<pkg>): … / docs: … / chore: … convention.
• [ ] PR body cites the spec section(s) read.
• [ ] PR body links to the task brief or Beads issue.
• [ ] Scope is a single package. Cross-package work is split into separate PRs.
• [ ] In-scope files only — no out-of-scope cleanup folded in.

Architectural #

• [ ] ADR present if the change touches: Adapter contract, StackPack contract, MCP catalog shape, runtime/language/tooling, distribution, security model. See how-to-guides/how-to-write-an-adr.md.
• [ ] No upward layer imports. Layer 1 never imports Layer 2 or 3; adapters never import stack packs.
• [ ] @aidokit/core has zero runtime deps on other @aidokit/* packages.
• [ ] No template engine sneaking in. Only {{varName}} interpolation via @aidokit/core.
• [ ] No YAML-as-code. Contracts and catalogs are TypeScript.
• [ ] No runtime plugin discovery / dynamic require.
• [ ] No LLM call anywhere in aidokit itself.
• [ ] No telemetry / phone-home / version-check ping.
• [ ] No auto-install of prereqs (ADR-0008).

Tests #

• [ ] Unit tests added or updated alongside the changed code.
• [ ] Integration test added or updated if emitted output changes.
• [ ] Conformance harness passes for the affected adapter / stack pack at its declared level.
• [ ] Determinism preserved — no timestamps, random ids, or set-iteration-order leaks.
• [ ] Coverage floors maintained: @aidokit/core ≥ 90%, adapters ≥ 80%, @aidokit/cli ≥ 70%.

Dogfood (post-Phase 8) #

• [ ] Dogfood byte-compare clean. If you touched @aidokit/adapter-claude-code or @aidokit/base-skills, the hand-built .claude/ was updated in lockstep.
• [ ] No file emitted outside the adapter's declared capabilityDeclarations.writesPaths.
• [ ] AD-STD-CAP-01 passes (declarations match actual child_process / fetch / http(s).request usage in source).

Versioning + distribution #

• [ ] Changeset present (.changeset/<slug>.md) for any behaviour change.
• [ ] Patch / minor / major chosen correctly: pre-1.0 minor allows breaking; post-1.0 strict semver.
• [ ] License declared Apache-2.0 on every published package.json.
• [ ] files allowlist in package.json includes only dist/**, README.md, LICENSE, NOTICE, CHANGELOG.md.

Documentation #

• [ ] Specs updated in .docs/docs/specs/* if the change is contract-relevant.
• [ ] ADR added (Proposed → Accepted) where required.
• [ ] Wiki updated if any of the load-bearing concepts / contracts / reference pages need to reflect the change.
• [ ] CHANGELOG.md entry under [Unreleased] for narrative work.
• [ ] > [!TODO] for any unknown the change introduces — never fabricated.

Security #

• [ ] If MCP-related: securitySensitive reflects real capability.
• [ ] If MCP-related: --yes does not bypass the confirmation for sensitive entries.
• [ ] If adapter-related: capability declarations are honest; AD-STD-CAP-01 green.
• [ ] No credentials, tokens, or env-var secrets embedded in emitted files.
• [ ] No reads outside the project root that weren't already part of the prereq probe.

Quality #

• [ ] Lint clean (pnpm lint).
• [ ] Typecheck clean (pnpm typecheck).
• [ ] Tests green (pnpm test).
• [ ] Build clean (pnpm build).
• [ ] No > [!TODO] left unflagged where you could have confirmed the answer.
• [ ] No commented-out code, dead imports, or unused exports.

What this is NOT #

• This checklist is intentionally broad. Many items will be N/A for a given PR — skip them honestly rather than rubber-stamping.
• Speed matters. If every item passes, the PR should review quickly. Reviewers blocking on style-only nits are doing it wrong.

Related Pages #

• contribution-guide.md
• code-standards.md
• testing-guidelines.md
• release-checklist.md
• ../tutorials/prepare-a-change-for-review.md
• CLAUDE.md §8 anti-patterns