@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-glossary/03-domain-entities-and-events.md

@@ -0,0 +1,395 @@
+# Agent Assistant — Domain Entities and Events
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Entity vocabulary, event vocabulary, and entity-event interaction matrix for the agent-assistant domain model |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Entity Vocabulary
+
+### Agent
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Agent identifier (filename without `.md`) |
+| `profile` | string | `{domain}:{category}` HSOL profile |
+| `handoffs` | string[] | Permitted downstream delegation targets |
+| `constraints` | object | Behavioral restrictions and scope limits |
+| `directive` | text | Primary mission statement |
+| `protocol` | text | Step-by-step execution procedure |
+| `output_format` | text | Required deliverable structure |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Defined** | Agent `.md` file exists in `agents/` |
+| **Loaded** | Orchestrator has read the agent file (TIER 2) or injected it into sub-agent prompt (TIER 1) |
+| **Active** | Agent is currently executing a phase |
+| **Complete** | Agent has produced deliverable and returned control |
+
+---
+
+### Team
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `domain` | string | Team's specialization area (folder name under `agents/teams/`) |
+| `tech_lead` | Agent | Tech Lead role file |
+| `executor` | Agent | Executor role file |
+| `reviewer` | Agent | Reviewer role file |
+| `mailbox` | file | Append-only communication channel |
+| `task_list` | file | Shared task tracking artifact |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Defined** | Team folder exists with 3 role files |
+| **Activated** | `:team` variant triggered, mailbox created |
+| **Debating** | Adversarial review cycle in progress |
+| **Consensus** | All 3 roles have signed off |
+| **Dissolved** | Team phase complete, artifacts finalized |
+
+---
+
+### Command
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Command identifier (e.g., `cook`, `fix`, `plan`) |
+| `router` | file | Top-level routing file (`commands/{cmd}.md`) |
+| `variants` | Variant[] | Available execution strategies |
+| `trigger` | string | User input pattern (slash command or natural language) |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Registered** | Command `.md` file exists in `commands/` |
+| **Triggered** | User input matched to this command |
+| **Routing** | Router analyzing scope and selecting variant |
+| **Dispatched** | Variant selected and execution begun |
+
+---
+
+### Variant
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Variant identifier (filename without `.md`) |
+| `command` | Command | Parent command |
+| `phases` | Phase[] | Ordered execution sequence |
+| `scope` | string | Scale indicator (single, multi, full, team) |
+| `quality_gates` | string[] | Required checkpoints |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Defined** | Variant `.md` file exists in `commands/{cmd}/` |
+| **Selected** | Router chose this variant for current request |
+| **Executing** | Phases running in sequence |
+| **Complete** | All phases finished, all quality gates passed |
+
+---
+
+### Phase
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `number` | int | Sequential position within variant |
+| `agent` | Agent | Responsible specialist |
+| `input` | object | Required inputs (prior deliverables + user context) |
+| `exit_criteria` | string[] | Conditions for phase completion |
+| `deliverable` | object | Output artifact specification |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Pending** | Phase not yet started, waiting for prior phase |
+| **Active** | Agent executing phase work |
+| **Review** | Deliverable under quality check (team variants) |
+| **Complete** | Exit criteria met, deliverable frozen (L8) |
+| **Failed** | Error classified, recovery in progress |
+
+---
+
+### Rule
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `file` | string | Rule file name (e.g., `CORE.md`, `PHASES.md`) |
+| `scope` | string | What the rule governs (identity, execution, skills, teams, errors) |
+| `laws` | Law[] | Immutable governance rules (CORE.md only) |
+| `load_priority` | string | When loaded: `always` (CORE) or `on-demand` (others) |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Available** | Rule file exists in `rules/` |
+| **Loaded** | Orchestrator has internalized the rule |
+| **Active** | Rule is constraining current execution |
+
+---
+
+### Skill (Matrix)
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Skill identifier |
+| `domain` | string | Parent domain (YAML file name) |
+| `trust` | float | Always `1.0` for matrix skills |
+| `tags` | string[] | Discovery keywords |
+| `path` | string | Folder path under `skills/` |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Registered** | Entry exists in domain YAML file |
+| **Resolved** | HSOL selected this skill for injection |
+| **Injected** | Skill content loaded into agent context |
+
+---
+
+### Matrix Skill Domain
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Domain identifier (e.g., `backend`, `frontend`) |
+| `file` | string | YAML file path (`matrix-skills/{domain}.yaml`) |
+| `skills` | Skill[] | All skills in this domain |
+| `count` | int | Number of skills in domain |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Defined** | YAML file exists in `matrix-skills/` |
+| **Indexed** | Listed in `_index.yaml` |
+| **Queried** | HSOL searched this domain during resolution |
+
+---
+
+### Dynamic Skill
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Skill identifier |
+| `source` | string | Origin (community repository, URL) |
+| `trust` | float | Current trust level (0.3–1.0) |
+| `executions` | int | Count of successful executions |
+| `installed_at` | datetime | Installation timestamp |
+| `path` | string | Folder path under `skills/` |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Discovered** | Found via `find-skills` mechanism |
+| **Installed** | Downloaded and registered in `_dynamic.yaml` |
+| **Progressing** | Trust increasing through successful executions |
+| **Promoted** | Elevated to matrix skill status |
+| **Removed** | Uninstalled from framework |
+
+---
+
+### Platform Config
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `platform` | string | AI tool name (Claude, Cursor, Copilot, Codex, Gemini) |
+| `entry_file` | string | Root-level boot file name |
+| `format` | string | Platform-specific Markdown conventions |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Defined** | Entry point file exists at project root |
+| **Loaded** | AI tool has read the entry point |
+| **Booted** | Pre-Flight complete, Orchestrator active |
+
+---
+
+### Entry Point
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `file` | string | File name (e.g., `CLAUDE.md`) |
+| `platform` | Platform Config | Target platform |
+| `boot_sequence` | string[] | Ordered rule files to load |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Available** | File exists at project root |
+| **Read** | AI tool has opened and parsed the file |
+| **Activated** | Orchestrator identity established |
+
+---
+
+### HSOL Config
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `fitness_weights` | object | Weight distribution (semantic, specificity, trust, freshness, success) |
+| `superiority_delta` | float | Minimum override threshold (0.15) |
+| `trust_thresholds` | object | Trust progression levels |
+| `max_skills` | int | Maximum skills injected per resolution |
+
+| Lifecycle State | Description |
+|----------------|-------------|
+| **Defined** | Configuration exists in `_index.yaml` |
+| **Loaded** | HSOL has parsed configuration |
+| **Active** | Configuration applied to skill resolution |
+
+---
+
+## Event Vocabulary
+
+### install
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | User runs `node cli/install.js install` |
+| **Source Entity** | CLI |
+| **Target Entities** | Platform Config, Entry Point |
+| **Outcome** | Platform entry points and agent files installed to target project |
+| **Side Effects** | Creates/updates root-level `.md` files, copies `rules/`, `agents/`, `commands/`, `skills/`, `matrix-skills/` |
+
+### uninstall
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | User runs CLI uninstall command |
+| **Source Entity** | CLI |
+| **Target Entities** | Platform Config, Entry Point |
+| **Outcome** | Framework files removed from target project |
+| **Side Effects** | Removes installed files and folders |
+
+### command trigger
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | User inputs a slash command or natural language matching a command |
+| **Source Entity** | User (via AI tool) |
+| **Target Entities** | Command, Router |
+| **Outcome** | Command router activated, begins scope analysis |
+| **Side Effects** | May trigger Pre-Flight if not already complete |
+
+### phase start
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Previous phase completed (or variant execution began for Phase 1) |
+| **Source Entity** | Variant |
+| **Target Entities** | Phase, Agent |
+| **Outcome** | Agent receives task with prior deliverables as constraints |
+| **Side Effects** | HSOL skill resolution for target agent |
+
+### phase complete
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Agent meets all exit criteria for current phase |
+| **Source Entity** | Phase |
+| **Target Entities** | Variant, next Phase |
+| **Outcome** | Deliverable frozen (L8), next phase unblocked |
+| **Side Effects** | Deliverable becomes immutable constraint |
+
+### agent delegation
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Orchestrator routes work to an agent (TIER 1 or TIER 2) |
+| **Source Entity** | Orchestrator |
+| **Target Entities** | Agent |
+| **Outcome** | Agent activated with scoped task and constraints |
+| **Side Effects** | TIER 1: new sub-agent context created; TIER 2: Orchestrator embodies agent |
+
+### skill resolution
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Agent delegation requires skill injection |
+| **Source Entity** | HSOL |
+| **Target Entities** | Matrix Skill, Dynamic Skill, Skill Module |
+| **Outcome** | Top-ranked skills injected into agent context |
+| **Side Effects** | Fitness scores computed, dynamic skill execution count may increment |
+
+### skill discovery
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | User invokes `find-skills` mechanism |
+| **Source Entity** | CLI / find-skills |
+| **Target Entities** | Dynamic Skill |
+| **Outcome** | New community skills discovered and presented for installation |
+| **Side Effects** | Network requests to skill repositories |
+
+### trust update
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Dynamic skill completes a successful execution |
+| **Source Entity** | HSOL |
+| **Target Entities** | Dynamic Skill |
+| **Outcome** | Trust level incremented (0.3→0.5→0.7→1.0) |
+| **Side Effects** | `_dynamic.yaml` updated; may trigger promotion at trust 1.0 |
+
+### consensus reached
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | All 3 Golden Triangle roles sign off on deliverable |
+| **Source Entity** | Team (Reviewer confirms) |
+| **Target Entities** | Consensus Stamp, Phase |
+| **Outcome** | Team phase output released as deliverable |
+| **Side Effects** | Consensus stamp written to mailbox; debate mechanism terminates |
+
+### error classified
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Exception or failure during phase execution |
+| **Source Entity** | Phase (failed) |
+| **Target Entities** | Error Classification |
+| **Outcome** | Error assigned class (E1/E1b/E2/E3/E4) and recovery procedure |
+| **Side Effects** | E1: auto-retry; E1b: context reduction; E2: alternative strategy; E3: user escalation; E4: workflow rollback |
+
+### error recovered
+
+| Attribute | Value |
+|-----------|-------|
+| **Trigger** | Recovery procedure succeeds for classified error |
+| **Source Entity** | Error Classification |
+| **Target Entities** | Phase |
+| **Outcome** | Phase execution resumes or restarts |
+| **Side Effects** | Error logged; phase may re-enter Active state |
+
+---
+
+## Entity-Event Interaction Matrix
+
+This matrix shows which entities participate in each event as **source (S)**, **target (T)**, or **affected (A)**.
+
+| Event | Agent | Team | Command | Variant | Phase | Rule | Skill (Matrix) | Skill (Dynamic) | Domain | Platform Config | Entry Point | HSOL Config |
+|-------|-------|------|---------|---------|-------|------|----------------|-----------------|--------|----------------|-------------|-------------|
+| **install** | A | A | A | A | — | A | A | A | A | T | T | A |
+| **uninstall** | A | A | A | A | — | A | A | A | A | T | T | A |
+| **command trigger** | — | — | T | — | — | A | — | — | — | — | — | — |
+| **phase start** | T | A | — | S | T | A | — | — | — | — | — | — |
+| **phase complete** | S | A | — | A | S | — | — | — | — | — | — | — |
+| **agent delegation** | T | — | — | — | A | A | — | — | — | — | — | — |
+| **skill resolution** | A | — | — | — | A | — | T | T | A | — | — | A |
+| **skill discovery** | — | — | — | — | — | — | — | T | — | — | — | — |
+| **trust update** | — | — | — | — | — | — | — | T | — | — | — | A |
+| **consensus reached** | A | S | — | — | T | — | — | — | — | — | — | — |
+| **error classified** | A | A | — | — | S | A | — | — | — | — | — | — |
+| **error recovered** | A | — | — | — | T | A | — | — | — | — | — | — |
+
+**Legend**: S = Source (initiates event), T = Target (directly affected), A = Affected (indirectly involved or state may change)
+
+---
+
+## Evidence Sources
+
+- `rules/CORE.md` — Orchestrator, Laws, agent identity
+- `rules/AGENTS.md` — Agent delegation lifecycle, TIER 1/TIER 2 states
+- `rules/PHASES.md` — Phase lifecycle, deliverable freezing
+- `rules/TEAMS.md` — Team lifecycle, mailbox, consensus events
+- `rules/ERRORS.md` — Error classification events, recovery states
+- `rules/SKILLS.md` — HSOL resolution events, skill lifecycle
+- `matrix-skills/_index.yaml` — HSOL config entity, domain registry
+- `matrix-skills/_dynamic.yaml` — Dynamic skill entity, trust progression events
+- `agents/*.md` — Agent entity attributes
+- `agents/teams/` — Team entity structure
+- `commands/*.md` — Command/variant entity attributes
+- `cli/install.js` — Install/uninstall events

