Documentation Guidelines: AI-Assisted Engineering

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 Frontmatter Classification

Every file under docs/ carries a para_category frontmatter field that directs AI agent behavior and enables documentation triage.

Required Frontmatter Fields

---
para_category: area              # project | area | resource | archive
date_last_reviewed: 2026-05-02   # last human-validated date (quarterly cadence)
expires_on: 2026-06-30           # optional — only for projects with hard deadlines
---

Category Definitions

• project — Active, time-bound initiatives with an end state (BSFZ funding, GoBD compliance, GDPR migration). Agents ignore these unless the task explicitly relates to the project.
• area — Ongoing standards, living specs, and domain knowledge (architecture, product scope, DDD, design principles). These evolve but never "finish." Agents read these when working in the relevant domain.
• resource — Reference lookup material (schemas, protocols, event contracts, ADRs, runbooks). Agents read these when they need exact specs or contracts. ADRs are immutable — agents never modify them.
• archive — Completed or superseded content. Agents never read these unless explicitly asked.

→ See the Areas Index for an index of all area files.

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.

4. Evergreen vs. Snapshot Content

Keep durable intent separate from volatile implementation snapshots:

Content Type	Where It Belongs	Update Rule
Stable intent, principles, domain language	docs/2-areas/**	Keep concise and implementation-light
Exact contracts, schemas, event payloads	docs/3-resources/**	Update when the contract changes
Operational procedures	docs/3-resources/runbooks/**	Keep executable and step-oriented
Time-bound plans, checklists, migration work	docs/1-projects/**	Add expires_on when there is a hard deadline
Superseded ideas or completed context	docs/4-archive/**	Preserve only when historically useful
Package/app usage details	Adjacent README.md	Prefer colocated docs over central wiki pages

When an area doc starts accumulating step-by-step implementation details, extract those details into a resource, runbook, ADR, or colocated README and link to it.

5. 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.

6. 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 HANDBOOK.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.

7. 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.

8. 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.

9. NotebookLM Integration (Strategic Brain) — Future

Status: Planned but not yet operational. No MCP connector exists. Do not attempt to query NotebookLM.

The monorepo serves as the Execution Brain (code, tasks, specs). NotebookLM is intended as the Strategic Brain for unstructured business intelligence (competitor analysis, pricing, customer interviews).

When operational, source files will use domain-driven prefixes:

• COMPETITOR_[Name]_[Topic].pdf
• DOMAIN_[Pillar]_[Topic].md
• GLOBAL_[Topic].pdf
• CUSTOMERS_[Topic].md