Documentation Guidelines

These rules define our monorepo documentation and AI agent orchestration strategy. Human intent remains the immutable core; AI acts as the executor.

1. Core Principles

• Code = The "What": Rely on self-documenting code. Do not document mechanics in abstract files.
• Abstract = The "Why" (Intention): Stable, human-authored rules and business logic.
• Concrete = The "How" (Implementation): Avoid implementation details in conceptual documentation to prevent rot.
• Bounded Context: Place documentation adjacent to relevant code. Avoid centralized wikis.
• Conventional Commits: Humans must use structured commit messages (e.g., feat:, fix:, docs:). This allows the agent to easily parse intent without reading every line of diff logic.

2. "Shared Brain" Monorepo Architecture

Maintain isolated contexts for different tools while centralizing rules to prevent agent drift.

Directory Structure

→ See Repository Structure for the canonical directory layout.

3. PARA Classification

Every file under docs/ carries a para_category frontmatter field that directs AI agent behavior, determines file placement, and governs the document's lifecycle.

→ See PARA Reference for category definitions, state transitions, content lifecycle rules, and the content placement guide.

Frontmatter Spec

→ See ADR-034 for the authoritative frontmatter schema specification.

Required fields: para_category and date_last_reviewed on every docs/**/*.md file.

Optional fields: tags:, related:, summary:, code_refs:, sources:, expires_on:.

When to use which

Question	Answer
Applies to >5 files and describes an axis?	→ tags:
Specific reference to 1 other file?	→ related:
Property of the file (tech, audience, type)?	→ tags:
Content that lives in more detail elsewhere?	→ related: with comment
Changes frequently?	→ Neither — that belongs in Git/PR metadata
One-liner describing the file's purpose?	→ summary:
Where in the codebase does this live?	→ code_refs:
External law, RFC, or vendor spec?	→ sources:

When uncertain, prefer related: over a broad tag. A too-broad tag dilutes the tag system for all files; an unnecessary related: entry only affects the local file.

ADR exception

ADRs receive tags: and summary: (both are classification metadata) but NOT related: or code_refs: (curated edges and code pointers count as content modification — code references evolve post-decision). ADRs remain immutable historical records. See ADR-034 for the full schema specification.

Pre-Commit Enforcement

A pre-commit hook validates that every docs/**/*.md file has the required para_category and date_last_reviewed frontmatter fields, and that para_category contains a valid value. The Node.js linter (scripts/lint-docs.mjs) additionally validates tags: against docs/.tags.yml, checks that related: paths resolve to existing files, and enforces summary, code_refs, and sources constraints.

Content Placement

→ See the Content Placement Guide in the PARA Reference for the full content-type-to-folder mapping.

4. Package/App README Standard

Every top-level app or package README should answer:

1. Purpose — why this package/app exists.
2. Public API / entrypoints — what consumers may import or run.
3. Key commands — dev, test, build, codegen, preview, if applicable.
4. Ownership / consumers — who depends on it and who should review changes.
5. Related docs — area/resource docs that define its architecture or contracts.
6. Common pitfalls — constraints that are easy to violate.

Use readme.md for new top-level READMEs.

5. Separation of Duties (Agent Roles)

All AI agents share a single centralized configuration under .agents/ — skills, workflows, prompts, and docs. Tool-specific entry points (CLAUDE.md, etc.) contain only minimal pointers to README.md and .agents/.

• IDE Coding Agents (Antigravity, Claude Code, etc.): Primary agents for feature development, system architecture, and multi-file execution. Load domain-specific skills from .agents/skills/ based on task context.
• Domain skills accumulate learnings on accessibility, security, performance, and infrastructure patterns. See .agents/skills/ for the full catalog.

6. Artifacts & The Handoff Workflow

1. Generate: Use Antigravity to generate high-level Markdown plans (implementation plans, walkthroughs, task lists).
2. Store: Antigravity manages artifact storage internally in its own data directory.
3. Execute (Handoff): Instruct the terminal agent to read and execute the plan.

7. AI Constraints

• Model Redundancy: Write model-agnostic system prompts.
• The "Ruthless Editor" Rule: Strip fluff. Force structural outputs (JSON, YAML, Markdown) with strict limits.
• Pruning: Agents manage their own context windows via internal knowledge stores and conversation summaries.