ADR Index
Purpose #
Every Architecture Decision Record (ADR) in the project, with a one-line summary and a link. ADRs live at .docs/docs/architecture/decisions/.
Conventions #
- Numbering is monotonically increasing. Do not renumber existing ADRs even if gaps appear.
- Status:
Proposed,Accepted,Deprecated,Superseded. - Template: .docs/docs/architecture/decisions/0000-template.md.
- When you introduce a non-trivial design choice, propose an ADR before writing the code (CLAUDE.md §7.5).
Index #
| # | Status | Title | One-line summary |
|---|---|---|---|
| 0001 | Accepted | Runtime + language | Node.js 20+ with TypeScript; ESM-only; no Go/Rust/Python/Bun/Deno. |
| 0002 | Accepted | Monorepo tooling | pnpm workspaces + Turborepo + Changesets. |
| 0003 | Accepted | License | Apache-2.0 across all packages (drafted, not legally reviewed pre-v1.0). |
| 0004 | Accepted | Distribution | npm; @aidokit/* scope + unscoped aidokit CLI; alpha dist-tag pre-1.0; provenance from v1.0. |
| 0005 | Accepted | Adapter contract shape | TypeScript interface, 12 methods, methods return data (no IO), manifest + behaviour split. |
| 0006 | Accepted | Stack-pack contract shape | 4 required methods + 1 optional; packs contribute data; sibling of adapter. |
| 0007 | Accepted | MCP catalog shape | TS const array; restricted OR-only trigger grammar; securitySensitive non-bypassable. |
| 0008 | Accepted | Prereq install policy | Detection only — aidokit never auto-installs prereqs. |
| 0009 | Accepted | Argument parser | Commander. |
| 0010 | Accepted | Prompts library | @clack/prompts. |
| 0011 | Accepted | Schema library | Zod re-exported from @aidokit/core/schema. |
| 0012 | Accepted | Spec↔core type reconciliation | Shipped @aidokit/core types are authoritative; adapter-contract.md §6/§8 patched to match. |
| 0013 | Accepted | SkillTemplate enrichment | Add description + allowedTools to SkillTemplate; @aidokit/base-skills populates them. |
| 0014 | Accepted | ProjectContext parsed manifests | ProjectContext.parsedManifests carries real package.json scripts for stack-pack consumption. |
| 0015 | Accepted | graphify MCP catalog entry | Add graphify (PyPI graphifyy) as catalog entry #8; opt-in, security-sensitive, Python prereq. |
| 0016 | Accepted | Copilot adapter in v1.0 | Add @aidokit/adapter-copilot at Minimum conformance to v1.0; Standard deferred to v1.x. |
| 0017 | Accepted | Strict-tier capability artifact | Strict-tier .aidokit/capabilities.json emitted by the CLI (not the adapter); read by D4 verifier and audit export. |
| 0018 | Accepted | aidokit verify facet umbrella | Pluggable facet runner under aidokit verify; five reserved facets (secrets, budget, deps, license, loop-cap) sharing .aidokit/policy.json. |
| 0019 | Accepted | MCP untrustedOutput flag | MCPDef.untrustedOutput?: boolean flags servers returning third-party content; emits quarantining-untrusted-output skill + MCP_QUARANTINE_SKILL_MISSING doctor finding. |
| 0020 | Accepted | ALWAYS_ON_SKILLS invariant | A subset of BASE_SKILLS always emits regardless of conformance tier; computeFilePlan dedupes by id. Covers scratchpad-hygiene, reset-context, quarantining-untrusted-output. |
How to write a new ADR #
See how-to-guides/how-to-write-an-adr.md and the template at .docs/docs/architecture/decisions/0000-template.md.
Required sections: Summary, Context, Decision, Consequences (Positive / Negative / Neutral), Alternatives considered, Implementation notes, Validation, References.