Changelog

All notable changes to this repository are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. Pre-v1.0, breaking changes are allowed on minor-version bumps; see .docs/ROADMAP.md.

Once Changesets is wired up in Phase 0, the Unreleased section below will be generated from .changeset/*.md files at release time. Until then, narrative entries are hand-curated.

[Unreleased]

Added

• aidokit verify facet umbrella. New flags --secrets, --budget, --deps, --license, --loop-cap, --all-facets, plus --all (scan full tree vs staged diff) and --sarif (SARIF 2.1.0 output). Only --secrets is fully implemented at v1.x — 11 bundled patterns + Shannon entropy + path allowlist + // aidokit-ignore-secret inline override. The other four facets are reserved stubs that emit FACET_NOT_IMPLEMENTED warnings when enabled. Closes pain-point #19 (secrets / credential leakage). See ADR-0018.
• .aidokit/policy.json emitted at init across all three adapters (byte-identical fixture). Carries per-facet enable/severity/allowlist settings consumed by aidokit verify.
• MCP untrustedOutput flag. New optional untrustedOutput?: boolean field on catalog entries; set on context7, playwright, and chrome-devtools. New quarantining-untrusted-output skill emitted into every adapter's skill set. New aidokit doctor finding MCP_QUARANTINE_SKILL_MISSING warns when a flagged server is enabled without the skill. Closes pain-point #11 (prompt injection via MCP / tool output). See ADR-0019.
• .aidoignore file emitted at init (byte-identical across all three adapters). New @aidokit/core/aidoignore namespace exports loadAidoignore(projectRoot) returning a gitignore-style matcher. Default content covers .env*, secrets/, private keys (.pem / .key / .p12 / .pfx), and cloud-CI credential bundles. Closes pain-point #23 (code confidentiality); reinforces #19.
• .aidokit/model.lock emitted at init recording each declared adapter's cliVersion. New aidokit doctor --model-drift warns on MODEL_DRIFT_DETECTED or MODEL_LOCK_MISSING. AIDOKIT_DETERMINISTIC=1 produces canonical timestamps for hermetic CI fixtures. Closes pain-point #21 (model / CLI-version drift).
• Scratchpad-hygiene + reset-context skills, emitted into every adapter as part of the ALWAYS_ON_SKILLS set (so they ship at every conformance tier). Also adds aidokit doctor --hygiene with findings HYGIENE_NO_SCRATCHPAD, HYGIENE_STALE_SCRATCHPAD, HYGIENE_DRIFT. New @aidokit/core namespace taskState with TaskState, incrementIterations, readTaskState, listTaskIds. The iterations field on task state foundations the loop-cap facet. Closes pain-point #2 (context poisoning); reinforces #15 (skill atrophy). See ADR-0020.
• aidokit eval command — reads ## Acceptance criteria from a task brief at agent-artifacts/task-briefs/<id>.md. Each - [ ] > <command> checkbox runs via execFile (no shell), reports PASS/FAIL/MANUAL, exit 0 / 1 / 2 (NO_CRITERIA). Flags: --task <id>, --brief <path>, --json (via global flag). Closes pain-point #17 (evaluation difficulty).
• aidokit verify --budget implemented — reads the JSONL ledger at agent-artifacts/metrics/events.jsonl (produced by aidokit metrics), converts via usdPerMillionTokens policy field, compares to maxUsdPerTask. Findings: BUDGET_EXCEEDED, BUDGET_NEAR_LIMIT, BUDGET_LEDGER_MISSING. New policy fields: aggregateAcrossTasks, warnAtRatio, usdPerMillionTokens. Closes pain-point #4 (token cost explosion).
• aidokit verify --deps implemented — diffs package.json vs HEAD, flags new deps not in allowedScopes and not justified in any agent-artifacts/<id>/change-summary.md ## Dependencies section. Findings: DEP_NEW_UNAPPROVED, DEP_NEW_UNJUSTIFIED, DEP_VERSION_DOWNGRADE. New policy fields: requireJustification, flagDowngrades, trackedFiles. Closes pain-point #24 (dependency bloat).
• aidokit verify --license implemented — two-pass: SPDX-License-Identifier header detection in source files (when requireHeaders: true); node_modules/<dep>/package.json license lookup (no network). Findings: LICENSE_HEADER_MISSING, LICENSE_INCOMPATIBLE, LICENSE_FORBIDDEN, LICENSE_UNKNOWN. New policy fields: denySpdx (default GPL/AGPL family), requireHeaders, sourceGlobs. Closes pain-point #18 (license / IP contamination).
• aidokit verify --loop-cap implemented — reads iterations from agent-artifacts/<task-id>/state.json, compares to policy.verify.loopCap.maxIterations. Findings: LOOP_CAP_EXCEEDED, LOOP_CAP_NEAR_LIMIT (warn at 80% by default). New policy field: perTaskOverride. Closes pain-point #22 (agent runaway loops / cost spikes).
• Semantic doc-drift in aidokit doctor --drift — extracts markdown references (file links and code-symbol backticks) from .docs/**/*.md and validates against the live tree. Missing files and missing symbols emit doc-drift warn findings. New @aidokit/core namespace docGraph with extractRefs and buildSymbolIndex (regex over packages/*/src/**/*.ts exports — no TS compiler dep). New flag --no-semantic-drift opts out. Promotes pain-point #5 from structural to semantic drift coverage.
• Landing page redesign at docs-site/index.html with the new aidokit brandkit (logo, palette, type ramp, motion tokens).
• Prev/next topic navigation at the bottom of every documentation page (assets/doc-nav.js).
• docs-site/BRANDKIT.md documenting brand usage.