package/documents/business/business-glossary/04-api-term-mapping.md

@@ -0,0 +1,173 @@
+# Agent Assistant — API Term Mapping
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Mapping between domain terms and their technical implementation: file locations, YAML fields, Markdown sections, CLI arguments, and configuration keys |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Primary Term-to-Implementation Mapping
+
+| Domain Term | Implementation Artifact | File/Path | Section/Field |
+|-------------|----------------------|-----------|---------------|
+| **Orchestrator** | Markdown section | `rules/CORE.md` | `## IDENTITY` section — defines Orchestrator role, prohibitions, self-check |
+| **Agent** | Markdown file | `agents/{name}.md` | Entire file — YAML frontmatter + directive + protocol + output format |
+| **Team Agent** | Markdown file | `agents/teams/{domain}/{role}.md` | Entire file — role-specific agent within Golden Triangle |
+| **Command** | Markdown file | `commands/{cmd}.md` | Entire file — router logic, scope analysis, variant dispatch |
+| **Variant** | Markdown file | `commands/{cmd}/{variant}.md` | Entire file — phase sequence, agent assignments, quality gates |
+| **Phase** | Markdown section | `commands/{cmd}/{variant}.md` | `## Phase N` sections within variant file |
+| **Profile** | YAML frontmatter field | `agents/{name}.md` | `profile: {domain}:{category}` in YAML frontmatter |
+| **HSOL** | YAML configuration | `matrix-skills/_index.yaml` | `hsol` top-level key — resolution config, weights, thresholds |
+| **Trust** | YAML configuration | `matrix-skills/_index.yaml` | `hsol.trust` key — trust thresholds and progression rules |
+| **Dynamic Skill** | YAML registry | `matrix-skills/_dynamic.yaml` | Each entry — name, source, trust, executions, path |
+| **Matrix Skill** | YAML registry | `matrix-skills/{domain}.yaml` | Each entry — name, tags, path, implicit trust 1.0 |
+| **Skill Module** | Folder + Markdown | `skills/{skill-name}/SKILL.md` | SKILL.md — domain knowledge, best practices, examples |
+| **Fitness Score** | YAML configuration | `matrix-skills/_index.yaml` | `hsol.fitness_weights` — semantic, specificity, trust, freshness, success |
+| **Superiority Delta** | YAML configuration | `matrix-skills/_index.yaml` | `hsol.superiority_delta: 0.15` |
+| **Golden Triangle** | Folder structure | `agents/teams/{domain}/` | 3 files: tech-lead, executor, reviewer |
+| **Mailbox** | Runtime file | Created at runtime during `:team` execution | Append-only message log |
+| **Shared Task List** | Runtime file | Created at runtime during `:team` execution | Task breakdown with status tracking |
+| **Orchestration Laws** | Markdown section | `rules/CORE.md` | `## LAWS` or equivalent section — L1 through L10 |
+| **Anti-Pattern Registry** | Markdown section | `rules/CORE.md` | `## ANTI-PATTERNS` or equivalent — A1 through A10 |
+| **Error Classification** | Markdown file | `rules/ERRORS.md` | E1–E4 definitions, recovery procedures |
+| **Domain** | YAML file | `matrix-skills/{domain}.yaml` | Each YAML file = one domain (19 total) |
+| **Platform Entry Point** | Markdown file | `{PLATFORM}.md` at project root | `CLAUDE.md`, `CURSOR.md`, `COPILOT.md`, `CODEX.md`, `GEMINI.md` |
+| **Requirements Registry** | Markdown section | `rules/PHASES.md` | Requirements table format specification |
+| **Cognitive Anchor** | Markdown section | `agents/{name}.md` | Cognitive anchor block within agent definition |
+| **Handoff** | YAML frontmatter field | `agents/{name}.md` | `handoffs: [agent1, agent2]` in YAML frontmatter |
+| **Consensus Stamp** | Markdown format | `rules/TEAMS.md` | Stamp format specification |
+| **Debate Mechanism** | Markdown section | `rules/TEAMS.md` | Review cycle rules, max 3 rounds |
+| **Trust Progression** | YAML configuration | `matrix-skills/_index.yaml` | `hsol.trust` — progression levels 0.3→0.5→0.7→1.0 |
+| **Promotion** | YAML lifecycle | `matrix-skills/_dynamic.yaml` → `matrix-skills/{domain}.yaml` | Entry moves from dynamic to domain YAML on promotion |
+
+---
+
+## CLI Argument Mapping
+
+| Domain Term | CLI Command | Arguments | Description |
+|-------------|-------------|-----------|-------------|
+| **install** | `node cli/install.js install` | `--all`, `--platform {name}` | Install framework into target project |
+| **uninstall** | `node cli/install.js uninstall` | `--all`, `--platform {name}` | Remove framework from target project |
+| **find-skills** | `find-skills` | `{query}` | Discover community skills matching query |
+| **Platform Entry Point** | `node cli/install.js install` | `--platform claude`, `--platform cursor`, `--platform copilot`, `--platform codex`, `--platform gemini` | Install specific platform entry point |
+| **Agent** | `node cli/install.js install` | `--agents` (implicit with `--all`) | Install agent definitions |
+| **Command** | `node cli/install.js install` | `--commands` (implicit with `--all`) | Install command routers and variants |
+| **Skill Module** | `node cli/install.js install` | `--skills` (implicit with `--all`) | Install skill modules |
+| **Rule** | `node cli/install.js install` | `--rules` (implicit with `--all`) | Install rule files |
+| **Matrix Skill** | `node cli/install.js install` | `--matrix-skills` (implicit with `--all`) | Install matrix skill registry |
+
+---
+
+## Prompt Command Term Mapping
+
+Mapping between user-facing slash commands and their internal implementation artifacts.
+
+| User Command | Router File | Variant Folder | Natural Language Triggers |
+|-------------|-------------|----------------|--------------------------|
+| `/cook` | `commands/cook.md` | `commands/cook/` | "implement", "build", "create", "make" |
+| `/fix` | `commands/fix.md` | `commands/fix/` | "fix", "bug", "repair", "patch" |
+| `/plan` | `commands/plan.md` | `commands/plan/` | "plan", "design architecture", "architect" |
+| `/debug` | `commands/debug.md` | `commands/debug/` | "debug", "investigate", "trace" |
+| `/test` | `commands/test.md` | `commands/test/` | "test", "write tests", "coverage" |
+| `/review` | `commands/review.md` | `commands/review/` | "review", "audit", "check quality" |
+| `/docs` | `commands/docs.md` | `commands/docs/` | "document", "write docs", "documentation" |
+| `/design` | `commands/design.md` | `commands/design/` | "design", "UI", "UX", "mockup" |
+| `/deploy` | `commands/deploy.md` | `commands/deploy/` | "deploy", "release", "ship" |
+| `/report` | `commands/report.md` | `commands/report/` | "report", "analyze", "assessment" |
+| `/brainstorm` | `commands/brainstorm.md` | `commands/brainstorm/` | "brainstorm", "ideate", "explore options" |
+| `/ask` | `commands/ask.md` | `commands/ask/` | "ask", "question", "explain" |
+| `/code` | `commands/code.md` | `commands/code/` | "code", "write code", "snippet" |
+| `/auto` | `commands/auto.md` | — | "auto", "automatic", "autonomous" |
+
+---
+
+## HSOL Configuration Term Mapping
+
+Detailed mapping of HSOL domain terms to their `_index.yaml` configuration structure.
+
+| Domain Term | YAML Path | Type | Default | Description |
+|-------------|-----------|------|---------|-------------|
+| **HSOL** | `hsol` | object | — | Top-level HSOL configuration block |
+| **Fitness Score — Semantic** | `hsol.fitness_weights.semantic` | float | `0.35` | Weight for semantic similarity to task |
+| **Fitness Score — Specificity** | `hsol.fitness_weights.specificity` | float | `0.25` | Weight for profile-category match |
+| **Fitness Score — Trust** | `hsol.fitness_weights.trust` | float | `0.20` | Weight for skill trust level |
+| **Fitness Score — Freshness** | `hsol.fitness_weights.freshness` | float | `0.10` | Weight for recency of last update |
+| **Fitness Score — Success** | `hsol.fitness_weights.success` | float | `0.10` | Weight for historical success rate |
+| **Superiority Delta** | `hsol.superiority_delta` | float | `0.15` | Override threshold for dynamic over matrix |
+| **Trust — Initial** | `hsol.trust.initial` | float | `0.3` | Starting trust for new dynamic skills |
+| **Trust — Level 2** | `hsol.trust.level_2` | float | `0.5` | Trust after first progression |
+| **Trust — Level 3** | `hsol.trust.level_3` | float | `0.7` | Trust after second progression |
+| **Trust — Promotion** | `hsol.trust.promotion` | float | `1.0` | Trust level triggering promotion eligibility |
+| **Domain Registry** | `hsol.domains` | string[] | 19 domains | List of registered skill domain names |
+
+---
+
+## Agent Frontmatter Field Mapping
+
+| Domain Term | YAML Field | Type | Example |
+|-------------|-----------|------|---------|
+| **Profile** | `profile` | string | `backend:api` |
+| **Handoff** | `handoffs` | string[] | `[debugger, tester]` |
+| **Agent name** | (filename) | string | `backend-engineer.md` |
+| **Constraints** | `constraints` | object | `{ max_files: 10, languages: [typescript] }` |
+
+---
+
+## Rule File Mapping
+
+| Domain Term | Rule File | Load Priority | Key Sections |
+|-------------|-----------|---------------|-------------|
+| **Orchestration Laws (L1–L10)** | `rules/CORE.md` | Always (Pre-Flight) | Identity, Laws, Prohibitions, Self-Check |
+| **Phase execution** | `rules/PHASES.md` | On-demand | Phase structure, deliverable format, requirements registry |
+| **Tiered Execution** | `rules/AGENTS.md` | On-demand | TIER 1/TIER 2, delegation protocol, handoff rules |
+| **HSOL resolution** | `rules/SKILLS.md` | On-demand | Fitness scoring, skill injection, trust progression |
+| **Golden Triangle** | `rules/TEAMS.md` | On-demand | Team protocol, mailbox, consensus, debate mechanism |
+| **Error Classification (E1–E4)** | `rules/ERRORS.md` | On-demand | Error classes, recovery procedures, escalation rules |
+| **Quick lookup** | `rules/REFERENCE.md` | On-demand | Summary tables, cheat sheets |
+
+---
+
+## Domain YAML File Mapping
+
+| Domain Name | YAML File | Skill Count Category |
+|-------------|-----------|---------------------|
+| AI/ML | `matrix-skills/ai-ml.yaml` | Machine learning, LLM, NLP skills |
+| Architecture | `matrix-skills/architecture.yaml` | System design, patterns, principles |
+| Backend | `matrix-skills/backend.yaml` | Server-side, API, database skills |
+| Cloud | `matrix-skills/cloud.yaml` | AWS, GCP, Azure, serverless |
+| Data | `matrix-skills/data.yaml` | Data engineering, analytics, pipelines |
+| Design | `matrix-skills/design.yaml` | UI/UX, visual design, accessibility |
+| DevOps | `matrix-skills/devops.yaml` | CI/CD, infrastructure, monitoring |
+| Frontend | `matrix-skills/frontend.yaml` | Browser, UI frameworks, CSS |
+| Gaming | `matrix-skills/gaming.yaml` | Game engines, graphics, physics |
+| Languages | `matrix-skills/languages.yaml` | Programming language-specific skills |
+| Management | `matrix-skills/management.yaml` | Project management, agile, processes |
+| MCP | `matrix-skills/mcp.yaml` | Model Context Protocol skills |
+| Mobile | `matrix-skills/mobile.yaml` | iOS, Android, cross-platform |
+| Performance | `matrix-skills/performance.yaml` | Optimization, profiling, benchmarking |
+| Planning | `matrix-skills/planning.yaml` | Requirements, estimation, roadmapping |
+| Quality | `matrix-skills/quality.yaml` | Testing, QA, code quality |
+| Research | `matrix-skills/research.yaml` | Analysis, investigation, evaluation |
+| Security | `matrix-skills/security.yaml` | AppSec, infrastructure security, compliance |
+| Tools | `matrix-skills/tools.yaml` | Developer tools, IDEs, utilities |
+
+---
+
+## Evidence Sources
+
+- `rules/CORE.md` — Orchestrator identity section, Laws section
+- `rules/AGENTS.md` — Tiered Execution protocol
+- `rules/PHASES.md` — Phase format, requirements registry
+- `rules/TEAMS.md` — Team protocol, consensus format
+- `rules/ERRORS.md` — Error classification
+- `rules/SKILLS.md` — HSOL resolution algorithm
+- `matrix-skills/_index.yaml` — HSOL configuration structure, fitness weights, trust thresholds
+- `matrix-skills/_dynamic.yaml` — Dynamic skill entry structure
+- `matrix-skills/*.yaml` — Domain YAML file structure
+- `agents/*.md` — Agent frontmatter field structure
+- `commands/*.md` — Command/variant file structure
+- `cli/install.js` — CLI argument parsing
+- `package.json` — Project metadata, version

