Contributing to aidokit

Thanks for considering a contribution. aidokit is pre-alpha; this guide will grow as the project matures. For the design context behind any decision, read .docs/ARCHITECTURE.md and the relevant spec under .docs/docs/specs/.

1. Status and scope

aidokit is in Phase 0 of the v0.1 release. The repo is being hand-built up to the point where aidokit init can re-emit the repo's own .claude/ directory (the dogfood gate — see ARCHITECTURE.md §20).

Until v0.1 lands, contributions are limited to:

• Repo bootstrap (workspace, tooling, CI)
• The @aidokit/core contract package
• The @aidokit/adapter-claude-code reference adapter
• The @aidokit/stack-pack-node-ts reference stack pack
• The @aidokit/cli shell with only the init command
• Documentation, specs, and ADRs

Out-of-scope work (Codex adapter, additional stack packs, aidokit doctor/sync/migrate, brownfield, Minimum/Strict conformance, marketplace) is deferred — see .docs/ROADMAP.md.

2. Prerequisites

3. Local setup

The workspace itself is not yet created. The commands below describe the intended developer experience once Phase 0 lands.

git clone <repo-url> aidokit && cd aidokit
corepack enable
pnpm install
pnpm build           # turbo-orchestrated build across all packages
pnpm test            # unit + integration tiers
pnpm test:e2e        # gated; requires a working `claude` install
pnpm lint            # ESLint + Prettier check
pnpm typecheck       # tsc --noEmit across the workspace

4. Branching and PR workflow

• main is the integration branch. It is always green.
• Feature work happens on short-lived branches named <initials>/<slug> (e.g., gj/adapter-emit-pipeline).
• Open a draft PR early; mark it ready for review when CI is green and a changeset is attached.
• PRs squash-merge by default. Keep the squash commit message conventional (feat(cli): ..., fix(core): ..., docs: ..., chore: ...).
• Breaking changes require an ADR (see §6) and a changeset of type minor (pre-1.0) or major (post-1.0).

4.1 What lands in a PR

A non-trivial PR includes, at minimum:

1. The code change.
2. Co-located unit tests.
3. Integration test coverage if the change crosses package boundaries.
4. Spec or doc updates in the same PR (no drift between .docs/docs/specs/ and code).
5. A changeset entry (pnpm changeset).
6. CHANGELOG updates land automatically from changesets at release time — do not edit CHANGELOG.md directly except for hand-curated narrative entries pre-v0.1.

4.2 What gets rejected

• Speculative features outside the current milestone's In-Scope list.
• Template engines, runtime plugin discovery, LLM calls from aidokit — see AGENTS.md §8.
• New direct child_process.spawn calls outside the shared shell helper in @aidokit/core.
• Cross-layer imports (adapter ↔ stack-pack, or anything upward through the layer graph).
• Coverage regressions below the targets in ARCHITECTURE.md §18.5.

5. Testing conventions

Rules:

• No filesystem, network, or shell access in unit tests.
• Integration tests run in os.tmpdir() and clean up after themselves.
• Each integration test is independent — no shared mutable state.
• Snapshot updates require a comment explaining why the snapshot moved.

6. ADRs (Architecture Decision Records)

Architecture-relevant choices live in .docs/docs/architecture/decisions/.

• Use 0000-template.md as the starting point.
• Numbers are monotonically increasing. Gaps (0003, 0004, 0006) are reserved; do not renumber.
• An ADR captures the decision, the context, the alternatives considered, and the consequences. It is not a design doc — specs are.
• Propose the ADR in a draft PR before writing implementation code. Reviewers should push back on the decision in the ADR PR, not on the implementation PR.

7. Working with .docs/

The on-disk path is .docs/ (hidden). Public docs reference paths as docs/. This is an intentional Phase-0 choice — the dot prefix keeps design docs out of the published package surface. See AGENTS.md §2 for the full note.

When editing docs:

• Cross-reference by file path and section number (.docs/ARCHITECTURE.md §12).
• Keep numbered section headings stable. Adding sections at the end is preferred over inserting and renumbering.
• No emoji in spec or ADR content. Plain prose, tables, fenced code blocks.

8. Reporting issues

For now, file issues against this repo. Include:

• aidokit --version (once published).
• node --version, pnpm --version, OS + arch.
• The command you ran and the full output (--verbose if applicable).
• What you expected vs what happened.

For security issues, do not open a public issue. Email the maintainer (address to be published in SECURITY.md at v1.0).

9. Code of conduct

Be kind. Disagree on substance, not on people. Reviewers are doing you a favour by spending attention on your PR; reciprocate when you review someone else's.

10. License

By contributing, you agree that your contributions are licensed under the Apache 2.0 License (license file to be added before v0.1 publish).