Changed

• aidokit doctor internal architecture refactored to a DoctorCheckSource registry under packages/cli/src/commands/doctor-checks/. No user-visible change; unblocks parallel landing of further doctor checks (model-drift, MCP quarantine, etc.).
• Security model spec promotes prompt-injection-via-MCP from "not named" to named threat T18 with declared mitigation (security-model.md §7.12). A follow-up section covers .aidoignore-based confidentiality.
• Breaking: aidokit init no longer defaults to claude-code when --adapter is omitted. Interactive shells are prompted to pick an adapter; non-interactive invocations (--yes or no TTY) must pass --adapter <name> explicitly. See ADR-0016.

Docs

• Remove "primary" framing for claude-code across README, ARCHITECTURE, CLAUDE.md, and wiki comparison page. The three first-party v1.0 adapters are presented as equal siblings.

Added (v1.0 — sessions 2–10)

• User-facing tier vocabulary. TierName (starter / standard / strict) exported from @aidokit/core as a 1:1 alias over the internal ConformanceLevel. aidokit init --tier <name> is the preferred flag; --conformance keeps working as back-compat alias. Interactive picker added. (A1, A2, A3, A5)
• Starter tier UX surface. Tier-aware verb emission: Starter ships /start + /ship; Standard/Strict keep the canonical three. Tier-aware CLAUDE.md template (agent-rules-starter.md). v4 base skills suppressed at Starter. Beads and MCP prompts suppressed at Starter (opinionated 60-second defaults). (B1, B2, B3)
• aidokit init safety + UX. Refuses to overwrite an existing install — detected via .aidokit/state.json or hand-rolled engine dirs; --brownfield opens the hand-rolled case. Elapsed-time print at end (Ready in N s.) with tier-aware Next step. (B5, B6)
• aidokit add adapter <name>. Non-destructive addition of a second/third adapter to an existing project, with --dry-run preview, tier-compatibility guard, and Strict-tier capabilities refresh. (D1+D2)
• aidokit doctor --drift. Adds stale-ADR and flat-file task-backlog checks to the doctor report. Configurable via --max-adr-age-days. (C7)
• aidokit verify [--capabilities]. Read-only install integrity check (template diff). --capabilities adds the D4 regex-based cross-check between .aidokit/capabilities.json and emitted hook scripts. (G5, D4)
• aidokit manifest --verify-capabilities. Manifest command surfaces the D4 verifier; exits non-zero on drift. JSON mode wraps results in the standard CLI envelope. (D6)
• aidokit metrics summary | export. Read-only CLI over the local-only MetricsLog. Both honour --since <Nm|Nh|Nd|Nw>; export optionally writes to --output <file>. (C3, C4)
• aidokit audit export --format soc2|eu-ai-act. Strict-tier evidence packet bundling .aidokit/capabilities.json, ADRs, change summaries, and blockers into a single markdown file. (C5, C6)
• @aidokit/core MetricsLog — append-only JSONL writer + reader
• aggregator. Discriminated union over five event kinds (scope.violation, context.reload, task.started, task.completed, task.tokens). Forward-compatible reader. (C1)
• @aidokit/adapter-claude-code watchdog wiring. New .claude/scripts/lib/emit-metric.mjs helper; validate-scope.mjs, track-command-failures.mjs, and inject-active-task.mjs emit events when AIDOKIT_METRICS=1. Zero telemetry by default. (C2)
• Strict-tier .aidokit/capabilities.json artifact. CLI-emitted projection of every declared adapter's manifest.capabilities. Emitted by init, sync, verify; consumed by D4 verifier and audit export. See ADR-0017. (A4-remaining)
• Canonical tasks-fallback module for the Starter flat-file task store (agent-artifacts/tasks.md). parseTasksFile, serializeTasksFile, markTaskDone, appendTask, countTaskRows. (B4)
• Compliance mapping documents. docs/compliance/soc2.md (CC1.4 → CC9.1) and docs/compliance/eu-ai-act.md (Articles 9, 12, 13, 14, 15). Both explicitly document scope limits and the fact that the mappings have not been reviewed by qualified counsel. (C5, C6)
• Privacy policy page. wiki/privacy/index.md documents the zero-telemetry promise auditably — what aidokit never does, what it does explicitly, the MetricsLog opt-in path, third-party privacy posture, and audit/verification methods. (C8)
• Per-adapter capability declarations reference (wiki/reference/adapter-capabilities.md) and per-tier landing pages (wiki/tiers/{starter,standard,strict}.md) and per-stack landing pages (wiki/stacks/{node-ts,node-js,python,react,go}.md), comparison page (wiki/compare/aidokit-vs-alternatives.md), Hall of Pain (wiki/hall-of-pain/index.md), supply-chain (wiki/supply-chain/signed-packages.md), health (wiki/health/index.md), devlog (wiki/devlog/). (F1–F6, D7)
• CI workflows. matrix.yml (14 curated {adapter, stack, tier} combos per-PR), matrix-snapshot.yml (nightly aggregate to health/matrix-status.json), publish.yml (Sigstore provenance), snapshot-accept.yml (weekly fixture refresh PR), quarterly-bump.yml (Q1/Q2/Q3/Q4 upstream-bump checklist issue). (H2, H3, G4, H4, H5)
• Byte-compare exception list. Named drift acceptance via packages/cli/test/integration/byte-compare-exceptions.json — files listed there are allowed to drift with a recorded rationale. (H1)
• scripts/wiki-to-html.py generalised. SECTIONS list moved to scripts/wiki-nav.json; script accepts --src, --out, --nav CLI args; documented for forks in scripts/wiki-to-html-README.md. (F8)
• ADR-0017 — Strict-tier capability artifact design.

