AGENTS.md — aidokit repository agent rules

Project-level rules for AI-assisted development of aidokit itself. This file is read by your AI coding agent (Claude Code, Codex, Copilot, …) at session start. Keep it lean, high-signal, and evergreen — pin durable conventions here, not transient task state.

1. What aidokit is

aidokit is a command-line tool that scaffolds a structured, adapter-agnostic, AI-assisted development workflow into any software project in one command. It is the productisation of the AI Dev Orchestrator Spec v2.0 — earlier internal iterations of which lived as claude-workflow-kit v2.1, v3, and v4.

aidokit itself:

• Makes zero LLM calls. It is a deterministic scaffolder.
• Emits files. It does not run as a daemon, agent, or runtime.
• Is the package. The kit content (skills, agents, hooks, slash commands) is emitted by an adapter (@aidokit/adapter-codex, @aidokit/adapter-copilot, @aidokit/adapter-claude-code, …) — not hard-coded into the CLI.

One-line mental model

A monorepo of TypeScript packages whose CLI shell composes one Adapter + N Stack Packs + shared catalogs + shared docs into a complete workflow tree (.codex/, .copilot/, .claude/, …) in the user's project.

2. Read these before substantive work

The product is fully specified. Do not invent design — read first, draft second.

Path discrepancy — read this once

The on-disk path is .docs/ (hidden directory). The published docs reference paths as docs/. Treat .docs/ as the source of truth on disk; the dot prefix is an intentional Phase-0 choice to keep design docs out of the published package surface. A future cleanup may flatten this — until then, references in this AGENTS.md and in code comments use the actual on-disk path.

3. Current phase

What is in scope right now (v1.0 ROADMAP delta over v0.5): - Multi-adapter projects (.codex/ + .copilot/ + .claude/ from one init) - aidokit search adapter|stack-pack (npm-native discovery) - --dry-run on init and sync (enumerate without writing) - Capability declarations in adapter manifests + conformance verification - Signed npm packages (Sigstore / npm provenance) - Docs site, frozen adapter contract + CLI surface

What is still out of scope (post-v1.0): Third-party adapter/stack-pack SDK as standalone packages, curated marketplace site, additional first-party adapters or stack packs beyond the five listed, IDE plugins, LLM-assisted features, auto-install of prereqs (ADR-0008, permanent non-goal).

If you find yourself building anything still out of scope, stop.

4. Architecture cheat-sheet

Three layers, strict downward dependency:

Layer 3   @aidokit/cli                            (user-facing shell)
              │
Layer 2   @aidokit/adapter-*    @aidokit/stack-pack-*   (siblings; compose orthogonally)
              │                    │
Layer 1   @aidokit/core   @aidokit/shared-docs   @aidokit/stack-detect
          @aidokit/prereq-check   @aidokit/mcp-catalog   @aidokit/base-skills

Rules that are not negotiable:

