Documentation Standards

Purpose #

How docs are structured in this repo: specs, ADRs, wiki, READMEs, and CHANGELOG. Authoritative tone and structure rules.

Where docs live #

Conventions #

RFC 2119 in specs #

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, REQUIRED — uppercase, normative meaning.

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
6. Claude Code official docs (for Claude Code primitives)
7. user instructions
8. general knowledge

Path discrepancy: .docs/ on disk, docs/ published #

Design docs live under .docs/ (hidden) on disk. References in wiki pages should use .docs/... until the directory is flattened (CLAUDE.md §2).

CHANGELOG #

Keep a Changelog format. Sections: Added, Changed, Deprecated, Removed, Fixed, Security. Per-package CHANGELOGs are generated by Changesets at release time; the repo-root CHANGELOG.md carries the narrative pre-0.5 history and the curated overview going forward.

Markdown style #

• Short paragraphs.
• Tables for comparisons.
• Numbered steps for procedures.
• Mermaid for flows.
• Callouts: > [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT], > [!TODO].
• File and command names in backticks.
• Package names always fully qualified (@aidokit/adapter-claude-code) on first mention per page.
• No emojis. No marketing language.
• Cross-link to .docs/ files using relative paths from the wiki page.

> [!TODO] discipline #

If a fact is not derivable from the cited sources, write > [!TODO] Confirm with maintainer. Never fabricate. This is the discipline the wiki was generated under and the same one applies to subsequent updates.

ADR format #

Use the template at .docs/docs/architecture/decisions/0000-template.md. Required: Summary, Context, Decision, Consequences (Positive/Negative/Neutral), Alternatives considered (with Pros, Cons, Reason rejected), Implementation notes, Validation, References. See how-to-guides/how-to-write-an-adr.md.

Wiki page format #

Every wiki page follows:

# Page Title

## Purpose
Why this page exists.

## Big Picture
Plain-English summary, citing the .docs/ source.

## How It Works
Flow or process, grounded in the spec.

## Example
Realistic example using actual aidokit packages, commands, or files.

## Diagram
Mermaid diagram where useful.

## Common Mistakes
Tied to CLAUDE.md §8 anti-patterns or known footguns.

## Checklist
Practical checklist.

## Related Pages
Cross-links within the wiki + back to .docs/ source.

Not every page needs all sections. Diagrams and Examples are added when they genuinely help.

When the wiki contradicts the specs, the specs win #

The wiki is onboarding documentation. Normative claims live in .docs/docs/specs/ and ADRs. If a wiki page conflicts with a spec, update the wiki to match (or, if the wiki is right and the spec is stale, file a spec PR).

Cross-linking #

Prefer relative paths so links survive a future docs-site build. From a wiki/concepts/*.md page:

• To another concept: [adapters-and-stack-packs.md](adapters-and-stack-packs.html)
• To a reference page: [../reference/adapter-contract.md](../../reference/adapter-contract.md)
• To a spec: [.docs/docs/specs/adapter-contract.md](../../../.docs/docs/specs/adapter-contract.md)
• To CLAUDE.md: [CLAUDE.md](../../../CLAUDE.md)

When to write what #

Related Pages #

• contribution-guide.md
• code-standards.md
• ../how-to-guides/how-to-write-an-adr.md
• CLAUDE.md