Pre-v1.0 entries (week 1)

• @aidokit/adapter-copilot — third first-party adapter targeting GitHub Copilot CLI at Minimum conformance. Emits .github/copilot-instructions.md (auto-loaded by Copilot CLI workspace-wide) and a .copilot/ workflow tree (agents/, prompts/, skills/, config.json). Watchdog stop conditions and the seven-phase workflow are documented as prose since Copilot CLI has no hook mechanism — declared in manifest.gaps. CLI wiring extended: aidokit init --adapter copilot and --adapter claude-code,codex,copilot are both supported. See ADR-0016.
• AD-STD-CAP-01 conformance check: verifies declared capabilities match the adapter's actual source-level imports and call sites. Scans <packagePath>/src/**.ts (excluding tests and the manifest) for child_process imports and fetch(/http(s).request( calls and fails when the corresponding manifest.capabilities.shellCommands / networkEndpoints arrays are empty. Skipped when ConformanceOptions.packagePath is not supplied.
• SECURITY.md at the repo root — vulnerability reporting contact (george@aicenter.ae), 90-day coordinated disclosure window, supported versions policy (pre-1.0 and post-1.0), threat-model summary, capability boundaries (filesystem, shell, network, prereqs, --yes bypass rules), forward reference to v1.0 capability declarations, dependency-hygiene and supply-chain notes, and a hardening checklist for third-party adapter authors. Links to the canonical long-form threat model at .docs/docs/specs/security-model.md.