package/documents/business/business-prd/00-index.md

@@ -0,0 +1,107 @@
+# Agent Assistant — Product Requirements Document (PRD)
+
+> **Purpose**: PRD summary, table of contents, key facts, cross-references, and known gaps for @namch/agent-assistant v1.3.0
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Quick Summary
+
+This PRD defines the product requirements for **@namch/agent-assistant v1.3.0**, a multi-agent orchestration framework that transforms a single AI coding assistant into a coordinated team of 21 specialist agents across 5 platforms (Cursor, Copilot, Claude Code, Codex, Antigravity/Gemini). The framework provides 14 structured commands with 4 variant strategies each, a Hybrid Skill Orchestration Layer (HSOL) with 1,430+ matrix skills across 19 domains, and adversarial team collaboration via the Golden Triangle protocol. Installation is global and one-time — zero per-project configuration required.
+
+The PRD covers 10 business goals (BG-001 through BG-010), 7 stakeholder types, 23 functional requirements (BR-001 through BR-023) with INVEST scoring, acceptance criteria, and a risk register addressing unvalidated performance claims, external dependencies, and testing gaps.
+
+---
+
+## Sub-Files
+
+| # | File | Description |
+|---|------|-------------|
+| 1 | [01-executive-summary.md](./01-executive-summary.md) | Mission statement, value proposition, target outcomes, target users, key metrics |
+| 2 | [02-problem-goals-and-scope.md](./02-problem-goals-and-scope.md) | Problem statement, 10 business goals (BG-001–BG-010), non-goals, in-scope/out-of-scope boundary |
+| 3 | [03-stakeholders-and-requirements.md](./03-stakeholders-and-requirements.md) | Stakeholder map with goals and touchpoints, functional requirements (BR-001–BR-023), non-functional requirements, traceability to goals |
+| 4 | [04-acceptance-risks-assumptions.md](./04-acceptance-risks-assumptions.md) | Acceptance criteria for the framework, risk register, assumptions, open questions |
+
+---
+
+## Key Facts
+
+| Key | Value |
+|-----|-------|
+| Package Name | `@namch/agent-assistant` |
+| Version | 1.3.0 |
+| Type | Multi-agent orchestration framework |
+| Platforms | 5 (Cursor, Copilot, Claude Code, Codex, Antigravity/Gemini) |
+| Specialist Agents | 21 |
+| Team Configurations | 17 teams (Golden Triangle protocol) |
+| Commands | 14 (with 4 variant strategies each) |
+| Matrix Skills | 1,430+ across 19 domains |
+| Business Goals | 10 (BG-001 to BG-010) |
+| Requirements | 23 (BR-001 to BR-023) |
+| Stakeholder Types | 7 |
+| Production Dependencies | 0 |
+| Runtime | Node.js >= 18.0.0 |
+| License | MIT |
+| Author | NamCH |
+
+---
+
+## Cross-References
+
+### Knowledge Folders (docs-core)
+
+| Folder | Relationship to PRD |
+|--------|---------------------|
+| [../knowledge-overview/](../knowledge-overview/) | Project identity, tech stack, features, getting started — provides factual basis for executive summary and scope |
+| [../knowledge-architecture/](../knowledge-architecture/) | System overview, components, data flow, design patterns, decisions — informs non-functional requirements |
+| [../knowledge-domain/](../knowledge-domain/) | Entities, business rules, API contracts — sources for domain-specific requirements |
+| [../knowledge-source-base/](../knowledge-source-base/) | Directory structure, entry points, key modules, configuration — evidence for technical requirements |
+| [../knowledge-standards/](../knowledge-standards/) | Code style, conventions, git workflow, testing standards — informs quality and process requirements |
+
+### Business Folders (docs-business)
+
+| Folder | Relationship to PRD |
+|--------|---------------------|
+| business-prd/ (this folder) | Product Requirements Document — goals, stakeholders, requirements, risks |
+| business-user-stories/ | User stories derived from BR-001–BR-023 requirements |
+| business-use-cases/ | Detailed use case specifications for canonical workflows |
+| business-glossary/ | Canonical terminology for all PRD terms |
+
+### Source Documents
+
+| Document | Relationship |
+|----------|-------------|
+| [../../reports/business-analysis/structured-business-pack.md](../../reports/business-analysis/structured-business-pack.md) | Primary source — goals, requirements, features, workflows, glossary, traceability matrix |
+| [../HSOL-ASSESSMENT.md](../HSOL-ASSESSMENT.md) | HSOL production readiness assessment — informs skill-related requirements and risks |
+| [../SMART-SKILL-ORCHESTRATION-BLUEPRINT.md](../SMART-SKILL-ORCHESTRATION-BLUEPRINT.md) | HSOL design blueprint — informs BR-008, BR-009, BR-010 |
+
+---
+
+## Known Gaps
+
+| ID | Gap | Impact | Affected Items |
+|----|-----|--------|----------------|
+| GAP-001 | Performance claims (70% faster, 70% fewer bugs, 85% token savings) are unvalidated — no benchmarks exist in the repository | Stakeholder expectations may be inflated; marketing risk | BG-003, BG-004, BG-005, BR-003, BR-008 |
+| GAP-002 | No automated test suite for framework behavior | Orchestration law violations (L1–L10) and error recovery (E1–E4) are undetectable at CI time | BG-009, BR-012, BR-013 |
+| GAP-003 | Dynamic skill ecosystem depends on external service (skills.sh) which is not bundled | BF-009, BF-010 features degrade to no-op when service is unreachable | BG-007, BR-009, BR-010 |
+| GAP-004 | Trust Progression Lifecycle has no observed implementation evidence | Trust values (0.3→0.5→0.7→1.0) may be conceptual only — `_dynamic.yaml` tracking is unverified | BG-007, BR-010 |
+| GAP-005 | No public roadmap exists | Contributors and adopters lack visibility into planned features and release priorities | BG-009, BG-010 |
+| GAP-006 | Community skill count target (≥50 in 12 months) has no measurement mechanism | BG-007 success cannot be tracked without skill registry analytics | BG-007 |
+| GAP-007 | Team adoption metric (≥80% in 30 days) has no measurement tooling | BG-002 KPI is aspirational without telemetry or survey mechanism | BG-002 |
+
+---
+
+## Evidence Sources
+
+| Source | Path | Used For |
+|--------|------|----------|
+| Structured Business Pack | `reports/business-analysis/structured-business-pack.md` | Goals, requirements, features, workflows, glossary, traceability |
+| Package manifest | `package.json` | Version, name, dependencies, scripts |
+| HSOL Assessment | `documents/HSOL-ASSESSMENT.md` | Skill layer readiness and gaps |
+| Knowledge Overview Index | `documents/knowledge-overview/00-index.md` | Project facts, quick summary |
+| Features | `documents/knowledge-overview/03-features.md` | Feature descriptions, performance metrics |
+| Core Rules | `rules/CORE.md` | Orchestration laws, tiered execution, command routing |
+| Agents directory | `agents/*.md` | 21 specialist agent definitions |
+| Commands directory | `commands/*.md` | 14 command workflow definitions |
+| Matrix Skills | `matrix-skills/_index.yaml` | 1,430+ skill entries across 19 domains |