From 771fb04f5a6ded7c0042a152a96409ff0bb19b41 Mon Sep 17 00:00:00 2001 From: Damian Galarza Date: Fri, 20 Mar 2026 14:04:14 -0400 Subject: [PATCH] feat: add domain knowledge documentation to agent-ready plugin --- .../agent-ready/skills/agent-ready/SKILL.md | 38 +++++++++- .../agent-ready/assets/claude-md-template.md | 1 + .../assets/docs-structure-template.md | 4 + .../assets/domain-knowledge-template.md | 74 +++++++++++++++++++ 4 files changed, 114 insertions(+), 3 deletions(-) create mode 100644 plugins/agent-ready/skills/agent-ready/assets/domain-knowledge-template.md diff --git a/plugins/agent-ready/skills/agent-ready/SKILL.md b/plugins/agent-ready/skills/agent-ready/SKILL.md index 1dd7de1..c00a876 100644 --- a/plugins/agent-ready/skills/agent-ready/SKILL.md +++ b/plugins/agent-ready/skills/agent-ready/SKILL.md @@ -90,6 +90,7 @@ Present a clear inventory to the user: - docs/ directory structure - docs/README.md (documentation index) - ARCHITECTURE.md (codemap, invariants, boundaries) +- docs/DOMAIN.md (business domain knowledge, terminology, workflows) - AGENTS.md (progressive disclosure entry point) - CLAUDE.md (symlink to AGENTS.md for Claude Code compatibility) - docs/decisions/001-agent-ready-documentation.md (starter ADR) @@ -110,11 +111,38 @@ Create `docs/README.md` as an index. Populate it based on what documentation exi Execute the **architecture** mode logic (see below) inline. Do not launch a separate agent. -### Step 5: Generate AGENTS.md +### Step 5: Generate docs/DOMAIN.md + +Read `assets/domain-knowledge-template.md` for the template. + +Seed the template by scanning the codebase: + +```bash +# Find model/entity/type names +find . -type f \( -name "*.rb" -o -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.java" \) 2>/dev/null \ + | grep -v node_modules | grep -v .git | grep -v vendor \ + | xargs grep -lE "class |model |entity |type |interface |struct " 2>/dev/null | head -20 + +# Look for model directories +find . -type d \( -name "models" -o -name "entities" -o -name "types" -o -name "schemas" -o -name "domain" \) 2>/dev/null \ + | grep -v node_modules | grep -v .git | grep -v vendor + +# Read README for business context +cat README.md 2>/dev/null | head -80 +``` + +Using the discovered model/entity names and README context: +1. Populate the glossary with discovered terms, even if definitions are thin -- mark them with `` +2. Sketch domain relationships based on model associations or naming patterns +3. Leave workflow and regulatory sections as template placeholders if not enough context exists + +Write the result to `docs/DOMAIN.md`. Note in the output that this file should be reviewed and filled in by domain experts on the team -- it is seeded from code analysis and will have gaps. + +### Step 6: Generate AGENTS.md Execute the **agents-md** mode logic (see below) inline. Do not launch a separate agent. -### Step 6: Create Starter ADR +### Step 7: Create Starter ADR Create `docs/decisions/001-agent-ready-documentation.md`: @@ -132,6 +160,7 @@ Adopt a progressive disclosure documentation structure: - AGENTS.md as a concise entry point (~100 lines) with markdown links to detailed docs - CLAUDE.md as a symlink to AGENTS.md for Claude Code compatibility - ARCHITECTURE.md as a codemap with invariants and boundaries +- docs/DOMAIN.md for business domain knowledge, terminology, and workflows - docs/ directory for guides, references, and decision records - Nested AGENTS.md files for major domain directories (as needed) @@ -146,9 +175,10 @@ Adopt a progressive disclosure documentation structure: - No structured docs, rely on code comments -- rejected because agents need navigational aids beyond inline comments ``` -### Step 7: Summary +### Step 8: Summary Present everything created with file paths, and suggest next steps: +- Review `docs/DOMAIN.md` and add business domain definitions -- this is the most valuable file for human and AI onboarding - Add domain-specific nested AGENTS.md files for major directories - Start writing ADRs for future architectural decisions - Set up CI checks for documentation freshness @@ -446,6 +476,7 @@ find AGENTS.md CLAUDE.md docs/ -type f 2>/dev/null | xargs grep -rn "source of t ### Step 4: Coverage Checks +- **Domain knowledge documentation:** Check if `docs/DOMAIN.md` exists. If it exists, check whether it is populated (has content beyond the template placeholders) or is still a stub. If missing, flag it as a coverage gap with the recommendation: "Create docs/DOMAIN.md to document business domain concepts -- this is the most valuable file for human and AI onboarding." - **Domain directories without nested AGENTS.md:** Find major source directories that could benefit from domain-specific AGENTS.md files - **Unlisted directories in ARCHITECTURE.md:** Find top-level source directories not mentioned in the codemap - **Missing docs/ categories:** Check if guides/, references/, decisions/ exist and have content @@ -463,6 +494,7 @@ Present an actionable report: | AGENTS.md (root) | [Present/Missing] | ./AGENTS.md | [N] | | CLAUDE.md (symlink) | [Correct symlink/Regular file/Missing] | ./CLAUDE.md | — | | ARCHITECTURE.md | [Present/Missing] | ./ARCHITECTURE.md | [N] | +| DOMAIN.md | [Present/Stub/Missing] | ./docs/DOMAIN.md | [N] | | docs/ index | [Present/Missing] | ./docs/README.md | [N] | | ADRs | [N found] | ./docs/decisions/ | — | | Nested AGENTS.md | [N found] | [locations] | — | diff --git a/plugins/agent-ready/skills/agent-ready/assets/claude-md-template.md b/plugins/agent-ready/skills/agent-ready/assets/claude-md-template.md index eeae1ef..b7d3d2e 100644 --- a/plugins/agent-ready/skills/agent-ready/assets/claude-md-template.md +++ b/plugins/agent-ready/skills/agent-ready/assets/claude-md-template.md @@ -28,6 +28,7 @@ Note: This file will be created as AGENTS.md, and CLAUDE.md will be a symlink to ## Architecture See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full codemap. +- [Domain Knowledge](docs/DOMAIN.md) -- business concepts, terminology, and workflows - [Key architectural fact 1 -- e.g., "Monorepo with packages/ for shared code and apps/ for deployables"] - [Key architectural fact 2 -- e.g., "Domain logic lives in src/domains/, each domain is self-contained"] diff --git a/plugins/agent-ready/skills/agent-ready/assets/docs-structure-template.md b/plugins/agent-ready/skills/agent-ready/assets/docs-structure-template.md index feff078..3c5d981 100644 --- a/plugins/agent-ready/skills/agent-ready/assets/docs-structure-template.md +++ b/plugins/agent-ready/skills/agent-ready/assets/docs-structure-template.md @@ -7,6 +7,7 @@ Recommended documentation layout for agent-ready codebases. Adapt based on proje ``` docs/ ├── README.md # Documentation index -- start here +├── DOMAIN.md # Business domain knowledge, terminology, workflows ├── architecture/ # Design documents │ ├── [feature-name].md # Design doc for a specific feature or system │ └── ... @@ -37,6 +38,9 @@ Index of project documentation. Start here to find what you need. ## Architecture - [ARCHITECTURE.md](../ARCHITECTURE.md) -- System overview, codemap, invariants, and boundaries +## Domain Knowledge +- [DOMAIN.md](./DOMAIN.md) -- Business concepts, terminology, and workflows the code implements + ## Design Documents - [docs/architecture/[name].md](./architecture/[name].md) -- [Brief description] diff --git a/plugins/agent-ready/skills/agent-ready/assets/domain-knowledge-template.md b/plugins/agent-ready/skills/agent-ready/assets/domain-knowledge-template.md new file mode 100644 index 0000000..181fcd0 --- /dev/null +++ b/plugins/agent-ready/skills/agent-ready/assets/domain-knowledge-template.md @@ -0,0 +1,74 @@ +# Domain Knowledge Template + +Use this template when generating a DOMAIN.md. Seed sections by scanning model names, entity types, and README content from the codebase. Mark thin definitions for team review rather than leaving them blank. + +--- + +```markdown +# Domain Knowledge + + + +## Glossary + +Business terms the code implements. Not code terms -- if it only exists in code and has no business meaning, it belongs in ARCHITECTURE.md. + +- **[Term]** -- [Definition in 1-2 sentences. What is this in the real world?] Maps to `[model_or_class_name]` in codebase. +- **[Term]** -- [Definition.] Maps to `[model_or_class_name]` in codebase. +- **[Term]** -- [Definition.] + +## Core Workflows + +Key business processes the system models. Describe what happens from a business perspective, not implementation details. + +### [Workflow Name] +- **Trigger:** [What initiates this process -- e.g., "A creator connects their YouTube channel"] +- **What happens:** [The business steps -- e.g., "Channel metrics are synced, historical videos are imported, an initial performance report is generated"] +- **Outcome:** [The end state -- e.g., "Creator has a dashboard with channel analytics and content recommendations"] +- **Key models:** `[Model1]`, `[Model2]`, `[Model3]` + +### [Workflow Name] +- **Trigger:** [What initiates this] +- **What happens:** [Business steps] +- **Outcome:** [End state] +- **Key models:** `[Model1]`, `[Model2]` + +## Domain Relationships + +How major business concepts relate to each other. Write in plain English. + +- [Relationship 1 -- e.g., "A Creator has many Channels. Each Channel has many Videos."] +- [Relationship 2 -- e.g., "A Video has one Performance Report. Reports are regenerated daily from platform analytics."] +- [Relationship 3 -- e.g., "Sponsors are matched to Creators based on audience overlap scores."] + +## Regulatory / Compliance Context + + + +Industry-specific rules the code must respect. These constraints explain why certain things work the way they do. + +- [Rule 1 -- e.g., "OAuth tokens must be encrypted at rest per platform API terms of service"] +- [Rule 2 -- e.g., "User analytics data must be anonymized after 90 days per privacy policy"] +- [Rule 3 -- e.g., "API rate limits must be respected -- YouTube Data API v3 allows 10,000 quota units per day"] +``` + +--- + +## Template Notes + +**This documents business concepts, not code patterns.** Code architecture, module boundaries, and technical invariants go in ARCHITECTURE.md. DOMAIN.md answers "what does the product do and why?" -- the knowledge that lives in domain experts' heads and product docs, not in the code itself. + +**Keep glossary entries to 2-3 sentences max.** If a concept needs a full explanation, link to a dedicated doc in `docs/references/`. The glossary is a quick-reference lookup, not a textbook. + +**Link to code when helpful, but focus on the "what" and "why", not the "how."** Including model names and service names helps agents navigate the codebase. But the definition should make sense to someone who has never read the code. + +**Update when new domain concepts are introduced in code.** If a PR adds a new model that represents a business concept, DOMAIN.md should get an entry. Treat it like updating a schema migration -- part of the change, not a follow-up task. + +**Engineers who join should be able to read this and understand what the product does,** not just how the code is structured. This is the file you wish existed on your first week. + +**Even a partially-filled DOMAIN.md is better than nothing.** Bootstrap it with what you can discover from model names, database schemas, and the README. Mark gaps with `` for the team to fill in. A stub with real terms and thin definitions beats a perfect document that never gets written. + +**This file is especially valuable for AI agents working in the codebase.** Agents can reference it to understand business intent behind code changes, write more accurate tests, and avoid violating domain rules they would otherwise have no way to discover.