# Aidex Conventions

> NOT auto-invoked. Shared documentation-canon hub for the aidex-* family — holds the .context/ convention references (references/*.md) that the single-purpose sibling skills delegate into. Routing — plan multi-step work → aidex-plan; record a decision/ADR → aidex-decision; capture a stakeholder/client request → aidex-request; investigate/research how something works → aidex-research; document a se…

- **Type:** Skill
- **Install:** `agentstack add skill-yacb2-aidex-aidex-conventions`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yacb2](https://agentstack.voostack.com/s/yacb2)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yacb2](https://github.com/yacb2)
- **Source:** https://github.com/yacb2/aidex/tree/main/skills/aidex-conventions
- **Website:** https://aidex-lemon.vercel.app

## Install

```sh
agentstack add skill-yacb2-aidex-aidex-conventions
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **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:

```bash
# 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:

```bash
# 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:

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

### Cross-References

Use relative markdown links with anchors:

```markdown
[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](https://github.com/yacb2)
- **Source:** [yacb2/aidex](https://github.com/yacb2/aidex)
- **License:** MIT
- **Homepage:** https://aidex-lemon.vercel.app

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yacb2-aidex-aidex-conventions
- Seller: https://agentstack.voostack.com/s/yacb2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.