FAQ
Frequently asked questions about aidokit.
What problems does aidokit solve?
aidokit was scoped against a 25-point analysis of recurring failure modes in unsupervised AI coding workflows. The v1.x release closes all 25 — 21 with a full mitigation that ships at every tier, and 4 that are strongest at the Standard and Strict tiers (tier-gated by design). The table below maps each category to the concrete mechanism that resolves it.
Legend: ✅ Strong = mitigated at every tier · 🟢 Strong-at-Standard = strongest at Standard/Strict, present-as-convention at Minimum.
| # | Pain point | Status | How aidokit resolves it |
|---|---|---|---|
| 1 | Context window limits | 🟢 Strong-at-Standard | Role separation, sub-agents, per-tier memory file. |
| 2 | Context poisoning / drift | ✅ Strong | scratchpad-hygiene + reset-context skills (always-on); doctor --hygiene. |
| 3 | Hallucinated APIs / symbols | ✅ Strong | Context7 MCP, Read-before-edit skill, byte-compare gate, zero-LLM scaffolder. |
| 4 | Token cost explosion | ✅ Strong | aidokit verify --budget. |
| 5 | Stale documentation | ✅ Strong | aidokit doctor --drift with semantic reference-graph check. |
| 6 | Tech debt from AI sprawl | 🟢 Strong-at-Standard | Memory-file anti-patterns; scope discipline. |
| 7 | Non-determinism | ✅ Strong | Zero-LLM scaffolder; hermetic CI; AIDOKIT_DETERMINISTIC=1. |
| 8 | Verification gap | 🟢 Strong-at-Standard | Tester-Reviewer role; aidokit verify; change-summary. |
| 9 | Security & supply-chain | ✅ Strong | .aidokit/capabilities.json; signed packages; five verify facets. |
| 10 | Workflow fragmentation | ✅ Strong | Three first-party adapters; multi-adapter projects. |
| 11 | Prompt injection (MCP) | ✅ Strong | untrustedOutput flag; quarantining-untrusted-output skill; doctor check; threat T18. |
| 12 | Scope creep | 🟢 Strong-at-Standard | Immutable task briefs; memory-file rules. |
| 13 | Architectural intent loss | ✅ Strong | First-class ADRs (0001–0020). |
| 14 | Onboarding cost | ✅ Strong | Per-tier memory file; shared docs/ skeleton. |
| 15 | Skill atrophy | ✅ Strong | SP9 hygiene gates (doctor --hygiene). |
| 16 | Multi-agent chaos | 🟢 Strong-at-Standard | Fixed role contracts; single Maintainer merge. |
| 17 | Evaluation difficulty | ✅ Strong | aidokit eval runs ## Acceptance criteria. |
| 18 | License / IP contamination | ✅ Strong | aidokit verify --license. |
| 19 | Secrets leakage | ✅ Strong | aidokit verify --secrets; reinforced by .aidoignore. |
| 20 | Reproducibility across OSes | ✅ Strong | CI matrix Win/macOS/Linux; deterministic emission. |
| 21 | Model / CLI version drift | ✅ Strong | .aidokit/model.lock; doctor --model-drift. |
| 22 | Agent runaway loops | ✅ Strong | aidokit verify --loop-cap. |
| 23 | Code confidentiality | ✅ Strong | .aidoignore; @aidokit/core/aidoignore matcher. |
| 24 | Dependency bloat | ✅ Strong | aidokit verify --deps. |
| 25 | AI-code provenance | ✅ Strong | Beads task IDs; change-summary; ADRs. |
Want the field stories behind these? Read the Hall of Pain — named, dated failure modes contributed by real teams, and the specific aidokit mechanism that prevents each.
General
Does aidokit call an LLM?
No. Zero LLM calls. Every decision aidokit makes is deterministic. All model traffic happens in your AI coding CLI (Claude Code, Codex, Copilot), using whatever authentication you have configured there.
Does aidokit send any telemetry?
No. Zero network calls from aidokit itself. The only network activity during normal use is npm install (when you first npx it) and the shell commands declared in adapter manifests (e.g. claude mcp add).
Is aidokit a replacement for my AI coding CLI?
No. aidokit scaffolds discipline around the CLI you already use. After aidokit init finishes, you continue working in Claude Code, Codex CLI, or Copilot CLI as before.
Why three CLIs? Why not just pick one?
Different teams pick different tools. Different roles in the same team sometimes pick different tools. aidokit makes the workflow portable across them so you don't have to lock in.
What about Aider / Cursor / Continue / Cline?
Post-v1.0, third-party adapters can be published under any npm scope (@scope/aidokit-adapter-<name>). The standalone SDK that makes third-party adapters first-class ships in the v1.x or v2.0 line per the roadmap.
Install and update
Why @alpha?
Pre-1.0, the latest npm dist-tag is intentionally unset so users don't silently get pre-release builds. From v1.0 GA, latest takes over and you can drop the tag.
How do I update?
npx always fetches the latest version of the tag you specify. To upgrade once you've initialised a project, run aidokit sync to re-emit adapter-owned files from the new version.
Can I pin a specific version?
npx aidokit@0.5.0 init pins to a specific version. aidokit doctor warns if a newer version is available.
Do I need to install aidokit globally?
No. npx is preferred. Global install is optional: npm install -g aidokit@alpha.
Prereqs
Why doesn't aidokit auto-install Node / Claude Code / Beads?
Because installing system software crosses a trust boundary aidokit shouldn't own. We don't know your package-manager preference (Homebrew vs nvm vs asdf vs mise vs winget vs scoop vs …). We can't reason about whether sudo is appropriate. We can't roll back a half-installed prereq. So we detect and print the install command; you run it. See ADR-0008 in the repo for the full reasoning.
Can I bypass the prereq check?
--skip-prereq-check opts out of detection entirely. Use when you know your environment is set up — subsequent stages may still fail if prereqs are genuinely missing.
Configuration and state
Where does aidokit write?
- The project directory: engine dir, rules file,
docs/,agent-artifacts/,.aido/,.gitignore. - (Optionally)
~/.aido/for personal config and personal skills.
It never touches your shell rc, PATH, SSH keys, credential stores, or other system files.
Where does aidokit get its config?
Per-project: <project>/.aido/adapter.md (your selections at init time). User-level: ~/.aido/config.json for preferences. CLI flags override both.
Can I commit .aido/ to git?
Yes — in fact, you should. .aido/adapter.md documents your team's chosen adapter and conformance level; .aido/state.json is the audit log of installed MCPs. Both belong in version control. The transient .aido-staging/ dir is auto-gitignored.
Workflow
What's the difference between /intake and /implement-task?
/intake— classify, research, design, and plan a change into Beads tasks. Stops before any code is written. Runs in plan mode./implement-task— execute exactly one approved Beads task end-to-end (Builder, two-stage Tester-Reviewer, then Maintainer). Stops after one task; no auto-progression.
Why "stops after one task"? Why not run them in a loop?
Autonomous loops are how AI coding sessions go wrong: scope creep, accumulating errors, runaway token spend. Human-gated task transitions are core to the design.
What is /orchestrator-next?
A read-only recommender. Reads the project + Beads state and tells you the safest next action. Never edits files.
Adapters, stack packs, MCPs
Why are adapters and stack packs separate?
Different concerns: adapters target a CLI runtime; stack packs encode tech-stack conventions. Keeping them orthogonal means a Django pack works under Claude Code today and Codex tomorrow without modification.
Can I write my own adapter?
Yes — though the standalone third-party SDK package ships post-v1.0. Until then, copy packages/adapter-claude-code/ as a starting point. The contract is at .docs/docs/specs/adapter-contract.md in the repo.
Why is the MCP catalog "data, not a plugin registry"?
Curation. A catalog is a trust signal — users rely on it to know an entry has been vetted for triggers, role-scoping, and security. Plugin registries that anyone can add to have zero curation.
What's the deal with security-sensitive MCPs?
Some MCPs can write outside the engine dir, execute shell, or send data off-host. Those carry a hard confirmation gate that --yes doesn't bypass. See MCP catalog.
Conformance and quality
What does "Strict" buy me over "Standard"?
The seventh role (frontend-browser-tester), output styles for reports, and complete monitoring-stream coverage of stage transitions. Worth picking if you want the full discipline; default Standard is fine for most teams.
Can I drop down from Strict to Standard later?
Yes. Edit the conformanceTarget in .aido/adapter.md and run aidokit sync. aidokit doctor will reflect the new target.
What happens if a check fails in aidokit doctor?
Exit 13 (CONFORMANCE_FAILED) on any MUST failure. Warnings are reported but don't fail unless you pass --strict.
Multi-adapter and brownfield
Can I run Claude Code and Codex in the same project?
Yes. aidokit init --adapter claude-code,codex. Three engine dirs coexist; docs/, agent-artifacts/, and Beads are shared. See Multi-adapter projects.
I already have a project. Will aidokit init nuke it?
No. Use --brownfield. Existing files outside the adapter's declared writesPaths are never touched. See Brownfield.
Pre-1.0 status
How stable is the v1.0 surface?
Roadmap and architecture are stable. Specs and ADRs are frozen for v1.0. The public CLI surface may still shift before GA but follows semver from v1.0 onward. Pre-1.0 breaking changes ship on minor bumps with migration scripts.
When does v1.0 GA ship?
When the exit criteria in the roadmap are met — signed packages, docs site, no P0/P1 bugs, external review of the adapter contract. Target: Q3–Q4 (indicative, not committed).
Troubleshooting
aidokit init exits with code 10
A required prereq is missing. Install it from the printed instructions and retry.
aidokit init exits with code 13
Conformance check failed. Either the installed adapter is broken or its declared level isn't supported. Try pnpm update @aidokit/adapter-claude-code (or your adapter).
Hook scripts don't run in Claude Code
Likely lost the executable bit. Run aidokit sync --scripts or chmod +x .claude/scripts/*.mjs.
MCP commands hang
Some MCPs need network. If you're offline, set AIDO_OFFLINE=1 and re-run with --no-mcp.
I can't tell which MCPs are installed
aidokit mcp list shows installed MCPs and their role scoping.