Roadmap

Strategic plan for aidokit, organized by release milestone. v0.5 Beta shipped; v1.0 GA in flight. Dates are indicative, not commitments.

Vision

By v1.0, aidokit is the default way developers add structured, controlled, AI-assisted workflow to a project. One command emits a complete, scope-enforced, role-separated, watchdog-protected operating layer that runs on whichever AI coding CLI the developer prefers. Multi-adapter projects work. Stack-aware suggestions work. The ecosystem has at least two first-party adapters and four first-party stack packs, and a stable contract lets third parties build their own.

By v2.0 (post-1.0), the third-party SDK and marketplace let community-maintained adapters and stack packs ship with the same trust signals (conformance level, verification badges, security declarations) as first-party packages.

Release principles

  1. Ship narrow, ship working. Each release covers a smaller surface than the previous plan suggested, but everything in that surface is production-quality.
  2. Dogfood as soon as possible. From v0.1 onward, the aidokit repo itself should be re-bootstrappable with aidokit init as the strongest possible integration test.
  3. Stability before breadth. Lock the adapter contract and CLI surface before adding more adapters or stack packs.
  4. Honest about pre-1.0. Breaking changes are allowed between minor versions until v1.0. After v1.0, semver applies strictly.
  5. No telemetry, no API calls, no surprises. Every release stays zero-LLM and zero-tracking.
  6. Migrations are first-class. Every breaking change ships with an aidokit migrate script.

Current status

Release Status Target Conformance levels
v0.1 Alpha Delivered Q1 Standard only
v0.5 Beta Delivered Q2 All three
v1.0 GA Code-complete; pending human gates Q3–Q4 (est.) All three
Post-1.0 Planned TBD All three

v1.0 status as of 2026-05-26: the deterministic mechanism for all 25 pain points from the analysis now ships in code. "Mechanism shipped" means the gate, skill, or scan exists and is wired in — not that the underlying model failure can no longer occur. aidokit raises the floor (e.g. the eval gate makes toolchain-visible "claimed-done ≠ done" deterministically fail — ADR-0028); it does not fix the model. Claims stay scoped to what a zero-LLM scaffolder can actually enforce. The complete aidokit verify facet umbrella ships fully implemented (--secrets, --budget, --deps, --license, --loop-cap), alongside aidokit eval, aidokit doctor --hygiene / --model-drift / semantic --drift, MCP untrustedOutput quarantine + skill, .aidoignore confidentiality emit, .aidokit/model.lock, scratchpad-hygiene + reset-context skills, and the TaskState.iterations foundation. What's gating GA is the same set of human items as before: design-partner recruitment, community-maintainer recruitment for non-canary stack packs, a published cost-study case, auditor validation of the SOC2 and EU AI Act mappings, and the marketing surface (video, analyst outreach). See the second devlog post for the honest read: wiki/devlog/2026-05-25-week-2-workstreams-closed.md.

Target dates are aspirational, set against single-maintainer pace. Multi-contributor velocity could compress them.

High-level scope across releases

Legend: ✅ = scoped for that release · ✓ = delivered as of 2026-05-25 · ❌ = not in scope.

Capability v0.1 v0.5 v1.0 Post-1.0
aidokit init (greenfield) ✓ ✓ ✓ ✅
Claude Code adapter ✓ ✓ ✓ ✅
Node + TypeScript stack pack ✓ ✓ ✓ ✅
Prereq detection (printed install commands) ✓ ✓ ✓ ✅
MCP catalog (core 5) ✓ ✓ ✓ ✅
Standard conformance ✓ ✓ ✓ ✅
Minimum + Strict conformance ❌ ✓ ✓ ✅
Brownfield support (--brownfield) ❌ ✓ ✓ ✅
aidokit doctor ❌ ✓ ✓ ✅
aidokit sync ❌ ✓ ✓ ✅
aidokit validate ❌ ✓ ✓ ✅
aidokit migrate (v3 → v4) ❌ ✓ ✓ ✅
aidokit new scaffolding ❌ ✓ ✓ ✅
Python stack pack ❌ ✓ ✓ ✅
MCP catalog (expanded ~10) ❌ ✓ ✓ ✅
Codex CLI adapter ❌ ❌ ✓ ✅
Copilot adapter (Minimum; ADR-0016) ❌ ❌ ✓ ✅
Multi-adapter projects + aidokit add adapter ❌ ❌ ✓ ✅
React + Go stack packs ❌ ❌ ✓ ✅
Dry-run install (--dry-run) ❌ ❌ ✓ ✅
Signed packages (Sigstore / npm provenance) ❌ ❌ ✓ ✅
User-facing tier vocabulary (--tier) ❌ ❌ ✓ ✅
.aidokit/capabilities.json at Strict (ADR-0017) ❌ ❌ ✓ ✅
aidokit verify [--capabilities] ❌ ❌ ✓ ✅
aidokit verify --secrets ❌ ❌ ✓ ✅
aidokit verify --budget (impl) ❌ ❌ ✓ ✅
aidokit verify --deps (impl) ❌ ❌ ✓ ✅
aidokit verify --license (impl) ❌ ❌ ✓ ✅
aidokit verify --loop-cap (impl) ❌ ❌ ✓ ✅
aidokit eval (acceptance criteria runner) ❌ ❌ ✓ ✅
Scratchpad-hygiene + reset-context skills (always-on) ❌ ❌ ✓ ✅
aidokit doctor --hygiene ❌ ❌ ✓ ✅
Task state.json + iterations counter ❌ ❌ ✓ ✅
Semantic doc-drift in aidokit doctor --drift ❌ ❌ ✓ ✅
.aidokit/policy.json (all tiers) ❌ ❌ ✓ ✅
MCP untrustedOutput flag + quarantine skill ❌ ❌ ✓ ✅
aidokit doctor --model-drift ❌ ❌ ✓ ✅
.aidokit/model.lock ❌ ❌ ✓ ✅
.aidoignore + @aidokit/core/aidoignore ❌ ❌ ✓ ✅
aidokit manifest --verify-capabilities ❌ ❌ ✓ ✅
aidokit metrics summary/export (opt-in) ❌ ❌ ✓ ✅
aidokit audit export + SOC2/EU-AI-Act mappings ❌ ❌ ✓ ✅
aidokit doctor --drift ❌ ❌ ✓ ✅
Per-tier CLAUDE.md + verb sets ❌ ❌ ✓ ✅
CI matrix + nightly snapshot + quarterly bump ❌ ❌ ✓ ✅
Docs site (aidokit.dev or equivalent) ❌ ❌ ✅(*) ✅
Third-party adapter SDK ❌ ❌ ❌ ✅
Third-party stack-pack SDK ❌ ❌ ❌ ✅
Marketplace (npm-native + curated) ❌ ❌ ❌ ✅
Additional first-party adapters / packs ❌ ❌ ❌ ✅