[0.5.0]

v0.5 alpha — broader command surface, three stack packs, full conformance harness with declared+verified levels, expanded MCP catalog, brownfield projects, and JSON output across the CLI.

Added

• CLI commands. aidokit doctor, aidokit sync, aidokit manifest, aidokit validate <file>, aidokit migrate v3-to-v4, aidokit new task|adr|skill, and the aidokit mcp list|add|remove and aidokit skills list subcommand trees. All commands honour --json, --dry-run, --quiet, --verbose, and --no-color from the root parser.
• --brownfield flag on aidokit init. Detects existing project state (stack signals, package manager, source-doc inventory) before emitting and surfaces it in the resulting manifest. Greenfield remains the default.
• @aidokit/stack-pack-node-js. Plain JavaScript sibling to the TypeScript pack. Detects package.json with no tsconfig.json; ships five JS-flavoured skills, context7 MCP suggestion, and ESLint / Prettier / Vitest validation commands.
• @aidokit/stack-pack-python. Second-language proof of the StackPack contract. Three detection signals (pyproject.toml, requirements.txt, .python-version) with high/medium/low confidence; five Python skills (python-conventions, pytest-patterns, type-hints, python-error-handling, pyproject-discipline); context7 MCP suggestion; ruff / mypy / pytest validation commands. Passes Standard conformance.
• Conformance harness in @aidokit/core. runAdapterConformance and runStackPackConformance runners, formatter, and makeProjectContext test helper. Verifies declared conformance levels against the shipped artifact surface so drift fails CI.
• Minimum and Strict conformance levels. Per-level check tables for adapters and stack packs. Adapters now declare their level in the manifest and the runner rejects mismatches. @aidokit/adapter-claude-code is bumped to Strict (adds the seventh role and the five output styles — checks AD-STR-01 and AD-STR-02).
• MCP catalog expansion. GitHub, Chrome DevTools, Postgres, and Filesystem entries added; catalog now ships seven entries. New exported constants on @aidokit/mcp-catalog for direct lookup.
• --json output mode. Every command emits structured JSON when --json is set, including mcp add|remove (formatMcpActionResult) and conformance reports. Closes the JSON gap flagged in Phase 7.
• ADR-0013 implementation. SkillTemplate carries optional description and allowedTools; @aidokit/base-skills populates them for all 18 skills; adapter-claude-code's emitSkills writes them as SKILL.md frontmatter with a synthesised fallback.
• ADR-0014 implementation. ProjectContext.parsedManifests is populated from package.json during buildProjectContext. Stack packs consume it (e.g., stack-pack-node-ts.suggestValidationCommands now emits commands only for scripts that exist).
• Plans. Seven Phase plan documents under docs/superpowers/plans/ (Phases 1–8) plus the v1.0 Codex adapter plan.

Changed

• adapter-claude-code conformance: standard → strict. Pre-existing Standard-level integrations remain compatible; new strict checks emit the seventh role and output styles.
• Adapter-level constraint guard. The CLI rejects selections that conflict with the declared adapter conformance level.
• @aidokit/core public surface re-exports the conformance runners, the formatter, and makeProjectContext for adapter and stack-pack authors writing their own conformance suites.

Security

• No new shell-execution paths. The single shared exec helper remains the only route to child_process. Strict conformance does not relax prereq-install policy (ADR-0008).

Pre-1.0 notes

• v0.5 may contain breaking changes relative to v0.1 — minor bumps allow breakage pre-1.0 per .docs/ROADMAP.md.
• The adapter contract and CLI surface remain unfrozen. v1.0 freezes both.

[0.1.0-alpha] — design phase

Added

