How to navigate the monorepo

Purpose #

Find the right package for a task in under two minutes. Companion to reference/package-index.md.

Decide which package to open #

You want to…	Open
Change the Adapter interface or `AdapterManifest`	`packages/core/src/types.ts`, `src/schema.ts` + draft ADR
Change the StackPack interface	`packages/core/src/types.ts`, `src/schema.ts` + draft ADR
Change the `AidoError` envelope or error codes	`packages/core/src/error.ts`
Change variable interpolation	`packages/core/src/interpolate.ts`
Change the conformance harness	`packages/core/src/conformance/`
Add or edit an MCP catalog entry	`packages/mcp-catalog/src/catalog.ts`
Add or change a prereq check	`packages/prereq-check/src/`
Add a base skill	`packages/base-skills/src/files/skills/` + `src/skills.ts`
Change the docs/ or agent-artifacts/ skeleton	`packages/shared-docs/src/files/`
Change a stack-pack detector or skill set	`packages/stack-pack-<name>/src/`
Change adapter-emitted Claude Code content	`packages/adapter-claude-code/src/files/` + hand-built `.claude/`
Change adapter-emitted Codex content	`packages/adapter-codex/src/files/`
Change adapter-emitted Copilot content	`packages/adapter-copilot/src/files/`
Change CLI commands, flags, prompts	`packages/cli/src/commands/`, `src/init/`

What lives where in `packages/cli` #

packages/cli/src/ is the largest package. Notable subtrees:

bin/aidokit.ts — the binary shim (one of the only files that calls process.exitCode).
run.ts — the Commander shell and global-flag normalisation.
exit-codes.ts — AidoError.code ↔ exit code map.
init/ — the 14-step init pipeline (selections.ts, build-project-context.ts, compute-file-plan.ts, write-files-staged.ts, manifest-reader.ts, resolve-adapter-instance.ts, …).
commands/ — one file per top-level command (init, doctor, sync, validate, …).
test/integration/init-emit.test.ts — the integration test that exercises the full pipeline.

What lives where in adapter packages #

Each adapter mirrors the same skeleton (per ADR-0005 §Implementation notes):

packages/adapter-<name>/
├── src/
│   ├── index.ts            # exports the const adapter
│   ├── manifest.ts         # AdapterManifest with capability declarations
│   ├── emit/
│   │   ├── agent-rules.ts
│   │   ├── engine-config.ts
│   │   ├── verbs.ts
│   │   ├── roles.ts
│   │   ├── skills.ts
│   │   ├── watchdog.ts
│   │   └── output-styles.ts
│   ├── mcp/
│   │   ├── install.ts
│   │   ├── remove.ts
│   │   └── list.ts
│   ├── lifecycle.ts        # postInstall, preSync, doctor
│   ├── files-resolver.ts   # locate dist/files/ or src/files/
│   └── files/              # template tree, tree-copied to dist/files/
├── test/                   # unit tests + conformance test
├── adapter.md              # at-rest manifest with YAML frontmatter
├── package.json
└── tsconfig.json

Discovering the runtime dep of a package #

cat packages/<pkg>/package.json | jq '.dependencies, .peerDependencies'

Or visually: every Layer 1 package has only @aidokit/core. Every Layer 2 package has only @aidokit/core. @aidokit/cli has everything. See reference/package-index.md for the full runtime-dep table.

Common pitfalls #

Starting in the wrong layer. If you find yourself wanting to import an adapter from a stack pack (or vice versa), stop — orchestration goes in @aidokit/cli.
Editing dist/files/ — regenerated. Edit src/files/.
Searching outside packages/ for runtime code. scripts/, agent-artifacts/, .docs/, docs/ are not shipped code.