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 (AGENTS.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. |
| 0021 | Accepted | Task-brief quality score | Deterministic scoreTaskBrief rubric (scope 20 / acceptance-criteria 30 / risks 15 / rollback 15 / test-plan 20; grades A–F) behind advisory aidokit task score. ROI #10. |
| 0022 | Accepted | Declarative model policy | Optional .aidokit/model-policy.json (Zod schema) validated by doctor --model-policy; aidokit recommends a model per task type but never selects/routes/invokes one. ROI #7 workaround. |
| 0023 | Accepted | Static goal-contract + run-plan emitter | buildGoalContract + aidokit goal draft/goal plan emit a goal contract and a documentation-only run-plan script. No model calls. ROI #1/#2 workaround. |
| 0024 | Accepted | Local-only project index | buildProjectIndex + aidokit index build write .aidokit/index.json from a read-only scan (files/exports/tests/docs). No network/model. ROI #19/#20 core. |
| 0025 | Accepted | Known-broken baseline | aidokit baseline capture/diff parse a caller-provided test-output file to snapshot and classify failures (pre-existing vs new). aidokit never runs the suite. ROI #12/#21. |
| 0026 | Accepted | PR packet + CI generator + team policy | aidokit pr packet, aidokit ci init --provider, and an optional additive team section in the verify policy schema. ROI #13/#14/#24. |
| 0027 | Accepted | task run pre-flight orchestrator |
aidokit task run composes score → goal draft → goal plan in one command and stops before the model. Tier-2 chain; autonomous runner remains a non-goal. |
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.