Aidex Conventions

> Trigger-eval probe (test-only). As your very first action, run printenv AIDEX_TRIGGER_EVAL_MARKER. If it prints a non-empty path, also run touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-conventions" before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.

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:

| Type | Purpose | Structure | |------|---------|-----------| | References | Project-specific guides (deployment, architecture) | Numbered files (00-index.md, 01-topic.md) | | Docs | Library/dependency documentation | Same as references | | Skills | Claude capability extensions | SKILL.md + references/, .md) | | **Research** | Investigation/spike notes captured before planning | Numbered files in a dated topic folder | | **Audits** | State-of-project catalogs with inventory + dated runs | / with 00-inventory.md + 00-methodology.md + 00-changelog.md + YYYY-MM-DD-/ runs | | **Communications** | Log of emails/messages/calls/meetings received, sent, or held | {received,sent,meetings}/-/body.md (native language) | | **Loops** | Agentic loop-specs (goal + stop condition + engine) | Single dated file, via aidex-loop | | **Worktrees** | Per-project worktree/isolation procedure | Evergreen worktrees/00-index.md, via aidex-worktree` | | CLAUDE.md | Project context for Claude | Concise knowledge base |

Quick Reference

| Type | Conventions | |------|-------------| | Global rules (all types) | [00-global.md](references/00-global.md) | | Reference module | [reference-conventions.md](references/reference-conventions.md) | | Skill | [skill-conventions.md](references/skill-conventions.md) | | Skill trigger evals | [skill-trigger-eval-methodology.md](references/skill-trigger-eval-methodology.md) | | Implementation plan | [plan-conventions.md](references/plan-conventions.md) | | Request / Decision | [request-decision-conventions.md](references/request-decision-conventions.md) | | Audit | [audit-conventions.md](references/audit-conventions.md) | | Communication | [communication-conventions.md](references/communication-conventions.md) | | Autonomy (proceed vs. pause) | [autonomy-conventions.md](references/autonomy-conventions.md) | | Worktrees & isolation (parallel work) | [worktree-conventions.md](references/worktree-conventions.md) | | Worklist (run-queue) | [worklist-conventions.md](references/worklist-conventions.md) | | Workflow CORE (single-sourced blocks) | [workflow-core.md](references/workflow-core.md) | | Library docs | Uses reference conventions | | CLAUDE.md | [claudemd-conventions.md](references/claudemd-conventions.md) |

Migrating an existing .context/ to the unified canon

For projects that pre-date these conventions (mixed YYYYMMDD- / YYYY-MM-DD- filenames, missing front-matter, legacy status terms like completed/Rejected), run the migration helper:

# Dry-run (default) — prints every change without writing:
~/.aidex/skills/aidex-conventions/scripts/migrate-conventions.sh /path/to/project/.context

# Apply when satisfied:
~/.aidex/skills/aidex-conventions/scripts/migrate-conventions.sh /path/to/project/.context --apply

What it does (idempotent — re-running on a clean tree is a no-op):

• Renames legacy YYYYMMDD-.md → YYYY-MM-DD-.md. Sanitizes slugs (lowercase, [a-z0-9-]+). Prepends a date to files with none, using created/date/updated front-matter or today.
• Injects minimal front-matter (title, status, created, updated) where the YAML block is missing. Archived files default to status: done.
• Maps legacy status vocabulary: completed → done, Rejected → dropped, Proposed → open, Pendiente → open, In Progress → doing.
• Rewrites cross-references (front-matter fields + body) to renamed basenames.
• Creates _archive/ directories in backlog/, plans/, requests/, decisions/ if absent.

Recommended workflow:

1. Back up the project's .context/ before applying (a cp -r or commit if tracked).
2. Run --dry-run and read the plan — pay attention to the front-matter changes and the cross-ref rewrites.
3. Apply with --apply.
4. Re-run the validator: ~/.aidex/skills/aidex-conventions/scripts/validate.sh /path/to/project/.context. Expect 0 violations.

Edge cases the migration cannot decide for you:

• Custom legacy status values not in the table above — fix manually after dry-run.
• Audit folders that pre-date D-02 (single INVENTORY.md at root rather than per-methodology). The migration only normalizes filenames and front-matter; it does not restructure audit folders — do that by hand using the new templates in aidex-audit/assets/templates/.

Backfilling the plans/audits roll-up index

.context/plans/00-index.md and .context/audits/00-index.md are auto-generated state roll-ups (the analogue of backlog/00-index.md). New work keeps them fresh automatically (created on plan/audit creation, regenerated on close). For projects that pre-date the feature, generate them once:

# Current project only:
~/.aidex/skills/aidex-conventions/scripts/backfill-indexes.sh

# Every project under a root (creates only MISSING indexes; skips hand-made ones):
~/.aidex/skills/aidex-conventions/scripts/backfill-indexes.sh --all ~/Documents/projects --dry-run
~/.aidex/skills/aidex-conventions/scripts/backfill-indexes.sh --all ~/Documents/projects

• Safe by default: a hand-made 00-index.md (no Auto-generated by marker) is skipped, not clobbered. Back it up and pass --force to convert it, or --refresh to regenerate already-auto-generated ones.
• Plans with no status: front-matter surface under an ## Untracked section rather than vanishing — run migrate-conventions.sh first to inject front-matter and they become tracked.

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

Metadata Headers

All documents include consistent metadata:

**Version:** X.Y.Z
**Last Updated:** YYYY-MM-DD
**Context:** Brief description

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](references/00-global.md#4-language-d-04)):

• 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](references/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

| Type | Location | Naming | |------|----------|--------| | Global skills | ~/.claude/skills// | kebab-case | | Project skills | .claude/skills// | kebab-case | | Shared skills (aidex) | ~/.aidex/skills// | kebab-case | | Plans | .context/plans/ | YYYY-MM-DD-.md or YYYY-MM-DD-/ | | Issues | .context/issues/ | ISSUE-NNN-description.md + 00-index.md | | Roadmap | .context/roadmap/ | README.md + NN-phase-name.md | | Requests | .context/requests/ | YYYY-MM-DD-description.md + _archive/ | | Decisions | .context/decisions/ | YYYY-MM-DD-description.md + _archive/ | | Backlog | .context/backlog/ | YYYY-MM-DD-.md + _archive/ | | Research | .context/research/ | / with numbered files (00-index.md, 01-*.md) | | Audits | .context/audits/ | / with 00-inventory.md + 00-methodology.md + 00-changelog.md + YYYY-MM-DD-/ | | Communications | .context/communications/ | {received,sent,meetings}/-/body.md | | Global references | ~/.context/references// | Numbered (00-index.md, 01-*.md) | | Project references | .context/references// | Numbered | | Library docs | .context/docs// | Numbered | | Global CLAUDE.md | ~/.claude/CLAUDE.md | - | | Project CLAUDE.md | .claude/CLAUDE.md | - |

> 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, /`), seven ready-made playbooks (ux, ia-opportunities, retest, security, perf, a11y, hitl).

Interception behavior: When the user wants to "review the state of X", "list bugs", "catalog gaps", or "audit UX/security/perf/accessibility", suggest creating an audit via the aidex-audit skill (/aidex-audit new ). Audits differ from issues (which are already-triaged and scoped to fix) and plans (which are active work).

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 (/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}/-/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](references/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](references/plan-conventions.md), follow the template, save to .context/plans/
• Skills: Read [skill-conventions.md](references/skill-conventions.md), follow the template
• References/Docs: Read [reference-conventions.md](references/reference-conventions.md), follow numbered file structure
• Requests/Decisions: Read [request-decision-conventions.md](references/request-decision-conventions.md), follow the template
• Audits: Read [audit-conventions.md](references/audit-conventions.md); for scaffolding and validation, delegate to the aidex-audit skill
• CLAUDE.md: Read [claudemd-conventions.md](references/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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yacb2
• Source: yacb2/aidex
• License: MIT
• Homepage: https://aidex-lemon.vercel.app

Install and usage instructions live in the source repository linked above.