• CLAUDE.md at the repository root — agent rules for AI-assisted development of aidokit itself.
• CONTRIBUTING.md — local setup, branching, testing, ADR, and PR conventions.
• CHANGELOG.md — this file.
• LICENSE — Apache License 2.0, canonical text (drafted, not legally reviewed).
• NOTICE — Apache-2.0 §4(d) attribution file with the project copyright line.
• ADR 0003 — License (Apache-2.0).
• ADR 0004 — Distribution (npm, scoped packages, Changesets, provenance from v1.0).
• ADR 0006 — Stack-pack contract shape (sibling to ADR-0005).
• ADR 0008 — Prerequisite install policy (no auto-install; codifies .docs/ARCHITECTURE.md §13.3 reference).
• ADR 0009 — Argument parser (Commander).
• ADR 0010 — Prompts library (@clack/prompts).
• ADR 0011 — Schema library (Zod re-exported from @aidokit/core/schema).
• ADR 0012 — Spec↔core type reconciliation (shipped @aidokit/core types are authoritative; adapter-contract.md §6/§8 patched to match — see Changed; SkillTemplate/ProjectContext/StackPackManifest gaps recorded as deferred follow-ups).
• ADR 0013 — SkillTemplate enrichment (description + allowedTools), Accepted and implemented: SkillTemplateSchema gained the two optional fields; @aidokit/base-skills populates them for all 18 skills (the v4 description and allowed-tools frontmatter); the adapter's emitSkills emits them as SKILL.md frontmatter, falling back to a synthesised description when absent.
• ADR 0014 — ProjectContext parsed manifests, Accepted and implemented: ProjectContext gained an optional parsedManifests field; the CLI's buildProjectContext parses the root package.json into it (tolerating a malformed file); @aidokit/stack-pack-node-ts's suggestValidationCommands uses it to emit validation commands only for package.json scripts that exist, falling back to the conventional set when no manifest is parsed.
• .changeset/initial-v0-1-alpha.md — the first changeset: a minor bump for all nine v0.1 packages, to be published under the alpha dist-tag.
• Workspace bootstrap (Phase 0b): root package.json, pnpm-workspace.yaml, turbo.json, tsconfig.base.json, eslint.config.js (flat config), .prettierrc + .prettierignore, .node-version, .editorconfig.
• Changesets configuration: .changeset/config.json, .changeset/README.md.
• CI workflow: .github/workflows/ci.yml — lint, typecheck, format-check, build, test on Node 20 across macOS, Linux, Windows.
• @aidokit/core package skeleton (Phase 0c):
• AidoError envelope class with canonical ErrorCode constants and --json serialiser (packages/core/src/error.ts + tests).
• interpolate() / listVariables() helpers for {{varName}} substitution (packages/core/src/interpolate.ts + tests).
• Zod schemas for AdapterManifest, StackPackManifest, CapabilityDeclarations, MCPDef, PrereqMeta, PrereqStatus, SkillTemplate, ValidationCommand, DetectionResult, EmittedFile, ShellCommand, plus primitive enums (OS, Arch, ConformanceLevel, RoleName, SpecVersion) — exported from the @aidokit/core/schema subpath per ADR-0011 (packages/core/src/schema.ts + tests).
• Behavioural interfaces (Adapter, StackPack, ProjectContext, DetectContext, PrereqDef, DoctorCheck, SyncPlan, InstalledMCP) and the assertNever exhaustiveness helper (packages/core/src/types.ts).
• @aidokit/shared-docs package skeleton:
• getDocsSkeleton(ctx) and getArtifactsSkeleton(ctx) async emitters returning EmittedFile[] per .docs/ARCHITECTURE.md §11.
• Template tree under packages/shared-docs/src/files/ covering the 14 docs/ files and 7 agent-artifacts/ directory READMEs. v4 kit content ported (kit Part 2 §23-24): each docs/ file carries its real purpose blurb, owner note, and v4 required-section headings as a fill-in skeleton; each agent-artifacts/ README documents the directory's owner role, the correct v4 file-naming convention (<bd-id>-<slug>.md etc.), and the governing skill. The earlier placeholder file-naming (T-0042--…) and the invented monitoring/ file list were corrected to match v4.
• files-resolver module that locates dist/files/ or falls back to src/files/ so the package works in both built and source-tree layouts.
• scripts/copy-files.mjs post-tsc step that copies src/files/ → dist/files/ (tsc does not emit non-TS files).
• Co-located unit tests for the resolver, vars helper, and both emitter functions.
• @aidokit/mcp-catalog package:
• Three v0.1 MCP entries (Context7, Beads MCP, Playwright) per ROADMAP scope.
• evaluateTrigger / evaluateTriggers with the five canonical tokens (always, never, stack.hasFrontend, detect.githubRemote, beadsEnabled) per .docs/ARCHITECTURE.md §12.2.
• suggestMCPs(ctx, { extraIds }) — trigger-driven suggestions plus explicit opt-in; security-sensitive entries never auto-suggest.
• resolveInstall(mcp, adapterName) — per-adapter install resolution with a clean MCP_INSTALL_FAILED error envelope for unsupported adapters.
• Tests validate every catalog entry against MCPDefSchema so a typo'd entry fails CI before publish.
• @aidokit/prereq-check package:
• Four PrereqDef entries (Node ≥ 20, Git, Claude Code ≥ 2.1.32, Beads — optional) with per-OS install hints for macOS, Linux, and Windows.
• runPrereqChecks() runs every detector in parallel and classifies each result as pass / outdated / missing.
• formatPrereqReport(results, { os }) produces the plain-text table the CLI surfaces during the prereq stage, with OS-appropriate install hints only for the prereqs that need them.
• allRequiredOk() predicate for the CLI's "should we continue?" branch.
• Local runCommand / probeVersion exec helpers (timeout-bounded, no-shell-interpolation execFile). Will promote to @aidokit/core/exec when @aidokit/cli also needs to shell out (e.g. for claude mcp add).
• Minimal semver helpers (parseSemver, compareSemver, satisfiesMinVersion) — just enough for min-version checks, no full-semver dependency.
• Per ADR-0008: detection only. The package never invokes an installer.
• @aidokit/stack-detect package:
• createDetectContext({ projectRoot, os }) builds a DetectContext implementation that honours the safety contract from .docs/docs/specs/stack-pack-contract.md §7.1 (no shell, no network, path-escapes treated as "not found").
• Built-in support for package.json (parsed JSON); other manifests (pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile) return { raw, format } for the calling stack pack to parse.
• manifestHasDep(name) covers v0.1's package.json use case across all four dep buckets.
• Tiny zero-dep glob: literal paths, *.ext, **/*.ext, **/<basename>. Skips node_modules/.git/dist and friends by default. Throws a clean BAD_INVOCATION for patterns beyond this subset.
• runDetectors + composeStackInfo + detectStacks orchestrate stack-pack detection in parallel, sort matches by confidence, and hoist hasFrontend from any pack's extras.
• @aidokit/stack-pack-node-ts package — first concrete stack pack:
• manifest declares name: 'node-ts', conformance: 'standard', languages: ['typescript', 'javascript'].
• detect(ctx) combines tsconfig.json presence and a typescript dependency in any of the four package.json deps buckets to emit high (both signals), medium (one), or none (neither). The result's extras always carries { hasTsConfig, hasTsDep } for adapter UI.
• suggestSkills(ctx) contributes five <REVIEW REQUIRED>-marked SkillTemplates (typescript-conventions, vitest-patterns, esm-imports, error-envelope-conventions, package-json-discipline) with {{projectName}} interpolation.
• suggestMCPs(ctx) returns ['context7']; broad triggers like stack.hasFrontend remain catalog-driven (not pack-driven) per .docs/docs/specs/stack-pack-contract.md §12.
• suggestValidationCommands(ctx) derives the package manager from ctx.packageManagerLockfile (pnpm-lock.yaml, yarn.lock, bun.lockb, else npm) and emits lint, typecheck, test, format-check, and build commands with kind/speed/ciSafe set per §13. Each command is schema-validated in the test suite.
• Does NOT implement defaultArchitecturePattern — Node/TS has no single canonical layout (Strict-only contract gate per §15.4).
• @aidokit/adapter-claude-code package — first concrete adapter:
• manifest declares name: 'claude-code', cliTarget: 'Claude Code > =2.1.32', conformance: 'standard', and honest capabilityDeclarations(write globs,claude mcp …/bd initshell prefixes, no network calls).adapter.md carries the at-rest YAML form.
• All twelve Adapter contract methods implemented and composed into the exported adapter object: emitAgentRulesFile, emitEngineConfig, emitVerbs, emitRoles, emitSkills, emitWatchdog, emitOutputStyles, installMCP, removeMCP, listInstalledMCPs, postInstall, preSync, doctor.
• emitRoles emits the six required roles at every level and the seventh (frontend-browser-tester) at Standard/Strict; read-only roles get a restricted tools allowlist, builder carries the scope-limited-write profile.
• emitWatchdog emits the full v4 hook-script set at mode: 0o755.
• installMCP resolves a catalog entry's claude-code recipe and throws a clean MCP_INSTALL_FAILED envelope for missing/configBlock-only recipes; doctor performs real filesystem presence checks.
• Implemented against the shipped @aidokit/core types, which differ from the draft supporting types in adapter-contract.md §6/§8 (spec↔core reconciliation tracked separately).
• v4 kit content — backbone slice ported. Templates now live as checked-in files under src/files/, read at emit time via a synchronous files-resolver (the Adapter emit methods are synchronous by contract) and copied to dist/files/ by a post-tsc copy-files.mjs step, mirroring @aidokit/shared-docs. Ported verbatim from v4 kit Part 3: agent-rules.md (the emitted CLAUDE.md, with {{projectName}}/{{validationCommands}} interpolation — kit §42), engine/settings.json (the full hook + permissions config — kit §43), and all seven engine/agents/*.md role files (kit §44-50). emitAgentRulesFile, emitEngineConfig, and emitRoles read these templates instead of emitting inline placeholders.
• v4 kit content — watchdog slice ported. All 19 hook scripts from kit Part 3 §53 are checked in verbatim under src/files/engine/scripts/ (Node-stdlib-only: validate-scope, validate-bash, validate-version, track-file-edits, track-test-failures, track-command-failures, health-check, inject-active-task, … ). emitWatchdog now emits the full set at mode: 0o755; the stale 4-entry WATCHDOG_SCRIPTS map was removed from paths.ts. The emitted settings.json and emitWatchdog are now consistent.
• v4 kit content — slash-command slice ported. The three workflow verbs are checked in under src/files/engine/commands/{intake,implement-task, orchestrator-next}.md, authored as Claude Code slash commands (frontmatter - prompt body) from the v4 operational specs (kit Part 2 §26-28 — the kit documents verbs as specs, not literal files, so these are a faithful synthesis). emitVerbs reads them.
• v4 kit content — output-styles and schemas slice ported. The five output styles (kit Part 3 §52) are checked in under src/files/engine/output-styles/ and emitted by emitOutputStyles. The eight artifact JSON schemas (kit Part 3 §54) are checked in under src/files/engine/schemas/ and emitted by emitEngineConfig alongside settings.json — the Adapter contract has no dedicated schema method, so .claude/schemas/ is treated as engine configuration. With this, every adapter emit method is content-complete; emitSkills (a wrapper) is fed the real v4 skills via @aidokit/base-skills.
• Co-located Vitest suite covers the manifest, every emit method, MCP install/remove/list, the lifecycle methods, determinism, and the composed adapter wiring.
• aidokit CLI package (packages/cli) — the Layer 3 user-facing shell:
• Published unscoped as aidokit with a bin of the same name; the package directory is packages/cli/ (design docs call it @aidokit/cli).
• Commander-based shell (run.ts): global flags per cli-reference.md §3 (--yes, --no-prompts, --dry-run, --json, --verbose, --quiet, --no-color, --cwd), --json-implies---no-color/--no-prompts normalisation, and --verbose+--quiet rejection. run() returns an exit code rather than calling process.exit, so it is unit-testable; the bin/aidokit.ts shim is the only process.exitCode writer.
• exit-codes.ts maps AidoError.code (and the cli-reference.md §10.2 reserved codes) onto the grouped exit-code taxonomy from §8.
• aidokit init — the only v0.1 command — implements the 14-step init sequence from adapter-contract.md §4.1 for the greenfield / claude-code / Standard / node-ts slice: host + prereq probe, stack detection, flag/prompt selections (@clack/prompts), ProjectContext assembly, file plan composition (adapter emissions + shared-docs skeletons + core base skills), --dry-run short-circuit, confirmation, staged write (write to .aido-staging/ then commit; root untouched on failure), MCP install and postInstall via a single spawn helper, and .aido/adapter.md.
• v0.1 has a fixed, statically-imported extension registry (adapter-claude-code + stack-pack-node-ts); runtime plugin discovery stays a v2.0 concern. doctor, sync, validate, migrate, mcp, skills, new, manifest, list are not registered (deferred to v0.5+).
• The core base skill set is consumed from @aidokit/base-skills (see below); init/base-skills.ts is now a one-line re-export (CORE_BASE_SKILLS).
• Co-located Vitest suite covers exit-code mapping, global-flag normalisation, run (version/help/unknown-command), the selection resolvers, the core base skills, file-plan composition, and the staged writer (including unsafe-path rejection).
• Integration test (test/integration/init-emit.test.ts) exercises the real cross-package pipeline — adapter + stack pack + base-skills + shared-docs composed by computeFilePlan, written by writeFilesStaged to a temp dir — and asserts the emitted .claude/ tree structure (7 agents, 3 commands, 19 hook scripts, 5 output styles, 8 schemas, ≥18 skills) plus the docs/ and agent-artifacts/ skeletons and plan determinism. This is the structural integration test; the byte-compare-against-v4-reference variant is deferred until the reference snapshot is generated from a verified build.
• @aidokit/base-skills package (packages/base-skills) — a new Layer-1 package holding the core base skill set:
• Extracted from @aidokit/cli's former inline placeholder so a third-party adapter or non-CLI consumer can reuse the skills. Depends only on @aidokit/core; consumed by @aidokit/cli. (Not in the CLAUDE.md §5 package list yet — that list needs updating.)
• Exports BASE_SKILLS: readonly SkillTemplate[] (all 18 skills, source: 'core') and getBaseSkill(id).
• v4 kit content — skills slice ported. All 18 skill bodies from kit Part 3 §51 are checked in verbatim under src/files/skills/<id>.md (architecture-summary, testing-conventions, validation-patterns, error-envelope, changelog-format, api-docs-format, the six *-template skills, digest, beads-queries, decision-capture, delta-spec-format, subagent-review-checklists, …). Bodies are stored with the leading # Title removed; the adapter's emitSkills re-adds the heading. skills.ts carries the per-skill metadata table (name, preloadedBy from the v4 agent skills: frontmatter, required).
• Known fidelity gap: the v4 SKILL.md frontmatter description and allowed-tools are not round-tripped (SkillTemplate has no slot); autoLoadTriggers is left empty (the v4 kit encodes auto-load conditions as prose). Enriching SkillTemplate is tracked as ADR-0013.
• Co-located Vitest suite validates all 18 skills against SkillTemplateSchema, checks id uniqueness and source: 'core', and verifies bodies are heading-less fragments.

Changed

• docs/specs/adapter-contract.md §6 and §8 — supporting-type definitions (EmittedFile, ShellCommand, InstalledMCP, SyncPlan, DoctorCheck, AdapterManifest, CapabilityDeclarations) and the §8.2 adapter.md example were reconciled with the shipped @aidokit/core schemas per ADR-0012. Draft-only fields (EmittedFile.owner/syncOverwritePolicy, ShellCommand.requiresConfirmation/abortOnFailure, AdapterManifest.displayName/adapterVersion/maintainer/contentHash, structured AdapterGap, CapabilityDeclarations.readsBeyondOwnFiles) were removed; the §12 MinimalAdapter example carries a note that it predates the reconciliation.
• Removed the unused test:conformance script from @aidokit/adapter-claude-code's package.json — it referenced the conformance harness, which is v0.5 scope and does not exist, and would have failed CI.

Deprecated

• Nothing yet.

Removed

• Nothing yet.

Fixed

• Nothing yet.

Security

• Nothing yet.

Pre-history

Design phase. The kit content informing the Claude Code adapter lives in .docs/context/:

• claude-workflow-kit-v4-base-part-1.md — foundation, philosophy, concepts
• claude-workflow-kit-v4-base-part-2.md — architecture and detailed specifications
• claude-workflow-kit-v4-base-part-3.md — concrete code, templates, operations
• claude-workflow-kit-v4-a-z.md — consolidated v4 reference

Predecessor versions (v2.1, v3) and the tool-agnostic orchestrator-spec.md are held outside this workspace as historical context.

The first tagged release will be v0.1.0-alpha.0 under the alpha npm dist-tag once the v0.1 exit criteria in .docs/ROADMAP.md are met.