• Every package depends on @aidokit/core directly or transitively.
• No adapter imports any stack pack.
• No stack pack imports any adapter.
• Only @aidokit/cli consumes all extensions.
• @aidokit/core has zero runtime dependencies on other @aidokit/* packages — it must be installable standalone by third-party adapter authors.

For the full picture see .docs/ARCHITECTURE.md §1 and §4.

5. Repository layout (intended)

This is the target shape per .docs/ARCHITECTURE.md §3. Most of it does not exist yet — create directories and packages as the phases land them.

aidokit/
├── AGENTS.md                       ← this file (canonical agent rules)
├── CLAUDE.md                       ← Claude Code compatibility pointer → imports AGENTS.md
├── README.md                       ← currently at .docs/README.md, to be moved up
├── ROADMAP.md                      ← currently at .docs/ROADMAP.md, to be moved up
├── ARCHITECTURE.md                 ← currently at .docs/ARCHITECTURE.md, to be moved up
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE                         ← Apache-2.0, drafted not legally reviewed (v0.1)
├── package.json                    ← workspace root
├── pnpm-workspace.yaml
├── turbo.json
├── tsconfig.base.json
├── .github/workflows/              ← lint, typecheck, unit, integration, publish
├── .changeset/                     ← already initialised per .gitignore
├── docs/                           ← currently .docs/ — see §2 note
│   ├── specs/
│   └── architecture/decisions/
├── packages/
│   ├── cli/                        ← @aidokit/cli
│   ├── core/                       ← @aidokit/core
│   ├── shared-docs/                ← @aidokit/shared-docs
│   ├── stack-detect/               ← @aidokit/stack-detect
│   ├── prereq-check/               ← @aidokit/prereq-check
│   ├── mcp-catalog/                ← @aidokit/mcp-catalog
│   ├── base-skills/                ← @aidokit/base-skills
│   ├── adapter-claude-code/        ← @aidokit/adapter-claude-code
│   └── stack-pack-node-ts/         ← @aidokit/stack-pack-node-ts
├── examples/                       ← bootstrapped sample projects used in CI
└── scripts/                        ← repo automation

Packages not in v0.1: adapter-codex, stack-pack-python, stack-pack-react, stack-pack-go. Do not create their directories yet.

6. Design principles to enforce

These come from .docs/ARCHITECTURE.md §2 and are load-bearing. Reject changes that violate them.

1. Plain template files, no template engine. Templates are real files under src/files/ mirroring their target layout. Variable substitution uses a single thin interpolate(template, vars) helper with {{varName}} syntax. No Handlebars, EJS, Nunjucks, Mustache. If a template needs conditionals or loops, generate it programmatically instead.
2. Contracts as TypeScript interfaces. Adapter and StackPack are TS interfaces in @aidokit/core. Not YAML schemas. Adapters are real packages with real code.
3. Data-driven catalogs. The MCP catalog and prereq list are TypeScript const arrays. Adding an entry is a one-file edit. No runtime plugin discovery before v2.0.
4. Zero LLM calls. Every decision is deterministic. Every CI run is hermetic.
5. Conformance declared AND verified. Adapters declare a level in their manifest; the @aidokit/core harness verifies the claim. Drift fails CI.
6. Adapters and stack packs are siblings. They never import each other.
7. Migrations are first-class. Every breaking change ships with aidokit migrate. (Not v0.1 surface, but design with this in mind.)
8. Read-before-write everywhere. No file is overwritten without diff + confirmation. --yes skips the prompt but never the diff computation (diff goes to logs).
9. Fail loud, recover gracefully. Use the AidoError envelope (§16 of ARCHITECTURE.md). Partial writes go to a staging dir; on failure, staging is deleted and the project root is untouched.

7. Engineering conventions

7.1 Tooling

• Runtime: Node.js 20+ (.node-version and engines.node once present).
• Package manager: pnpm (workspaces).
• Build orchestrator: Turborepo.
• Language: TypeScript, strict mode, ESM output. tsconfig.base.json at root, per-package tsconfig.json extends it.
• Test runner: Vitest.
• Linter / formatter: ESLint + Prettier.
• Release tool: Changesets (.changeset/ already present).
• Shipping target: npm, scoped under @aidokit/*. CLI published as aidokit (unscoped).

7.2 Open library choices

These are flagged in .docs/ARCHITECTURE.md §21. Do not silently pick one — open an ADR first and ask the maintainer for a decision:

• Argument parser: commander vs oclif vs custom
• Prompts: @inquirer/prompts vs clack vs prompts
• Schema lib in @aidokit/core: re-export zod vs define our own
• Module format: ESM-only vs ESM + CJS

7.3 Code conventions

• One responsibility per file. Public surface goes through index.ts per package.
• No default exports in @aidokit/core. Named exports keep IDE refactoring honest.
• Errors thrown internally use the AidoError class with a machine-readable code.
• All async filesystem work uses fs/promises. No fs.*Sync in command paths.
• Shell execution goes through a single helper in @aidokit/core so capability declarations stay enforceable. Direct child_process.spawn is a code-review red flag.
• Templates under packages/*/src/files/ are checked in as-is and tree-copied during build into packages/*/dist/files/. The build pipeline must preserve relative paths and file modes (chmod +x for .mjs hook scripts is part of postInstall).

7.4 Testing tiers (see ARCHITECTURE.md §18)

Coverage targets (do not relax without an ADR): @aidokit/core 90%+, adapters 80%+, @aidokit/cli 70%+.

7.5 ADRs

Architecture-relevant decisions live in .docs/docs/architecture/decisions/ using the template at 0000-template.md. Numbering is monotonically increasing — do not renumber existing ADRs even if gaps appear. Existing ADRs:

• 0001 — runtime + language (Node.js 20+, TypeScript, ESM)
• 0002 — monorepo tooling (pnpm + Turborepo)
• 0003 — license (Apache-2.0)
• 0004 — distribution (npm, scoped packages, Changesets, provenance from v1.0)
• 0005 — adapter contract shape
• 0006 — stack-pack contract shape
• 0007 — MCP catalog shape
• 0008 — prereq install policy (no auto-install)
• 0009 — argument parser (Commander)
• 0010 — prompts library (@clack/prompts)
• 0011 — schema library (Zod via @aidokit/core/schema)
• 0012 — spec↔core type reconciliation (shipped @aidokit/core types are authoritative)
• 0013 — SkillTemplate enrichment (description + allowedTools)
• 0014 — ProjectContext parsed manifests (real package.json scripts)
• 0015 — graphify MCP catalog entry (Proposed; opt-in, security-sensitive, Python prereq)
• 0032 — .gitignore managed-block merge (Proposed; optional Adapter.gitignoreEntries)

When you introduce a non-trivial design choice, propose an ADR before writing the code.

7.6 Changesets

Every PR that changes published behavior MUST include a changeset. Run pnpm changeset and commit the generated file. Patch/minor/major follows the "pre-1.0 breaking changes allowed on minor bump" rule from .docs/ROADMAP.md.

8. Anti-patterns — refuse these

These are repeat-failure modes the architecture is explicitly written to avoid.

• Template engines. No Handlebars/EJS/Nunjucks/Mustache. See §6, principle 1.
• YAML "config" instead of typed contracts. The Adapter interface is TS. Declarative configs that try to encode behavior end up reimplementing programming.
• Runtime plugin discovery / dynamic require. Adapters and stack packs are workspace packages or npm dependencies, imported statically. Plugin loaders are v2.0 territory.
• LLM calls from aidokit itself. Including "helpful" calls to summarise something during init. Zero. The user's CLI handles all model traffic.
• Telemetry, phone-home, anonymous metrics. None. Ever.
• Cross-package upward imports. Layer 1 never imports Layer 2; adapters never import stack packs. Enforce with ESLint no-restricted-imports once Phase 0 lands.
• Overwriting user files without diff + confirm. Including .gitignore — append-with-dedupe only.
• Auto-installing prereqs. Even with --yes. Prereq installs are always a separate explicit confirmation (ADR-0008 codifies this).
• Speculative features. If it isn't in the v0.1 In-Scope list in .docs/ROADMAP.md, push back and defer.

9. Working approach for agents in this repo

9.1 Before writing code

1. Read the relevant spec section(s) in .docs/ first. Cite the file and section in your response when proposing a design.
2. If the answer is genuinely undecided, ask one focused question rather than guessing. The product is precisely specified; do not invent.
3. For changes touching the Adapter or StackPack contract: propose an ADR draft.
4. For changes touching emitted kit content: cross-reference .docs/context/claude-workflow-kit-v4-base-part-*.md so the templates stay faithful to v4.

9.2 While writing code

1. Stage work in small, reviewable commits.
2. Co-locate tests with source. New code without tests blocks the PR.
3. Update the relevant spec or ADR in the same PR — drift between .docs/docs/specs/* and code is a CI gate (will be, once Phase 0 lands).
4. Touch only the package the task names. Cross-package refactors are their own PR.

9.3 Source-of-truth ordering when sources conflict

1. The current target version of the kit content — v4 base parts (Parts 1/2/3).
2. The product specs in .docs/docs/specs/.
3. ADRs in .docs/docs/architecture/decisions/.
4. .docs/README.md, .docs/ROADMAP.md, .docs/ARCHITECTURE.md.
5. Predecessor kit versions (v3, v2.1) — context only, never overrides.
6. The target CLI's official documentation — authoritative for any claim about that CLI's primitives (hooks, frontmatter, permission modes, slash commands, MCP behaviour).
7. The user's instructions in the current session.
8. General knowledge — lowest priority; flag explicitly when used.

If a v4 base document conflicts with a spec in .docs/docs/specs/, flag the conflict and ask — do not silently pick one.

9.4 When you're stuck

• Search the kit context files (.docs/context/) — the answer is usually there.
• Then check the spec files (.docs/docs/specs/).
• Then check the ADRs.
• Then, and only then, ask the maintainer with the specific question, the sources you consulted, and the candidate answers.

10. The dogfood gate (read once, remember always)

Per .docs/ARCHITECTURE.md §20, every first-party adapter ships with a permanent CI gate that compares its emitted file plan, byte-for-byte, against a committed reference fixture. Three gates run today, one per adapter:

All three fixtures are produced from the same fixed packages/cli/test/integration/reference-context.json paired with @aidokit/stack-pack-node-ts, so the only variable between the trees is the adapter under test. The generator is:

pnpm -r build
node scripts/generate-reference-snapshot.mjs              # regenerate all three
node scripts/generate-reference-snapshot.mjs --adapter codex   # one at a time

The byte-compare tests fail if the emitted plan diverges from the fixture in any byte. Drift fails CI. Intentional kit changes are landed by regenerating the affected fixture(s) and reviewing the diff before committing — an unreviewed regeneration silently launders a regression past the gate.

@aidokit/adapter-claude-code additionally honors named drift exceptions in byte-compare-exceptions.json for the rare cases where intentional Strict- conformance content cannot be expressed in the fixture. Codex and copilot have no exception list — at Minimum conformance the surface is small enough to keep strict. (The differing conformance levels are a consequence of target-CLI capability — Claude Code exposes deterministic hooks and output styles, so its adapter declares strict; Codex and Copilot expose neither, so theirs declare minimum. This is a capability outcome, not a ranking of adapters.)

Why this matters: if aidokit init produces a working project for one adapter, it produces this project's .codex/ / .copilot/ / .claude/ content. If it doesn't, we know on the next CI run.

11. Non-goals — pushback list

If a request asks for any of these, push back politely and cite the source:

• LLM calls of any kind from aidokit itself. (ROADMAP §Non-goals.)
• Telemetry, "improve aidokit" prompts, anonymous usage stats. (ROADMAP §Non-goals.)
• A daemon mode, long-running watcher, or background service. (ARCHITECTURE §1.)
• Replacing the user's AI coding CLI. (ROADMAP §Non-goals.)
• Auto-progression between tasks in the emitted workflow. (ROADMAP §Non-goals.)
• A full project-management suite. (ROADMAP §Non-goals.)
• An IDE plugin. (Speculative, post-v1.0; ROADMAP "Speculative".)
• An enterprise SaaS product. (ROADMAP §Non-goals.)

12. Quick references

• Vision and install story: .docs/README.md
• Release plan and exit criteria: .docs/ROADMAP.md
• Full system design: .docs/ARCHITECTURE.md
• Adapter contract: .docs/docs/specs/adapter-contract.md
• Stack-pack contract: .docs/docs/specs/stack-pack-contract.md
• CLI surface: .docs/docs/specs/cli-reference.md
• MCP catalog: .docs/docs/specs/mcp-catalog.md
• Conformance levels: .docs/docs/specs/conformance-levels.md
• Security model: .docs/docs/specs/security-model.md
• ADRs: .docs/docs/architecture/decisions/
• Kit content (v4): .docs/context/claude-workflow-kit-v4-base-part-1.md, …part-2.md, …part-3.md
• Kit content (consolidated): .docs/context/claude-workflow-kit-v4-a-z.md

13. Editing this file

AGENTS.md is the canonical agent-rules surface and is read at every session start (Claude Code pulls it in via the @AGENTS.md import in CLAUDE.md). Keep it under ~400 lines. When this file grows, prefer extracting durable detail into a spec under .docs/docs/specs/ and linking from here. Transient state never belongs in AGENTS.md.