(*) Docs site: the wiki under docs-site/wiki/ is rendered and complete (see wiki/index.md). Domain registration + hosted deployment is a human operations task, not a code item.

v0.1 — Alpha

Goal: A working npx aidokit init that bootstraps a greenfield Node.js + TypeScript project with the Claude Code adapter at Standard conformance.

Audience: The maintainer, a handful of friendly testers. Not a public launch.

Tagline: Works for me.

In scope

Out of scope

Exit criteria

Risks

Risk Mitigation
v4 kit templates contain undocumented coupling Byte-compare integration test catches drift early
Claude Code's claude mcp add flags change Pin to a tested Claude Code version range in package.json; document gap
Windows path handling in template emission CI matrix includes Windows; manual smoke test before tagging
Beads availability on all OSes Beads is optional in v0.1; fallback to flat docs/04-task-index.md
Scope creep (someone wants Codex in v0.1) Defer to v1.0; document in ROADMAP

v0.5 — Beta

Goal: A usable tool for early adopters running real projects. Brownfield works, health checks work, the ecosystem grows by one stack pack.

Audience: Early adopters willing to file issues and tolerate rough edges. Not yet "stable."

Tagline: Works for early adopters.

In scope (delta over v0.1)

Out of scope

Exit criteria

Risks

Risk Mitigation
Brownfield scanner has too many false positives / negatives Pre-flight --dry-run shows what would be ingested; user can override
Migration script breaks on real-world v3 projects Migration writes backups; ships with a migration-review.md for manual review
Stack-pack contract leaks Node-specific assumptions Python pack catches this early; refactor contract before pack is finalized
aidokit sync overwrites user customizations Diff preview required; sync never writes without explicit confirmation
MCP installer drift across adapter versions Pin Claude Code version range; surface drift in aidokit doctor

v1.0 — GA

Goal: Public, stable, multi-adapter, multi-stack. The tool is ready to recommend without caveats.

Audience: General developers. Hacker News audience. Conference talks.

Tagline: Works for everyone.

In scope (delta over v0.5)

Out of scope

Exit criteria

Risks

Risk Mitigation
Codex CLI's sandbox/approval model lacks hook-level enforcement Document gap honestly; ship Codex adapter at Minimum first; advocate for Codex hook hooks upstream
Multi-adapter projects produce confusing duplicate setups Shared docs/ and agent-artifacts/ force convergence; aidokit doctor warns on drift
Spec v2.0 needs revision based on second-adapter learnings Treat first 2–3 minor releases of v1.x as a stability window; only freeze contract at v1.3
Public launch attracts contributors faster than capacity Triage protocol documented before launch; clear "good first issue" labels
Marketing of "adapter-agnostic" outruns reality Stay honest in README; only one fully-conformant adapter at launch

Beyond v1.0 — Ecosystem era

Post-1.0 shifts from "build the tool" to "let others extend the tool." Loose order, not strict timeline.

v1.x — Hardening and third-party readiness

v2.0 — Marketplace and platform

Speculative / not committed

Non-goals (across all releases)

aidokit will not:

How this roadmap evolves

Open questions

These are unresolved and will be answered before the affected release ships.

Question Affects Status
Final domain name for the docs site v1.0 Open
Whether to require Beads in v1.0 or keep optional v1.0 Open — leaning required at Standard, optional at Minimum
Codex CLI's exact hook/sandbox surface at the time of v1.0 v1.0 Awaiting Codex stable release
Whether to ship a single binary alongside npx (via pkg/sea) v1.0 Open — depends on user demand
Whether aidokit itself should depend on a stable Beads 1.0 v0.5 Open — pinning to Beads >= 0.X for now
Whether to add a code-graph / knowledge-graph MCP to the catalog to fill the v4 kit's cgb researcher slot (the researcher.md agent declares a cgb MCP for dependency-topology / impact analysis, which the v0.1 catalog does not provide). Candidate: graphify (PyPI graphifyy) — a /graphify skill + MCP server that turns a repo into a queryable knowledge graph. v0.5 Resolved — added as catalog entry #11 per ADR-0015 (Proposed). securitySensitive: true + triggers: ['never'] (opt-in only). Python remains a per-MCP prereq via the new MCPDef.prereqs field; not promoted to an aidokit-wide prereq. ADR-0008 no-auto-install applies.

See also