adc: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

This is a documentation-first repository for the Agent Decision Comments convention. README.md is the canonical specification: it defines the four directives, their format, scope, examples, review workflow, and current version. skills/adc/SKILL.md is the compact operational convention. Skill-aware agents install it directly; other adopting repositories copy it to ADC.md. Agents read it on every task, so keep it short. Keep it consistent with the full specification: every rule and example it states must match README.md, and both files must carry the same specification version. LICENSE contains the MIT license. There are currently no source, test, generated, or asset directories. Keep other documentation at the repository root unless a larger collection clearly warrants a focused directory such as examples/.

Build, Test, and Development Commands

This repository produces no build artifact. Markdown linting is its primary CI check. Run these commands before submitting a change:

• npx --yes [email protected] --config .markdownlint.jsonc "**/*.md" runs the same linter version as CI.
• npx --yes skills@latest add . --list confirms that the skills CLI discovers the adc skill.
• git diff --check detects trailing whitespace and malformed patches.
• rg '^#{1,6} ' README.md AGENTS.md skills/adc/SKILL.md reviews the Markdown heading hierarchy.
• git diff -- README.md AGENTS.md skills/adc/SKILL.md gives a focused review of documentation changes.

Also render changed Markdown in a previewer and verify that fenced examples, lists, and headings display correctly.

Coding Style & Naming Conventions

Write concise Markdown with ATX headings (## Heading), fenced code blocks with language tags, and hyphenated bullets. Follow the existing prose style: short paragraphs, direct present-tense statements, and one sentence per line when practical. Use the exact lowercase directive labels decision:, invariant:, assumption:, and tradeoff:. Examples should demonstrate non-obvious rationale rather than restate code behavior. The Markdownlint configuration excludes code blocks from MD013; directives must remain on one physical line. In docstrings and documentation comments, place normal prose before the directives with a blank line between them. Use ordinary comments for directive-only examples.