@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/knowledge-architecture/05-decisions.md

@@ -0,0 +1,410 @@
+# Agent Assistant — Architecture Decision Records
+
+> **Purpose**: Key architecture decisions with choices, alternatives considered, rationale, and trade-offs
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [ADR Summary Table](#adr-summary-table)
+2. [ADR-001: Markdown as Programming Language](#adr-001-markdown-as-programming-language)
+3. [ADR-002: AI Model as Runtime](#adr-002-ai-model-as-runtime)
+4. [ADR-003: Zero Production Dependencies](#adr-003-zero-production-dependencies)
+5. [ADR-004: Platform Abstraction via Placeholder Substitution](#adr-004-platform-abstraction-via-placeholder-substitution)
+6. [ADR-005: Adversarial Collaboration (Golden Triangle)](#adr-005-adversarial-collaboration-golden-triangle)
+7. [ADR-006: HSOL Two-Layer Skill Resolution](#adr-006-hsol-two-layer-skill-resolution)
+8. [ADR-007: 10 Laws Governance Model](#adr-007-10-laws-governance-model)
+9. [Evidence Sources](#evidence-sources)
+
+---
+
+## ADR Summary Table
+
+| ADR | Decision | Status | Impact |
+|-----|----------|--------|--------|
+| 001 | Markdown as programming language | Accepted | Framework logic is human-readable and version-controllable but not unit-testable |
+| 002 | AI model as runtime | Accepted | Zero infrastructure cost; behavior varies by model capability |
+| 003 | Zero production dependencies | Accepted | Maximum portability; limited to Node.js built-in modules |
+| 004 | Platform abstraction via `{TOOL}` placeholders | Accepted | Single codebase for 5 platforms; platform-specific features are lossy |
+| 005 | Adversarial collaboration (Golden Triangle) | Accepted | Higher quality via structured debate; higher token cost for `:team` |
+| 006 | HSOL two-layer resolution | Accepted | Pre-curated baseline + community discovery; trust scoring is interpretive |
+| 007 | 10 Laws governance model | Accepted | Prevents common AI failure modes; adds per-interaction overhead |
+
+---
+
+## ADR-001: Markdown as Programming Language
+
+### Context
+
+The framework needs to define complex multi-agent workflows, routing logic, conditional execution, and structured protocols. Traditional frameworks encode this as executable code. Agent Assistant encodes framework logic as Markdown instructions that the AI model reads and follows.
+
+### Decision
+
+**Use Markdown and YAML files as the instruction set for the entire framework.**
+
+All operational logic — orchestrator identity, command routing, phase execution, agent protocols, skill resolution, team collaboration, error recovery — is expressed as structured Markdown documents. YAML is used for metadata (agent frontmatter) and data registries (matrix skills).
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| Executable code (Python/JavaScript framework) | AI models would need a wrapper to execute; adds runtime complexity; not natively readable by AI during inference |
+| JSON configuration | Less readable than Markdown; poor support for narrative instructions; no inline formatting |
+| Custom DSL | Requires parser; AI models already understand Markdown natively; additional tooling burden |
+| Mixed (code + Markdown) | Splits logic across two paradigms; harder to reason about; version control complications |
+
+### Rationale
+
+- AI models natively parse and follow Markdown instructions during inference
+- Markdown files are human-readable, version-controllable, and diffable
+- No compilation step, no build process, no runtime interpreter needed
+- Contributors can modify framework behavior by editing text files
+- The same files serve as both documentation and execution logic
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Human-readable framework logic | Cannot unit-test Markdown instructions |
+| No compilation or build step | No static analysis for errors in routing logic |
+| Version-controllable with standard Git | No type-checking for agent handoffs or phase contracts |
+| AI models follow natively | Behavior depends on model's Markdown comprehension quality |
+| Contributors need no coding skills | Framework bugs manifest as behavioral drift, not compile errors |
+
+### Evidence
+
+- All 7 rule files (`rules/*.md`) are pure Markdown with no executable code
+- All 21 agent files (`agents/*.md`) define behavior via Markdown protocols
+- All 14 command routers (`commands/*.md`) express routing logic as Markdown conditional blocks
+- `package.json` lists zero production dependencies — confirming no runtime code executes
+
+---
+
+## ADR-002: AI Model as Runtime
+
+### Context
+
+Traditional multi-agent frameworks require a server process, message queues, and orchestration infrastructure. Agent Assistant needs to run in 5 different AI coding tools with no shared backend.
+
+### Decision
+
+**The AI model itself is the runtime — there is no server, no process, no compiled binary.**
+
+The framework distributes instruction files. When a user interacts with their AI tool, the model loads these files into context and follows them as operational protocols. The "execution engine" is the AI's inference process.
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| Server-side orchestration (e.g., LangChain, CrewAI) | Requires infrastructure; doesn't work inside Cursor/Copilot/Claude contexts |
+| Browser extension with API calls | Platform-specific; requires API keys; adds latency |
+| VS Code extension with language server | Limited to VS Code; doesn't support Cursor, Claude Code, or Codex |
+| Agent marketplace with hosted execution | Vendor lock-in; cost per execution; privacy concerns |
+
+### Rationale
+
+- Zero infrastructure cost — no servers, no databases, no message queues
+- Runs wherever the AI runs — built into the tool the developer already uses
+- No authentication, no API keys, no network requirements for core operation
+- Scales trivially — each developer's AI model is their own "server"
+- Framework updates via `npm update` — no deployment pipeline needed
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Zero infrastructure cost | No server-side state between sessions |
+| Works in any AI tool's context | Behavior varies by model capability and context window |
+| No authentication required | Cannot enforce protocol compliance programmatically |
+| Trivial scaling (per-developer) | No centralized logging, monitoring, or analytics |
+| Simple distribution via npm | Framework behavior is non-deterministic (depends on AI model) |
+
+### Evidence
+
+- `package.json` has zero production dependencies and zero runtime entry points
+- `cli/install.js` only copies files — no daemon, no background process
+- Platform entry points (CLAUDE.md, etc.) are loaded by the AI at inference time, not executed
+- CORE.md defines the execution loop as behavioral instructions, not runnable code
+
+---
+
+## ADR-003: Zero Production Dependencies
+
+### Context
+
+The CLI installer needs to copy files to platform directories. The framework needs to be distributable via npm. Minimizing dependency surface reduces supply-chain risk and simplifies installation.
+
+### Decision
+
+**Use only Node.js built-in modules for the CLI. Ship zero production dependencies.**
+
+`cli/install.js` uses only `fs`, `path`, `os`, and `readline` — all built into Node.js >=18.0.0.
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| `fs-extra` for file operations | Adds a dependency for convenience methods that can be implemented with built-ins |
+| `commander` or `yargs` for CLI parsing | 14-line argument parser is sufficient for the command set |
+| `glob` for file discovery | `fs.readdirSync` with recursive option (Node 18+) handles all use cases |
+| `chalk` for terminal colors | ANSI escape codes or plain text are sufficient |
+
+### Rationale
+
+- Zero supply-chain attack surface — no third-party code executes
+- `npm install` is faster with no dependency tree to resolve
+- No version conflicts or breaking changes from upstream packages
+- Node.js 18+ provides all necessary filesystem and CLI capabilities
+- Dev dependencies (semantic-release, husky) only run in CI, not on user machines
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Zero supply-chain risk | More verbose code for file operations |
+| Faster npm install | No cross-platform path normalization library |
+| No dependency maintenance | CLI features limited to what built-ins provide |
+| Smaller package size | Custom argument parsing instead of battle-tested CLI framework |
+
+### Evidence
+
+- `package.json` `dependencies` field is absent (zero production deps)
+- `package.json` `engines.node` specifies `>=18.0.0`
+- `cli/install.js` imports: `require('node:fs')`, `require('node:path')`, `require('node:os')`, `require('node:readline')` — all `node:` prefixed built-ins
+- `devDependencies` contains only semantic-release plugins and husky (CI/dev tooling)
+
+---
+
+## ADR-004: Platform Abstraction via Placeholder Substitution
+
+### Context
+
+The framework must work identically across 5 AI platforms (Cursor, GitHub Copilot, Claude Code, Codex, Antigravity/Gemini), each with different directory conventions and configuration approaches.
+
+### Decision
+
+**Use `{TOOL}` placeholders in all source files, replaced at install time by the CLI for each target platform.**
+
+All Markdown and YAML files reference paths with `{TOOL}` (e.g., `~/.{TOOL}/skills/agent-assistant/`). When `cli/install.js` copies files to a platform directory, it performs text replacement on every file with the platform-specific values.
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| Separate file copies per platform | Duplication nightmare; changes require updating 5 copies |
+| Runtime path resolution (AI reads config) | Adds context overhead; AI might resolve incorrectly |
+| Symlinks to shared directory | Platform-specific directory structures conflict; not all OS support well |
+| Environment variables in Markdown | AI models don't resolve environment variables in Markdown context |
+
+### Rationale
+
+- Single source of truth — one copy of each file with placeholders
+- Install-time resolution is deterministic — no runtime ambiguity
+- Simple text replacement — no complex templating engine needed
+- Platform-specific assets handled separately in `code-assistants/{tool}-assistant/`
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Single codebase for 5 platforms | Cannot test platform-specific behavior without full install |
+| Deterministic install-time resolution | Platform capability differences (sub-agents, context window) are invisible |
+| No runtime path ambiguity | Files on disk are platform-specific — can't share across tools |
+| Simple text replacement | Placeholder collisions possible if `{TOOL}` appears in content |
+
+### Evidence
+
+- `cli/install.js` defines `replacements` map for each platform in the TOOLS config:
+  ```javascript
+  replacements: {
+      '~/.{TOOL}/skills/agent-assistant/': '~/.cursor/skills/agent-assistant/',
+      '{TOOL}': 'cursor',
+  }
+  ```
+- All rule files use `~/.{TOOL}/skills/agent-assistant/` paths (verified in CORE.md, SKILLS.md)
+- `package.json` has 5 install scripts: `install:cursor`, `install:copilot`, `install:antigravity`, `install:codex`, `install:all`
+
+---
+
+## ADR-005: Adversarial Collaboration (Golden Triangle)
+
+### Context
+
+Single-agent execution and parallel cooperation both have quality ceilings. The framework needs a mechanism to produce higher-quality output for high-stakes tasks.
+
+### Decision
+
+**Implement a Golden Triangle pattern: 3 agents (Tech Lead, Executor, Reviewer) per phase with structured adversarial debate capped at 3 rounds.**
+
+The Executor builds; the Reviewer challenges with a devil's advocate mindset; the Tech Lead arbitrates unresolved disputes. Consensus is required before a deliverable is released.
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| Single agent with self-review | AI models are poor at catching their own errors |
+| Parallel agents + voting | No structured debate; majority vote doesn't improve quality |
+| 4th "Devil's Advocate" agent | Adversarial tension is embedded in Reviewer personality; 4th agent adds cost without value |
+| Unlimited debate rounds | Token cost grows unbounded; diminishing returns after 3 rounds |
+| Fixed 1 round (review only) | Executor cannot defend correct work; Reviewer has unchecked authority |
+
+### Rationale
+
+- Structured tension between Builder and Challenger catches more defects
+- Tech Lead arbitration prevents deadlocks without suppressing valid disagreement
+- 3-round cap bounds token cost while allowing substantive debate
+- Executor's right to defend prevents over-engineering from aggressive review
+- Consensus stamp ensures all three roles sign off on the final deliverable
+- File-based Mailbox creates auditable record of all exchanges
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Higher quality through adversarial review | 3× the agent invocations per phase |
+| Catches defects that single agents miss | Higher token consumption |
+| Auditable via Mailbox file | More complex phase output format |
+| Executor can defend correct work | Debate rounds delay deliverable completion |
+| Tech Lead breaks deadlocks | Arbitration quality depends on evidence presented |
+
+### Evidence
+
+- `rules/TEAMS.md` defines the 3 roles, debate mechanism, defense rules, and C8 enforcement checkpoints
+- `agents/teams/` contains 17 team directories × 3 role files (techlead.md, executor.md, reviewer.md)
+- `rules/PHASES.md` defines the Golden Triangle phase output format with consensus stamp
+- Debate cap: "Max debate rounds: 3. After round 3 without agreement, Tech Lead reads all Mailbox exchanges and makes a binding decision." (TEAMS.md)
+
+---
+
+## ADR-006: HSOL Two-Layer Skill Resolution
+
+### Context
+
+Agents need domain-specific knowledge to produce quality output. A static skill set becomes stale; a purely dynamic system lacks reliability. The framework needs to balance stability with discovery.
+
+### Decision
+
+**Implement a Hybrid Skill Orchestration Layer (HSOL) with two layers: pre-curated matrix skills (static) and community-discovered dynamic skills, unified by 5-factor fitness scoring.**
+
+Matrix skills (1,430 across 19 domains) provide a trusted baseline. Dynamic discovery via `find-skills` fills gaps when matrix fitness falls below 0.8. Community skills progress through a trust lifecycle (0.3 → 1.0) and can be promoted to the matrix.
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| Static skills only | Cannot adapt to new domains or technologies without manual curation |
+| Dynamic discovery only | No quality baseline; every skill starts untrusted |
+| Keyword-based matching | Misses semantic relationships; poor precision for related domains |
+| Manual skill assignment per task | Doesn't scale; requires user expertise about available skills |
+| Single fitness factor | Oversimplifies quality assessment; trust and freshness matter alongside relevance |
+
+### Rationale
+
+- Matrix skills provide guaranteed baseline quality (trust = 1.0) with zero discovery overhead
+- Dynamic layer enables adaptation without requiring framework releases
+- 5-factor fitness scoring balances multiple quality dimensions:
+  - 0.35 × Semantic Match — primary relevance
+  - 0.25 × Specificity — domain precision
+  - 0.20 × Trust Level — proven reliability
+  - 0.10 × Freshness — recency
+  - 0.10 × Success Rate — execution history
+- Trust progression prevents untested skills from affecting critical workflows
+- Variant-gated discovery (`:fast` skips, `:hard`/`:team` may trigger) keeps fast paths fast
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Pre-curated baseline ensures minimum quality | 1,430 skill entries require maintenance |
+| Community discovery fills gaps automatically | Dynamic skills start untrusted (0.3) |
+| 5-factor scoring balances multiple dimensions | Scoring is interpretive (AI evaluates), not deterministic |
+| Trust progression protects quality | New skills need 10 successful executions to reach VALIDATED |
+| Variant gating preserves fast path performance | Discovery only runs for hard/team variants |
+
+### Evidence
+
+- `matrix-skills/_index.yaml`: `total_matrix_skills: 1430`, 19 domain files, HSOL config with `async_threshold: 0.8`
+- `rules/SKILLS.md`: Resolution algorithm (6 steps), fitness formula (5 factors with weights), trust lifecycle (4 stages with criteria)
+- `matrix-skills/_dynamic.yaml`: Dynamic skill governance fields (owner, checksum, support_state, promotion_state)
+- `_index.yaml` discovery config: `apply_for_variants: ["hard", "team"]` — confirms `:fast` skips discovery
+
+---
+
+## ADR-007: 10 Laws Governance Model
+
+### Context
+
+AI models exhibit failure modes that traditional software does not — hallucination, role drift, requirement omission, silent halts, and context pollution. The framework needs a governance mechanism that prevents these failure modes across all interactions.
+
+### Decision
+
+**Define 10 immutable Orchestration Laws in CORE.md that the AI must follow before every response, enforced by self-check and anti-pattern detection.**
+
+The laws cover: single point of truth, requirement integrity, explicit loading, deep embodiment, sequential execution, language compliance, recursive delegation, stateful handoff, constraint propagation, and deliverable integrity.
+
+### Alternatives Considered
+
+| Alternative | Why Rejected |
+|------------|-------------|
+| No governance (trust AI behavior) | AI models drift, skip steps, and hallucinate without guardrails |
+| Soft guidelines ("try to...") | Non-binding language leads to inconsistent compliance |
+| External validator (post-processing) | Catches errors after the fact; doesn't prevent them |
+| Fewer laws (3–5) | Doesn't cover enough failure modes; gaps lead to exploitable weaknesses |
+| More laws (20+) | Diminishing returns; context overhead; harder for AI to internalize |
+
+### Rationale
+
+- 10 laws cover the observed failure modes of AI models in multi-agent orchestration:
+  - L1 (Single Point of Truth) prevents conflicting instructions
+  - L2 (Requirement Integrity) prevents requirement omission/hallucination
+  - L3 (Explicit Loading) prevents assumption-based reasoning
+  - L4 (Deep Embodiment) prevents role drift during delegation
+  - L5 (Sequential Execution) prevents incomplete phase dependencies
+  - L6 (Language Compliance) prevents inconsistent localization
+  - L7 (Recursive Delegation) prevents meta agents from implementing
+  - L8 (Stateful Handoff) prevents destructive modification of prior deliverables
+  - L9 (Constraint Propagation) prevents constraint loss in delegation chains
+  - L10 (Deliverable Integrity) ensures quality standards are upheld
+- Complemented by 10 anti-patterns (A1–A10) that define explicit violations with corrective actions
+- Self-check before every response creates a behavioral feedback loop
+
+### Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Prevents common AI failure modes | Adds structured overhead to every interaction |
+| Laws are explicit and auditable | AI must internalize 10 rules before doing any work |
+| Anti-patterns provide negative examples | Self-check consumes context window tokens |
+| Self-check creates behavioral consistency | Cannot programmatically enforce compliance |
+| Covers the full failure mode spectrum | May be over-prescriptive for simple tasks |
+
+### Evidence
+
+- `rules/CORE.md` v4.1: 10 laws defined in table format with enforcement column
+- `rules/CORE.md`: Self-check block with 3 checkpoints executed before every response
+- `rules/ERRORS.md`: Anti-patterns A1–A10 with explicit "Anti-Pattern" → "Correct Behavior" mappings
+- `rules/CORE.md`: Prohibitions table mapping forbidden actions to correct alternatives
+- Platform entry points (CLAUDE.md, COPILOT.md, etc.) all mandate loading CORE.md before any action
+
+---
+
+## Evidence Sources
+
+| Source | Path | What It Provides |
+|--------|------|------------------|
+| CORE.md v4.1 | `rules/CORE.md` | 10 laws, identity binding, execution loop, prohibitions, self-check |
+| PHASES.md | `rules/PHASES.md` | Phase output format, Golden Triangle format, requirements registry |
+| AGENTS.md | `rules/AGENTS.md` | TIER 1/TIER 2 protocol, embodiment, completion guarantee |
+| SKILLS.md | `rules/SKILLS.md` | HSOL resolution algorithm, fitness formula, trust lifecycle, variant gating |
+| TEAMS.md | `rules/TEAMS.md` | Golden Triangle: 3 roles, debate (3 rounds), mailbox, C8 checkpoints |
+| ERRORS.md | `rules/ERRORS.md` | Error classes (E1–E4), recovery, anti-patterns (A1–A10) |
+| _index.yaml | `matrix-skills/_index.yaml` | 1,430 skills, 19 domains, HSOL config, discovery settings |
+| _dynamic.yaml | `matrix-skills/_dynamic.yaml` | Dynamic skill governance fields |
+| package.json | `package.json` | Zero deps, Node >=18, 5 platform scripts, files array |
+| cli/install.js | `cli/install.js` | Platform configs, `{TOOL}` replacement maps, built-in modules only |
+| CLAUDE.md | `CLAUDE.md` | Platform entry point: identity binding, CORE.md boot mandate |
+| backend-engineer.md | `agents/backend-engineer.md` | Agent structure: frontmatter, cognitive anchor, profile, handoffs |
+| agents/teams/ | `agents/teams/` | 17 team directories × 3 role files each |

package/documents/knowledge-domain/00-index.md

@@ -0,0 +1,251 @@
+# Knowledge Domain
+
+> **Purpose**: Domain model summary, entity overview, bounded contexts, and cross-references for the Agent Assistant framework
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Quick Summary
+
+Agent Assistant's domain model is entirely file-based — every entity is a Markdown or YAML file stored in a well-defined directory structure. There is no database, no HTTP API, and no traditional ORM. The AI model reads these files at runtime as its operating instructions. The domain comprises 10 core entity types organized across 5 bounded contexts: Orchestration (rules and governance), Workflow (commands and variants), Agency (individual and team agents), Knowledge (matrix skill domains and skill modules), and Distribution (platform configs and entry points). Together, these entities define a framework of 21 specialist agents, 14 command routers with 54 workflow variants, 1,430 skills across 19 domains, and deployment to 5 AI coding platforms.
+
+---
+
+## Table of Contents
+
+1. [Quick Summary](#quick-summary)
+2. [Sub-Files](#sub-files)
+3. [Entity Overview Diagram](#entity-overview-diagram)
+4. [Quick Facts](#quick-facts)
+5. [Bounded Contexts](#bounded-contexts)
+6. [Cross-References](#cross-references)
+7. [Known Gaps and Open Questions](#known-gaps-and-open-questions)
+
+---
+
+## Sub-Files
+
+| # | File | Description |
+|---|------|-------------|
+| 1 | [01-entities.md](./01-entities.md) | Per-entity deep dive: attributes, types, constraints, relationships, and entity-relationship diagrams |
+| 2 | [02-database-schema.md](./02-database-schema.md) | Explanation of the file-based data model (YAML frontmatter as schema, directory structure as organization) |
+| 3 | [03-api-contracts.md](./03-api-contracts.md) | CLI interface specs, Prompt Command Interface (14 commands), and HSOL skill resolution protocol |
+| 4 | [04-business-rules.md](./04-business-rules.md) | All business logic: Orchestration Laws, Tiered Execution, Phase Sequencing, HSOL Fitness Scoring, Trust Progression, Error Classification, Golden Triangle Debate, Deliverable Integrity |
+
+---
+
+## Entity Overview Diagram
+
+```mermaid
+erDiagram
+    PLATFORM_ENTRY ||--|| RULE : "loads"
+    PLATFORM_ENTRY }|--|| PLATFORM_CONFIG : "configured by"
+    RULE ||--|{ COMMAND : "routes to"
+    COMMAND ||--|{ COMMAND_VARIANT : "has variants"
+    COMMAND_VARIANT }|--|{ AGENT : "delegates to"
+    COMMAND_VARIANT }|--o{ TEAM_AGENT : "delegates to (team variant)"
+    AGENT }|--|{ MATRIX_SKILL_DOMAIN : "inherits from"
+    MATRIX_SKILL_DOMAIN ||--|{ SKILL_MODULE : "contains"
+    HSOL_CONFIG ||--|{ MATRIX_SKILL_DOMAIN : "governs"
+
+    PLATFORM_ENTRY {
+        string filename PK "e.g. COPILOT.md"
+        string platform "cursor, copilot, claude, codex, gemini"
+        string boot_sequence "loads CORE.md"
+        string identity "Orchestrator role"
+        string routing "Command detection"
+    }
+
+    RULE {
+        string filename PK "e.g. CORE.md"
+        string purpose "Governance area"
+        string load_strategy "mandatory or on-demand"
+        string version "e.g. 4.1"
+    }
+
+    COMMAND {
+        string filename PK "e.g. cook.md"
+        string description "Router purpose"
+        string version "1.0"
+        string category "engineering, meta, etc."
+        string execution_mode "router"
+        string routing_logic "Complexity-based"
+    }
+
+    COMMAND_VARIANT {
+        string filename PK "e.g. cook/fast.md"
+        string parent_command FK "cook"
+        string variant_type "fast, hard, team"
+        int phase_count "Number of phases"
+        string agents_used "Agent assignments"
+    }
+
+    AGENT {
+        string name PK "e.g. backend-engineer"
+        string description "Role title"
+        string profile "e.g. backend:execution"
+        string category "meta, execution, validation, research, support"
+        string version "1.0"
+        string core_directive "Primary mission"
+        string[] handoffs "Agents to hand off to"
+    }
+
+    TEAM_AGENT {
+        string filename PK "e.g. backend-team/techlead.md"
+        string team_domain "e.g. backend"
+        string role "techlead, executor, reviewer"
+        string base_agent FK "maps to individual agent"
+    }
+
+    MATRIX_SKILL_DOMAIN {
+        string filename PK "e.g. backend.yaml"
+        string domain_name "e.g. Backend Development"
+        string description "Domain purpose"
+        int skill_count "Number of skills"
+    }
+
+    SKILL_MODULE {
+        string skill_id PK "e.g. nextjs-app-router"
+        string category "core, expert, specialized, utility"
+        int priority_score "1-10"
+        string[] agents "Mapped agents"
+        string[] profiles "Mapped profiles"
+        string description "Purpose for AI recognition"
+    }
+
+    PLATFORM_CONFIG {
+        string tool_key PK "cursor, copilot, etc."
+        string name "Display name"
+        string description "Platform description"
+        string paths "Directory structure"
+        string replacements "Placeholder map"
+        string assets "Platform-specific files"
+    }
+
+    HSOL_CONFIG {
+        string version PK "1.1"
+        float semantic_match_weight "0.35"
+        float specificity_weight "0.25"
+        float trust_weight "0.20"
+        float freshness_weight "0.10"
+        float success_rate_weight "0.10"
+        float matrix_sufficient "0.8 threshold"
+        float matrix_adequate "0.75 threshold"
+    }
+```
+
+---
+
+## Quick Facts
+
+| Key | Value |
+|-----|-------|
+| Total Entity Types | 10 |
+| Bounded Contexts | 5 |
+| Storage Format | Markdown (`.md`) + YAML (`.yaml`) |
+| Schema Mechanism | YAML frontmatter in Markdown files |
+| Database | None (file-based) |
+| API | CLI commands + Prompt commands (no HTTP) |
+| Individual Agents | 21 |
+| Team Configurations | 17 teams × 3 roles = 51 team agents |
+| Commands | 14 routers |
+| Command Variants | 54 total |
+| Rules | 7 files |
+| Matrix Skill Domains | 19 + 2 special (_index.yaml, _dynamic.yaml) |
+| Skill Modules | 1,430 |
+| Supported Platforms | 5 (Cursor, Copilot, Claude, Codex, Antigravity/Gemini) |
+| Platform Entry Points | 6 files (AGENT.md + 5 platform-specific) |
+
+---
+
+## Bounded Contexts
+
+### 1. Orchestration Context
+
+Defines the governance rules and laws that control all framework behavior. The Orchestrator is the single entry point — it never implements, only delegates.
+
+| Entity | Location | Count |
+|--------|----------|-------|
+| Rule | `rules/*.md` | 7 |
+| HSOL Config | `matrix-skills/_index.yaml` | 1 |
+
+### 2. Workflow Context
+
+Defines how user requests are routed to phased workflows with sequential execution.
+
+| Entity | Location | Count |
+|--------|----------|-------|
+| Command | `commands/*.md` | 14 |
+| Command Variant | `commands/{cmd}/*.md` | 54 |
+
+### 3. Agency Context
+
+Defines the specialist agents that perform work, both individually and in teams.
+
+| Entity | Location | Count |
+|--------|----------|-------|
+| Agent | `agents/*.md` | 21 |
+| Team Agent | `agents/teams/{domain}-team/*.md` | 51 |
+
+### 4. Knowledge Context
+
+Defines the skill matrix that provides domain expertise to agents.
+
+| Entity | Location | Count |
+|--------|----------|-------|
+| Matrix Skill Domain | `matrix-skills/*.yaml` | 19 |
+| Skill Module | `skills/*/SKILL.md` | 1,430 |
+
+### 5. Distribution Context
+
+Defines how the framework is packaged and deployed to different AI platforms.
+
+| Entity | Location | Count |
+|--------|----------|-------|
+| Platform Config | `cli/install.js` TOOLS object | 5 |
+| Platform Entry Point | Root `*.md` files | 6 |
+
+---
+
+## Cross-References
+
+| Topic | See |
+|-------|-----|
+| System architecture and data flow | [knowledge-architecture/00-index.md](../knowledge-architecture/00-index.md) |
+| Project identity, tech stack, features | [knowledge-overview/00-index.md](../knowledge-overview/00-index.md) |
+| HSOL orchestration blueprint | [SMART-SKILL-ORCHESTRATION-BLUEPRINT.md](../SMART-SKILL-ORCHESTRATION-BLUEPRINT.md) |
+| Entity attributes and relationships | [01-entities.md](./01-entities.md) |
+| File-based storage model | [02-database-schema.md](./02-database-schema.md) |
+| CLI and Prompt Command interfaces | [03-api-contracts.md](./03-api-contracts.md) |
+| Business rules and governance logic | [04-business-rules.md](./04-business-rules.md) |
+
+---
+
+## Known Gaps and Open Questions
+
+1. **No formal schema validation** — YAML frontmatter in agent/command files is not programmatically validated against a schema definition. Correctness relies on convention.
+2. **Skill module content structure** — While `SKILL.md` is the standard filename, the internal structure of skill modules is not enforced by a shared template across all 1,430 skills.
+3. **Dynamic skill lifecycle tracking** — The `_dynamic.yaml` manifest tracks community skills, but runtime execution counts and success rates depend on the AI platform's ability to persist state between sessions.
+4. **Team agent file standardization** — Team agent files (`techlead.md`, `executor.md`, `reviewer.md`) follow the Golden Triangle protocol, but their frontmatter schema is not documented in the same detail as individual agents.
+5. **Cross-platform behavioral parity** — The 5 platforms have different capabilities (sub-agent support, file access, tool availability), but per-platform behavioral differences are not formally documented as entity constraints.
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Package manifest | `package.json` |
+| CLI installer (TOOLS config) | `cli/install.js` |
+| Core rules | `rules/CORE.md` |
+| Agent handling rules | `rules/AGENTS.md` |
+| Phase execution rules | `rules/PHASES.md` |
+| Skill resolution rules | `rules/SKILLS.md` |
+| Team protocol rules | `rules/TEAMS.md` |
+| Error handling rules | `rules/ERRORS.md` |
+| Reference tables | `rules/REFERENCE.md` |
+| HSOL index config | `matrix-skills/_index.yaml` |
+| Example agent file | `agents/backend-engineer.md` |
+| Example command router | `commands/cook.md` |
+| Platform entry points | `AGENT.md`, `CLAUDE.md`, `COPILOT.md`, `CURSOR.md`, `CODEX.md`, `GEMINI.md` |