aidokitwiki
User Docs Wiki

Contribution Guide

Purpose #

The single starting point for anyone contributing to aidokit. Distills CLAUDE.md, CONTRIBUTING.md, and the relevant specs into a per-PR workflow.

Read these first #

  1. CLAUDE.md — project rules; read at every session start.
  2. .docs/README.md, .docs/ROADMAP.md, .docs/ARCHITECTURE.md — orientation triad.
  3. The contract relevant to your work: .docs/docs/specs/adapter-contract.md, .docs/docs/specs/stack-pack-contract.md, .docs/docs/specs/cli-reference.md, .docs/docs/specs/mcp-catalog.md, .docs/docs/specs/conformance-levels.md, .docs/docs/specs/security-model.md.

Rules at a glance #

From CLAUDE.md:

  1. aidokit makes zero LLM calls. No telemetry. No phone-home. No auto-install of prereqs.
  2. Adapters and stack packs are siblings — they never import each other; only @aidokit/cli consumes both.
  3. No template engines (Handlebars/EJS/Nunjucks/Mustache). {{varName}} interpolation only; complex emission is programmatic.
  4. No YAML-as-code, no runtime plugin discovery. Contracts are TS interfaces; catalogs are TS const arrays.
  5. Three-layer architecture with strict downward dependencies. @aidokit/core has zero @aidokit/* runtime deps.
  6. Read-before-write everywhere. No file overwritten without diff + confirmation.
  7. Migrations are first-class. Every breaking change ships with aidokit migrate.
  8. Dogfood gate is permanent — the adapter's emitted .claude/ must byte-equal the repo's hand-built .claude/.

Per-PR workflow #

The full loop is in tutorials/prepare-a-change-for-review.md. Summary:

  1. Confirm scope — one package per PR. Cross-package refactors are separate PRs.
  2. Cite the spec section in your PR body. Source-of-truth ordering from CLAUDE.md §9.3.
  3. Draft an ADR if the change touches a contract / runtime / monorepo / MCP shape (how-to-write-an-adr.md).
  4. Write code + tests — co-located unit tests, integration test if emitted output affected, conformance harness in CI.
  5. Update specs / ADR / wiki in the same PR.
  6. File a changeset (pnpm changeset) for any behaviour change.
  7. Run dogfood byte-compare if you touched @aidokit/adapter-claude-code or @aidokit/base-skills.
  8. Self-review against review-checklist.md before opening.

Local setup #

getting-started/quick-start.md covers it. TL;DR:

git clone <repo>
corepack enable
pnpm install
pnpm build
pnpm test

Code conventions #

See code-standards.md. Highlights:

Doc conventions #

See documentation-standards.md. Highlights:

What to do when stuck #

From CLAUDE.md §9.4:

  1. Search the kit context files (.docs/context/) — the answer is usually there.
  2. Then check the spec files (.docs/docs/specs/).
  3. Then check the ADRs.
  4. Then ask the maintainer with the specific question, the sources you consulted, and the candidate answers.

Anti-patterns to refuse #

From CLAUDE.md §8:

If a request asks for any of these, push back politely and cite the source.

Non-goals (push-back list) #

From CLAUDE.md §11: LLM calls, telemetry, daemon mode, replacing the user's AI coding CLI, auto-progression between tasks, project-management suite, IDE plugin, enterprise SaaS.