Onboarding Guide

Purpose #

A concrete ramp from "I just cloned the repo" to "I have shipped a small change end-to-end" — tuned to aidokit's real artifacts.

Big Picture #

aidokit is precisely specified — design decisions live in .docs/, not in code review. The first three days are about reading; the rest is about practising the workflow that ships changes.

How It Works #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
gantt
  title Contributor onboarding plan
  dateFormat  X
  axisFormat %s
  section Read
  Setup (README, ROADMAP, CLAUDE.md)            :a1, 0, 1
  section Run
  Local CLI working (scaffold demo)             :a2, after a1, 1
  section Understand
  Architecture + contracts + concepts           :a3, after a2, 2
  section Ship
  Pick a task, draft ADR if needed              :a4, after a3, 1
  Land a small change with changeset            :a5, after a4, 3

Day 0 — Setup (≤ 30 min) #

1. Clone, install, build — see quick-start.md.
2. Read .docs/README.md, the v1.0 row of .docs/ROADMAP.md, and CLAUDE.md.
3. Skim CHANGELOG.md [0.5.0] and [Unreleased] (the v1.0 entry covers everything below).
4. Get oriented on the v1.0 user surface — read the three tier pages and pick the one matching your test project: Starter · Standard · Strict.
5. Skim the comparison page so you can explain where aidokit sits versus alternatives: aidokit vs. alternatives.
6. Read the privacy policy so you know what aidokit does and doesn't transmit: wiki/privacy/.

Day 1 — Local CLI working #

1. Run tutorials/scaffold-your-first-project.md.
2. Open the emitted .claude/ tree. Cross-reference against .docs/context/claude-workflow-kit-v4-base-part-3.md §§42–54.
3. Read .docs/ARCHITECTURE.md §§1–8. Stop at §8 (the aidokit init data flow).

Days 2–3 — Architecture and contracts #

1. Read .docs/ARCHITECTURE.md §§9–22.
2. Read the two central contracts: - .docs/docs/specs/adapter-contract.md (§§1–11, §§13–15) - .docs/docs/specs/stack-pack-contract.md (§§1–15)
3. Read .docs/docs/specs/conformance-levels.md §§3–6 + Appendix B.
4. Read .docs/docs/specs/mcp-catalog.md §§4–10.
5. Read concepts/dogfood-gate.md and concepts/three-layer-architecture.md.

Day 4 — Pick a task #

The work surface lives in .docs/ROADMAP.md §v1.0 In scope minus what is already shipped in CHANGELOG.md.

Open candidates as of v1.0 ship lane: - Multi-adapter polish around shared-docs deduplication. - --dry-run on init and sync (any gap). - Capability declarations verification across all adapters (AD-STD-CAP-01 is in; extend to AD-STD-CAP-* family). - aidokit search adapter|stack-pack. - Docs site scaffolding.

Day 5 — Propose or pick up an ADR if needed #

If your change touches any of:

• Adapter contract shape
• Stack-pack contract shape
• MCP catalog shape
• Runtime / language / monorepo tooling
• Distribution

… draft an ADR first. See tutorials/prepare-a-change-for-review.md and how-to-guides/how-to-write-an-adr.md.

Week 1 — Ship one change #

The full loop is documented in tutorials/prepare-a-change-for-review.md: brief, scope, code, tests, changeset, dogfood, conformance harness, PR.

Example milestones #

Diagram #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
gantt
  dateFormat  X
  axisFormat  Day %s
  section Setup
  Clone + install + read README/CLAUDE/ROADMAP :done, d0, 0, 1
  section Build muscle memory
  scaffold-your-first-project tutorial :a1, 1, 2
  ARCHITECTURE.md §§1-8 :a2, 1, 2
  section Contracts
  adapter-contract + stack-pack-contract :a3, 2, 4
  conformance-levels + mcp-catalog :a4, 3, 4
  section Pick & ship
  Pick a v1.0 task :a5, 4, 5
  Draft ADR if needed :a6, 5, 6
  Ship one change :a7, 5, 8

Common Mistakes #

• Skipping CLAUDE.md — it is read at every session start by AI tools and contains the source-of-truth ordering.
• Trying to fix multiple things in one PR. The repo runs a one-task-per-PR discipline (see contributing/review-checklist.md).
• Working from memory of the v4 kit. The v4 base parts are the de-facto reference; always re-open the relevant section before emitting kit-shaped content.

Checklist #

• [ ] Local build works.
• [ ] You can locate the spec for any contract you touch.
• [ ] You know whether your change needs an ADR.
• [ ] You know where your changeset will land (.changeset/<slug>.md).
• [ ] You know how to run the conformance harness for the package you touched (see tutorials/extend-an-adapter.md).

Related Pages #

• tutorials/scaffold-your-first-project.md
• tutorials/prepare-a-change-for-review.md
• concepts/three-layer-architecture.md
• concepts/dogfood-gate.md
• contributing/contribution-guide.md