Aidex Conventions

Documentation Standards

Canon hub — NOT model-invoked (disable-model-invocation: true). This skill is no longer an entry point. It exists to own and host the shared .context/ convention canon in references/*.md, which the single-purpose sibling skills read and delegate into. To actually create an artifact, the matching sibling fires: planning → aidex-plan, decisions → aidex-decision, requests → aidex-request, research → aidex-research, references → aidex-reference, skill-conventions checks → aidex-skill. Everything below is the canon index, not an active workflow.

Standards for consistent documentation structure in Claude Code projects.

Overview

This skill defines conventions for thirteen documentation types:

Quick Reference

This table is a dispatch table, not a reading list. Find the row for the artifact kind you are about to write or judge, and read that one file in full before writing anything — the files live in ~/.claude/skills/aidex-conventions/references/. Working from the summary in rules/aidex-conventions.md is enough to recognize a convention and never enough to apply one: the per-type file owns the front-matter schema, the status vocabulary and the archive rule that validate.py actually enforces.

Migrating an existing .context/ to the unified canon

For a project that pre-dates these conventions — mixed YYYYMMDD- filenames, missing front-matter, legacy status terms, no roll-up indexes — read ~/.claude/skills/aidex-conventions/references/migration-guide.md and follow it. It holds the migrate-conventions.py invocation and its dry-run-by-default contract, what the migration does and deliberately does not restructure, the manual-review cases it declines out loud, and the separate backfill for plans/00-index.md and audits/00-index.md including the safety rule that a hand-made index is skipped, not clobbered.

Core Principles

Progressive Disclosure

1. Index/overview first - Always visible, provides navigation
2. Detailed modules - Loaded as needed
3. Cross-references - Enable discovery without bloating context

Front-matter

Every file-based artifact carries the D-07 minimum (00-global.md §7) — the four fields validate.py requires:

---
title: "Human-readable, quoted"
status: <per-type vocabulary>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Cross-References

Use relative markdown links with anchors:

[Description](./NN-filename.md#section-anchor)

Language

Language is scoped by artifact kind (see 00-global.md §4):

• Knowledge artifacts → English (always): plans, decisions, requests, research, references, docs, audits, backlog, loops, CLAUDE.md, and skill prose. This keeps cross-project uniformity and skill matching predictable.
• Communications → the language of the communication: communications/ bodies follow the interlocutor's language (never translate a Spanish client email to English). Front-matter keys stay English; values are as-is. See communication-conventions.md.
• Code + code comments → English (unchanged).

Skill descriptions stay English-only regardless (D-11). The assistant continues to reply in the user's spoken language; only the written artifacts above are constrained.

Canonical File Locations

Resolution: Project-level skills override global skills of the same name. When updating a skill, verify its location first.

When to Use Each Type

References

Project-specific multi-step guides: deployment procedures, architecture documentation, setup/configuration guides, operational runbooks.

Characteristics: Numbered files, sequential or modular organization, verification steps.

Docs

Library or dependency documentation: API reference, integration guides, framework-specific patterns.

Characteristics: Same as references, focused on external tools.

Skills

Claude capability extensions: domain expertise, workflow automation, tool integrations.

Characteristics: SKILL.md entry point, references/ for details, <500 lines, negative triggers in description, testing & validation guidance.

Plans

Complex multi-session work: feature implementations, large refactoring projects, migration tasks.

Characteristics: Checkboxes for tracking, phases, exact file paths.

CLAUDE.md

Project context: tech stack overview, critical conventions, links to detailed docs.

Characteristics: Concise (<300 lines), reference-focused.

Requests

Incoming tasks, product requirements, or change requests from stakeholders. A request is a single document — if it needs deeper analysis, escalate to a plan or research.

Characteristics: Dated file, origin (who asked), description, priority/urgency, outcome (became plan, dropped).

Decisions

Architecture or product decision records. Documents what was decided, why, what alternatives were considered, and the outcome. Prevents revisiting the same debates.

Characteristics: Dated file, context/problem, options considered, decision taken, rationale, status (accepted/superseded/dropped).

Audits

State-of-project catalogs. An audit describes what is (findings, gaps, risks, opportunities), distinct from plans which describe what will be. Every finding lives in a canonical 00-inventory.md and is referenced (not copied) from per-run findings.md views.

Characteristics: per-methodology 00-inventory.md as source of truth, 00-methodology.md as living playbook with 00-changelog.md, dated per-run folders (YYYY-MM-DD-<slug>/), ready-made playbooks (ux, ai-opportunities, retest, security, perf, a11y, hitl, test-coverage, docs-coverage, rule-ablation).

Audits differ from issues (already-triaged and scoped to fix) and from plans (active work). Scaffolding and validation belong to the aidex-audit skill.

Backlog

Deferred or parked ideas: work the team intends to do later but is not acting on now. A backlog entry captures the idea, why it is deferred, and what would trigger picking it up — created via the aidex-backlog skill.

Characteristics: Single dated file, status lifecycle (open → doing → done/dropped), priority, optional link to the plan or loop-spec that picks it up.

Research

Investigation or spike notes captured before a plan or implementation exists: how something works, what the options are, what an experiment found — created via the aidex-research skill.

Characteristics: Numbered files in a dated topic folder (<topic>/00-index.md, 01-*.md), findings referenced (not duplicated) by later plans/decisions.

Communications

A log of emails, WhatsApp messages, calls, and meetings — received from or sent to a stakeholder/client, or held synchronously — captured so the thread is searchable and cross-linkable to plans/decisions/requests. Created via the aidex-comm skill.

Characteristics: {received,sent,meetings}/<YYYY-MM-DD>-<slug>/body.md (attachments alongside; synchronous records live in meetings/ with a participants list instead of direction/from/to), front-matter (channel, direction, from/to, subject, date, status for the sent side, related: [], created, updated). Body text is in the native language of the communication — communications are exempt from the English-only rule (front-matter keys stay English). See communication-conventions.md.

Plan: Modular vs Single-File

Single-file (default):

• Up to 4 phases
• Less than 20 tasks total
• Small-medium project

Multi-file (directory with 00-index.md):

• 5+ phases
• 20+ tasks
• Large or multi-layer project (backend + frontend + infra)
• Phases executed by different sessions/teammates

Workflow Integration

aidex-conventions provides structural conventions for documentation. To create or validate documentation:

• Plans: Read plan-conventions.md, follow the template, save to .context/plans/
• Skills: Read skill-conventions.md, follow the template
• References/Docs: Read reference-conventions.md, follow numbered file structure
• Requests/Decisions: Read request-decision-conventions.md, follow the template
• Audits: Read audit-conventions.md; for scaffolding and validation, delegate to the aidex-audit skill
• CLAUDE.md: Read claudemd-conventions.md, validate against conventions

Complementary skills (e.g., skill-creator for behavioral testing, TDD workflows) can extend these conventions with execution tracking.

Syncing Documentation

When documentation needs updating from official sources:

For skills: Extract version + Resources section from SKILL.md → resolve Context7 library ID → fetch latest → compare → report changes → apply with approval.

For references (code-based): Compare documented file paths and code snippets against actual project code → flag drift.

For docs (library-based): Compare documented library version against package.json/pyproject.toml → detect minor/feature/major version changes → incremental sync or full regeneration.

Related

• Auditing and fixing: Use the aidex skill (/aidex) for ecosystem audits and automated fixes
• Agent definitions: aidex skill contains the subagent specifications used during audits