Kit Content (v4)

Purpose #

Clarify the relationship between the v4 kit base parts in .docs/context/ and what the Claude Code adapter actually emits.

Big Picture #

The "kit content" is the body of skills, agents, hooks, slash commands, output styles, and JSON schemas that lives inside the emitted .claude/ engine directory. It is the operational substance of the workflow.

The v4 base parts are the reference for that content:

The Claude Code adapter (@aidokit/adapter-claude-code) and the base skills package (@aidokit/base-skills) port that content into checked-in files under src/files/ and emit it at aidokit init time.

The dogfood gate (see dogfood-gate.md) makes this relationship enforceable.

How It Works #

What the adapter and base-skills package port from v4 #

From CHANGELOG.md [0.1.0-alpha] — these slices have been ported verbatim:

The # Title headings are stripped from the skill bodies; the adapter's emitSkills re-adds the heading from SkillTemplate.name.

How the data flows at init #

@aidokit/base-skills  →  CORE_BASE_SKILLS (SkillTemplate[])
                                     │
                                     ▼
                         @aidokit/cli (init/file-plan)
                                     │
@aidokit/adapter-claude-code:
  emitAgentRulesFile  ──► reads src/files/agent-rules.md
  emitEngineConfig    ──► reads src/files/engine/settings.json + schemas
  emitVerbs           ──► reads src/files/engine/commands/*.md
  emitRoles           ──► reads src/files/engine/agents/*.md
  emitSkills(skills)  ──► reads body via @aidokit/base-skills + re-adds heading
  emitWatchdog        ──► reads src/files/engine/scripts/*.mjs (mode 0o755)
  emitOutputStyles    ──► reads src/files/engine/output-styles/*
                                     │
                                     ▼
                          EmittedFile[] → staged write

Variable interpolation #

The CLI interpolates a small variable set ({{projectName}}, {{validationCommands}}, {{kitVersion}}, {{specVersion}}, {{aidoCliVersion}}) via the helper in @aidokit/core. Anything more complex (conditionals, loops) is generated programmatically — never via a template engine (CLAUDE.md §8, .docs/ARCHITECTURE.md §11.2).

Source-of-truth ordering #

From CLAUDE.md §9.3, when sources conflict:

1. v4 kit base parts (Parts 1/2/3)
2. Product 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 a v4 base doc conflicts with a spec, flag it as > [!TODO] and stop — do not silently pick one.

Known fidelity gap #

The v4 SKILL.md frontmatter fields description and allowed-tools are tracked in ADR-0013. The current state per CHANGELOG.md [0.5.0] is implemented: SkillTemplate carries optional description + allowedTools; @aidokit/base-skills populates them for all 18; adapter-claude-code's emitSkills writes them with a synthesised fallback.

Example: where a v4 skill ends up #

A v4 skill architecture-summary exists in Part 3 §51. The body (without its # Title) is checked into packages/base-skills/src/files/skills/architecture-summary.md. The metadata table in packages/base-skills/src/skills.ts records its name, preloadedBy (from the v4 agent skills: frontmatter), and required flag.

At aidokit init, the CLI passes BASE_SKILLS to claudeCodeAdapter.emitSkills(ctx, [...BASE_SKILLS, ...packSkills]). The adapter writes .claude/skills/architecture-summary/SKILL.md with the # Architecture summary heading re-added and frontmatter built from the metadata.

Common Mistakes #

• Editing emitted content in dist/files/ — that directory is built from src/files/ by scripts/copy-files.mjs and would be overwritten.
• Changing a skill body without re-reading the v4 source. v4 base parts are the de-facto reference. If you must diverge, capture it as an ADR.
• Inventing a v4-shaped artifact that doesn't appear in Parts 1/2/3. Flag the gap as > [!TODO] instead of guessing.
• Adding a template engine to handle conditionals. Use programmatic emission inside the adapter instead (.docs/ARCHITECTURE.md §2.1).

Checklist when editing emitted content #

• [ ] Located the v4 source section in .docs/context/claude-workflow-kit-v4-base-part-{1,2,3}.md.
• [ ] Edited src/files/... not dist/files/....
• [ ] Re-ran pnpm build so dist/files/ is regenerated.
• [ ] Re-ran the integration test that asserts on the emitted tree.
• [ ] Re-ran the dogfood byte-compare (post-Phase 8).
• [ ] Updated the corresponding v4 base part or filed an ADR if the divergence is intentional.

Related Pages #

• dogfood-gate.md
• three-layer-architecture.md
• ../how-to-guides/how-to-update-the-v4-reference.md
• .docs/context/claude-workflow-kit-v4-base-part-3.md