feat: add domain knowledge documentation to agent-ready plugin

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 `<!-- TODO: needs domain expert review -->`
+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] | — |

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"]

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]
 

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
+
+<!-- This file documents the business domain this codebase implements.
+     It answers "what does this system do?" not "how is the code structured?"
+     For code architecture, see ARCHITECTURE.md.
+     Maintainers: update this when new domain concepts are introduced in code. -->
+
+## 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.] <!-- TODO: needs domain expert review -->
+
+## 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
+
+<!-- Optional: remove this section if the domain has no regulatory requirements. -->
+
+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 `<!-- TODO: needs domain expert review -->` 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.