aidokitwiki
User Docs Wiki

2026-05-25 — Tier rename + first distribution surface

This week we did the work the 18-month plan calls Phase 0 + the first chunk of Phase 1: rename the user-facing vocabulary, set up the distribution surface, and lay the foundation for the cost-study workstream that will push problem-validity from 7 → 9 over the next several months.

What shipped #

Six commits, atomic, each with its own changeset entry:

  1. feat(core): add user-facing tier names — TierName type (starter | standard | strict) as a 1:1 alias layer over the internal ConformanceLevel. The schema, adapter manifests, and project state file keep their current vocabulary; only the CLI surface and user-facing docs use tiers. 24 new tests, all green.

  2. feat(adapter-claude-code): emit feedback@aidokit.dev mailto — small "Feedback" section at the bottom of the emitted CLAUDE.md. Zero telemetry is a design choice, but it leaves the maintainers blind — an explicit opt-in mailto is the only signal we get. Updated the byte-compare reference fixture in lockstep so the dogfood gate stayed green.

  3. docs: add aidokit vs. alternatives comparison page — honest side-by-side with SpecKit, BMAD-METHOD, Superpowers, and "just write your own CLAUDE.md." Calls out where aidokit is the wrong pick. Marketing copy that names the wrong pick converts better than copy that doesn't, and it's the entire point of an OSS project being trustworthy.

  4. feat(core): add local-only MetricsLog — append-only JSONL writer + reader + aggregator for scope violations, context reloads, task lifecycle, and token estimates. Pure addition; no callsite yet wires it. The C2 ticket will instrument the existing watchdog hooks. The whole MetricsLog is local-only, user-owned, never transmitted — that's the whole "manual telemetry" model.

  5. feat(cli): add --tier flag and interactive picker to init — aidokit init --tier starter|standard|strict is now the preferred way to choose workflow intensity. --conformance keeps working as a back-compat alias. The interactive picker leads with a single "How structured do you want this?" question instead of leaving conformance buried under other prompts.

  6. docs: add per-tier landing pages and Hall of Pain wiki — three tier pages (/wiki/tiers/{starter,standard,strict}), a Hall of Pain page documenting categorised AI-agent failure stories. Two new sidebar sections so they appear everywhere.

What didn't ship #

I started B1 (Starter slash-command aliases /start, /plan, /ship) and then stopped. The honest reason: those new verbs need per-tier emission infrastructure (the A4 ticket), and shipping them standalone either violates the adapter contract (always emit them, even at Strict) or is incomplete (gate them on tier without the supporting infrastructure). Adding them now would either be wrong or sloppy. They move to the next session, after A3/A4.

What's next #

The next session should land:

After those, the design-partner recruitment work begins for real. Code without users is a portfolio piece; we don't want a portfolio piece.

How you can help #

— maintainer