aidokitwiki
User Docs Wiki

How to update the v4 reference

Audience-Contributor Status-Shipped v0.5

Purpose #

When the emitted kit content needs to change, update src/files/ in the adapter / base-skills, the hand-built .claude/ in this repo, and (if intentional) the v4 base parts in .docs/context/.

Big Picture #

There are three places kit content lives:

  1. .docs/context/claude-workflow-kit-v4-base-part-{1,2,3}.md and …v4-a-z.md — the reference.
  2. packages/adapter-claude-code/src/files/ and packages/base-skills/src/files/skills/ — what the adapter emits.
  3. aidokit/.claude/ — the hand-built dogfood reference at the repo root.

The dogfood gate (concepts/dogfood-gate.md) makes (2) and (3) byte-equal post-Phase 8. The v4 base parts (1) are the human-readable spec for what (2) and (3) should contain.

How It Works #

When the change is a content fix (bug or omission) #

  1. Identify the source v4 section in .docs/context/claude-workflow-kit-v4-base-part-{1,2,3}.md. If the change is true to v4 (you're correcting a port), no spec change is needed.
  2. Edit packages/<pkg>/src/files/<path> (the canonical adapter / base-skills location).
  3. Edit .claude/<same-path> (the hand-built reference).
  4. pnpm build regenerates dist/files/.
  5. Run the integration test + dogfood compare:
pnpm --filter aidokit test test/integration/init-emit.test.ts
mkdir /tmp/dog && cd /tmp/dog && git init
node /path/to/aidokit/packages/cli/dist/bin/aidokit.js init --adapter claude-code --stack node-ts --yes
diff -r /path/to/aidokit/.claude ./.claude
  1. Both should be empty/clean. If the dogfood diff is non-empty, you missed updating one side.
  2. Changeset (patch for fixes; minor for behavioural changes).

When the change is an intentional divergence from v4 #

This is rare. The change must be justified by an ADR.

  1. Open an ADR (how-to-write-an-adr.md) capturing what diverges from v4 and why.
  2. Update the v4 base parts in .docs/context/ to reflect the new canonical content. Mark the v4 file with a > [!IMPORTANT] callout describing the deviation and link the ADR.
  3. Update adapter + base-skills sources to emit the new content.
  4. Update the hand-built .claude/ to match.
  5. Dogfood compare clean.
  6. Changeset.

When the change is additive (new skill, new role, new schema) #

  1. Add the content to packages/<pkg>/src/files/....
  2. Add the same content to .claude/ so dogfood stays clean.
  3. If it's a base skill, add the metadata entry in packages/base-skills/src/skills.ts (see tutorials/extend-an-adapter.md).
  4. If it's a new role or watchdog script, update packages/adapter-claude-code/src/emit/<area>.ts if the emit logic needs to know about it.
  5. Update .docs/context/claude-workflow-kit-v4-base-part-3.md with the addition.
  6. Test, changeset.

Source-of-truth ordering (when sources conflict) #

From CLAUDE.md §9.3:

  1. v4 kit base parts
  2. specs in .docs/docs/specs/
  3. ADRs
  4. README / ROADMAP / ARCHITECTURE
  5. predecessor kit versions (v3, v2.1) — context only
  6. Claude Code official docs (authoritative for Claude Code primitives)
  7. user instructions
  8. general knowledge

If v4 base parts and a spec conflict, flag and ask — don't silently pick.

Example: fixing a typo in a role file #

Symptom: packages/adapter-claude-code/src/files/engine/agents/builder.md has a typo.

  1. Open .docs/context/claude-workflow-kit-v4-base-part-3.md §47 (or whichever Part-3 section ports builder.md). Confirm the v4 source is correct (no typo).
  2. Fix packages/adapter-claude-code/src/files/engine/agents/builder.md.
  3. Fix .claude/agents/builder.md (the hand-built copy).
  4. pnpm build && pnpm --filter aidokit test test/integration/init-emit.test.ts
  5. Dogfood compare clean.
  6. Changeset: patch for @aidokit/adapter-claude-code.

Common pitfalls #