@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/knowledge-domain/02-database-schema.md

@@ -0,0 +1,138 @@
+# Agent Assistant — Database Schema
+
+> **Purpose**: Explanation of the file-based data model — this project has no traditional database
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Not Applicable — File-Based Storage
+
+Agent Assistant does not use a database. There is no SQL, no NoSQL, no ORM, and no data persistence layer. The entire framework is a **content distribution system** — it distributes Markdown and YAML files into AI tool directories, and those files are read at runtime by the AI model itself.
+
+---
+
+## File-Based Data Model
+
+### Storage Philosophy
+
+The project treats the **file system as the database**:
+
+- **Directories** serve as tables/collections — each directory groups a single entity type
+- **Files** serve as rows/documents — each file is one instance of an entity
+- **YAML frontmatter** serves as the schema — structured key-value metadata at the top of Markdown files
+- **Markdown body** serves as the content/payload — unstructured or semi-structured domain knowledge
+- **File naming conventions** serve as primary keys — `backend-engineer.md`, `cook.md`, `backend.yaml`
+
+### Directory-as-Table Mapping
+
+| "Table" | Directory | File Format | Record Count | Key Field |
+|---------|-----------|-------------|--------------|-----------|
+| agents | `agents/*.md` | Markdown + YAML frontmatter | 21 | filename (e.g., `backend-engineer`) |
+| team_agents | `agents/teams/{domain}-team/*.md` | Markdown | 51 | `{domain}-team/{role}` |
+| commands | `commands/*.md` | Markdown + YAML frontmatter | 14 | filename (e.g., `cook`) |
+| command_variants | `commands/{cmd}/*.md` | Markdown + YAML frontmatter | 54 | `{cmd}/{variant}` |
+| rules | `rules/*.md` | Markdown | 7 | filename (e.g., `CORE`) |
+| matrix_skill_domains | `matrix-skills/*.yaml` | YAML | 19 + 2 | filename (e.g., `backend`) |
+| skill_modules | `skills/*/SKILL.md` | Markdown | 1,430 | directory name (e.g., `nextjs-app-router`) |
+| platform_configs | `cli/install.js` (TOOLS object) | JavaScript | 5 | object key (e.g., `cursor`) |
+| platform_entries | Root `*.md` | Markdown | 6 | filename (e.g., `COPILOT`) |
+
+### YAML Frontmatter as Schema
+
+Agent and command files use YAML frontmatter delimited by `---` as their structured schema:
+
+```yaml
+---
+name: backend-engineer
+description: Principal Backend Architect — server-side logic, API design, scalable systems
+profile: "backend:execution"
+handoffs: [tester, database-architect, performance-engineer, devops-engineer, frontend-engineer, security-engineer]
+version: "1.0"
+category: execution
+---
+```
+
+This pattern provides:
+
+| Database Concept | Frontmatter Equivalent |
+|-----------------|----------------------|
+| Column definition | YAML key name |
+| Data type | Inferred from YAML (string, array, number) |
+| Required fields | Convention — all agents must include name, description, profile, handoffs, version, category |
+| Foreign keys | String references (e.g., `handoffs` references other agent names) |
+| Enums | Convention (e.g., `category` must be one of: meta, execution, validation, research, support) |
+| Indexes | Directory structure + HSOL registry in `_index.yaml` |
+
+### YAML Domain Files as Registries
+
+The `matrix-skills/*.yaml` files function as indexed registries. Each skill entry follows a consistent schema:
+
+```yaml
+- skill_id: unique-identifier
+  category: core|expert|specialized|utility
+  priority_score: 1-10
+  relevance_mapping:
+    agents: [agent-id, ...]
+    profiles: [domain:category, ...]
+  description: "Concise purpose for AI recognition"
+```
+
+The `_index.yaml` file functions as a **master index** — it lists all domains with their file paths and skill counts, defines agent-to-domain profile mappings, and stores the HSOL configuration parameters.
+
+### Referential Integrity
+
+Since there is no database engine to enforce constraints, referential integrity is maintained by convention:
+
+| Relationship | Enforcement Mechanism |
+|-------------|----------------------|
+| Agent `handoffs` → Agent names | Convention — names must match existing agent filenames |
+| Agent profile → Domain key | `_index.yaml` `agent_profiles` section maps profiles to domains |
+| Command variant → Agent | Variant Markdown references agent by name in phase definitions |
+| Skill `relevance_mapping.agents` → Agent | Convention — agent IDs must match existing agent names |
+| Platform Config `{TOOL}` → Entry Point | CLI installer maps tool keys to entry point files |
+
+### Query Patterns
+
+Since the AI model is the runtime, "queries" are file reads:
+
+| SQL Equivalent | File-Based Equivalent |
+|---------------|----------------------|
+| `SELECT * FROM agents WHERE name = 'backend-engineer'` | Read `agents/backend-engineer.md` |
+| `SELECT * FROM agents WHERE category = 'execution'` | AI reads all agents, filters by frontmatter `category` |
+| `SELECT skills FROM backend WHERE priority >= 9` | AI reads `matrix-skills/backend.yaml`, filters by `priority_score` |
+| `JOIN agents ON skills.agents` | AI reads agent profile from `_index.yaml`, then reads matching domain YAMLs |
+| `INSERT INTO dynamic_skills` | `npx skills add {owner/repo@skill} -g -y` adds entry to `_dynamic.yaml` |
+
+### Data Lifecycle
+
+| Operation | Mechanism |
+|-----------|-----------|
+| Create | CLI installer copies files from npm package to `~/.{tool}/skills/agent-assistant/` |
+| Read | AI model reads files from the installed directory at runtime |
+| Update | User runs `npm update @namch/agent-assistant` then `agent-assistant install <tool>` |
+| Delete | `agent-assistant uninstall <tool>` removes installed files |
+
+### Why No Database
+
+1. **The AI model IS the runtime** — It reads Markdown/YAML directly; no query engine is needed
+2. **No persistent state between sessions** — Each AI session starts fresh by reading files
+3. **Content distribution, not data management** — The framework distributes instructions, not user data
+4. **Cross-platform compatibility** — Files work identically across all 5 AI platforms
+5. **Zero dependencies** — No database driver, ORM, or connection management required
+6. **Human-readable by design** — Developers can read and edit any file directly
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Agent frontmatter example | `agents/backend-engineer.md` |
+| Command frontmatter example | `commands/cook.md` |
+| HSOL index with domain registry and profiles | `matrix-skills/_index.yaml` |
+| Skill entry schema reference | `matrix-skills/_index.yaml` (resolution section comment) |
+| CLI installer with TOOLS config | `cli/install.js` |
+| Dynamic manifest structure | `matrix-skills/_dynamic.yaml` |
+| Package manifest | `package.json` |

package/documents/knowledge-domain/03-api-contracts.md

@@ -0,0 +1,479 @@
+# Agent Assistant — API Contracts
+
+> **Purpose**: CLI interface specifications, Prompt Command Interface, and HSOL skill resolution protocol
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [API Overview](#api-overview)
+2. [CLI Interface](#cli-interface)
+3. [Prompt Command Interface](#prompt-command-interface)
+4. [HSOL Skill Resolution Protocol](#hsol-skill-resolution-protocol)
+
+---
+
+## API Overview
+
+Agent Assistant exposes two distinct interfaces, neither of which is an HTTP API:
+
+| Interface | Type | Consumer | Entry Point |
+|-----------|------|----------|-------------|
+| CLI Interface | Node.js command-line tool | Developer's terminal | `cli/install.js` |
+| Prompt Command Interface | Natural language commands | AI model at runtime | Platform entry points (`COPILOT.md`, etc.) |
+
+There is also an internal resolution protocol — the HSOL (Hybrid Skill Orchestration Layer) — that functions as a "skill API" the AI model executes to inject domain expertise into agents.
+
+---
+
+## CLI Interface
+
+### Global Information
+
+| Property | Value |
+|----------|-------|
+| Binary name | `agent-assistant` |
+| Entry point | `cli/install.js` |
+| Runtime | Node.js >= 18.0.0 |
+| Dependencies | Zero (uses only `node:fs`, `node:path`, `node:os`, `node:readline`) |
+| Package | `@namch/agent-assistant` on npm |
+
+### Commands
+
+#### `agent-assistant install <tool>`
+
+Installs the framework to a specific AI platform's global directory.
+
+| Parameter | Type | Required | Valid Values | Description |
+|-----------|------|----------|--------------|-------------|
+| `tool` | string | yes (unless `--all`) | `cursor`, `copilot`, `antigravity`, `claude`, `codex` | Target AI platform |
+| `--all` | flag | no | — | Install for all 5 platforms |
+
+**Behavior**:
+
+1. Resolves the platform's installation paths from the TOOLS configuration object
+2. Creates the directory structure (`skills/agent-assistant/`, `agents/`, `commands/`, `rules/`, `matrix-skills/`, `documents/`)
+3. Copies core directories: `agents/`, `rules/`, `documents/`, `commands/`, `matrix-skills/`
+4. Copies `skills/` directory (1,430 skill modules)
+5. Performs `{TOOL}` placeholder replacement in all Markdown and YAML files
+6. Copies platform-specific assets (entry point files, config files)
+7. Copies root files (`README.md`)
+8. Displays progress bar with file count
+9. Runs verification to confirm all files were written
+10. Prints summary report with statistics
+
+**Exit codes**:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Invalid tool name or installation error |
+
+**npm script shortcuts**:
+
+| Script | Equivalent |
+|--------|-----------|
+| `npm run install:cursor` | `node cli/install.js install cursor` |
+| `npm run install:copilot` | `node cli/install.js install copilot` |
+| `npm run install:antigravity` | `node cli/install.js install antigravity` |
+| `npm run install:codex` | `node cli/install.js install codex` |
+| `npm run install:all` | `node cli/install.js install --all` |
+
+---
+
+#### `agent-assistant uninstall <tool>`
+
+Removes the framework from a specific AI platform's global directory.
+
+| Parameter | Type | Required | Valid Values | Description |
+|-----------|------|----------|--------------|-------------|
+| `tool` | string | yes (unless `--all`) | `cursor`, `copilot`, `antigravity`, `claude`, `codex` | Target AI platform |
+| `--all` | flag | no | — | Uninstall from all 5 platforms |
+
+**Behavior**:
+
+1. Resolves the platform's `agentAssistant` path
+2. Removes only bundled agent files (preserves user-custom agents)
+3. Removes the `skills/agent-assistant/` directory tree
+4. Removes platform-specific assets installed by the framework
+
+**npm script shortcuts**:
+
+| Script | Equivalent |
+|--------|-----------|
+| `npm run uninstall:cursor` | `node cli/install.js uninstall cursor` |
+| `npm run uninstall:copilot` | `node cli/install.js uninstall copilot` |
+| `npm run uninstall:antigravity` | `node cli/install.js uninstall antigravity` |
+| `npm run uninstall:codex` | `node cli/install.js uninstall codex` |
+| `npm run uninstall:all` | `node cli/install.js uninstall --all` |
+
+---
+
+#### `agent-assistant list`
+
+Lists which platforms currently have the framework installed.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| (none) | — | — | No arguments |
+
+**Behavior**:
+
+1. Checks each platform's `agentAssistant` path for existence
+2. Prints a list of installed platforms with status indicators
+
+**npm script shortcut**: `npm run list`
+
+---
+
+### Installation File Mapping
+
+The installer copies these directories from the npm package into platform-specific paths:
+
+| Source Directory | Destination (relative to `agentAssistant` path) | Contents |
+|-----------------|------------------------------------------------|----------|
+| `agents/` | `agents/` | 21 individual agents + 17 team folders (51 role files) |
+| `rules/` | `rules/` | 7 governance files |
+| `documents/` | `documents/` | Knowledge base folders |
+| `commands/` | `commands/` | 14 routers + variant subfolders (54 variant files) |
+| `matrix-skills/` | `matrix-skills/` | 19 domain YAMLs + `_index.yaml` + `_dynamic.yaml` |
+| `skills/` | Installed to `{SKILLS_PATH}/` | 1,430 skill modules |
+| `README.md` | `README.md` | Project readme |
+
+### Platform-Specific Asset Mapping
+
+| Platform | Asset | Source | Destination |
+|----------|-------|--------|-------------|
+| Cursor | Rules directory | `code-assistants/cursor-assistant/rules/` | `~/.cursor/rules/` |
+| Cursor | Cursorrules | `code-assistants/cursor-assistant/.cursorrules` | `~/.cursor/.cursorrules` |
+| Copilot | Agent file | `code-assistants/copilot-assistant/agent-assistant.agent.md` | VS Code prompts folder |
+| Antigravity | Gemini config | `code-assistants/antigravity-assistant/GEMINI.md` | `~/.gemini/GEMINI.md` |
+| Antigravity | Agent file | `code-assistants/antigravity-assistant/AntigravityGlobal.agent.md` | `~/.gemini/agents/` |
+| Claude | Claude config | `code-assistants/claude-assistant/CLAUDE.md` | `~/.claude/CLAUDE.md` |
+| Codex | Codex config | `code-assistants/codex-assistant/CODEX.md` | `~/.codex/CODEX.md` |
+| Codex | TOML config | `code-assistants/codex-assistant/config.toml` | `~/.codex/config.toml` |
+| Codex | Agent TOMLs | `code-assistants/codex-assistant/agents/` | `~/.codex/agents/` |
+| Codex | Command skills | `code-assistants/codex-assistant/skills/` | `~/.codex/skills/` |
+
+---
+
+## Prompt Command Interface
+
+These commands are used inside AI coding assistants after the framework is installed. The AI model parses these from user input and routes them through the Orchestrator.
+
+### Command Syntax
+
+```
+/{command}                    → Routes to default variant (presents options)
+/{command}:{variant}          → Routes directly to specific variant
+/{command}/{variant}          → Alternative syntax (same effect)
+```
+
+Arguments follow the command:
+
+```
+/cook implement user authentication with JWT
+/fix the login button is not working
+/plan migration from REST to GraphQL
+```
+
+### Natural Language Detection
+
+The Orchestrator also detects commands from natural language:
+
+| User Intent | Detected Command |
+|-------------|-----------------|
+| implement, build, create, add | `/cook` |
+| fix, bug, error, broken | `/fix` |
+| plan, how should, strategy, approach | `/plan` |
+| debug, investigate, why | `/debug` |
+| test, coverage | `/test` |
+| review, PR, check code | `/review` |
+| document, readme, docs, spec | `/docs` |
+| design, UI, UX, mockup | `/design` |
+| deploy, release | `/deploy` |
+| report, status, summary | `/report` |
+| brainstorm, ideas, explore | `/brainstorm` |
+| question, how, what, why | `/ask` |
+| code, snippet, generate | `/code` |
+
+### Command Specifications
+
+#### `/cook` — Feature Implementation
+
+| Property | Value |
+|----------|-------|
+| Purpose | Implement new features end-to-end |
+| Input | Feature description |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Simple spec → fast; Complex → hard; Context-critical → focus; Max quality → team |
+
+| Variant | Phases | Discovery | Team |
+|---------|--------|-----------|------|
+| `fast` | Minimal (typically 2-3) | Matrix only, skip dynamic | Single agent per phase |
+| `hard` | Full (typically 5-7) | Matrix + dynamic discovery | Single agent per phase |
+| `focus` | Full with context clearing | Matrix + dynamic discovery | Single agent per phase |
+| `team` | Full with Golden Triangle | Matrix + dynamic discovery | 3 agents per phase |
+
+#### `/code` — Code Generation
+
+| Property | Value |
+|----------|-------|
+| Purpose | Generate code snippets or modules |
+| Input | Code specification |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Same as `/cook` |
+
+#### `/fix` — Bug Fixing
+
+| Property | Value |
+|----------|-------|
+| Purpose | Identify and fix bugs |
+| Input | Bug description or error message |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Clear bug → fast; Complex/multi-component → hard |
+
+#### `/debug` — Debugging
+
+| Property | Value |
+|----------|-------|
+| Purpose | Deep investigation of issues |
+| Input | Issue description or symptoms |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Quick investigation → fast; Root cause analysis → hard |
+
+#### `/test` — Test Generation
+
+| Property | Value |
+|----------|-------|
+| Purpose | Generate test suites |
+| Input | Component or feature to test |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Unit tests → fast; Full coverage strategy → hard |
+
+#### `/plan` — Planning
+
+| Property | Value |
+|----------|-------|
+| Purpose | Create implementation plans and task breakdowns |
+| Input | Feature or project to plan |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Quick plan → fast; Detailed architecture → hard |
+
+#### `/design` — UI/UX Design
+
+| Property | Value |
+|----------|-------|
+| Purpose | Design user interfaces and experiences |
+| Input | UI/UX requirements |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Simple component → fast; Full design system → hard |
+
+#### `/review` — Code Review
+
+| Property | Value |
+|----------|-------|
+| Purpose | Review code for quality, security, performance |
+| Input | Code or PR to review |
+| Variants | `fast`, `hard`, `team` |
+| Default routing | Quick check → fast; Thorough review → hard |
+
+#### `/report` — Reporting
+
+| Property | Value |
+|----------|-------|
+| Purpose | Generate reports and summaries |
+| Input | Topic or scope for report |
+| Variants | `fast`, `hard`, `focus`, `team` |
+| Default routing | Quick summary → fast; Detailed analysis → hard |
+
+#### `/brainstorm` — Ideation
+
+| Property | Value |
+|----------|-------|
+| Purpose | Explore ideas and possibilities |
+| Input | Topic or problem to brainstorm |
+| Variants | `fast`, `hard`, `team` |
+| Default routing | Quick ideas → fast; Deep exploration → hard |
+
+#### `/docs` — Documentation
+
+| Property | Value |
+|----------|-------|
+| Purpose | Generate or maintain documentation |
+| Input | Documentation target |
+| Variants | `core`, `business`, `audit` |
+| Default routing | Technical docs → core; Business docs → business; Review existing → audit |
+
+#### `/deploy` — Deployment
+
+| Property | Value |
+|----------|-------|
+| Purpose | Manage deployment pipeline |
+| Input | Deployment target or action |
+| Variants | `check`, `preview`, `production`, `rollback` |
+| Default routing | Pre-deploy verification → check; Staging → preview; Live → production; Undo → rollback |
+
+#### `/ask` — Questions & Answers
+
+| Property | Value |
+|----------|-------|
+| Purpose | Answer technical questions |
+| Input | Question |
+| Variants | `fast`, `hard` |
+| Default routing | Simple question → fast; Research-heavy → hard |
+
+#### `/auto` — Autonomous Execution
+
+| Property | Value |
+|----------|-------|
+| Purpose | Analyze task and autonomously execute complete workflow |
+| Input | Task description |
+| Variants | (meta-router — selects another command autonomously) |
+| Behavior | Classifies the task type, selects the optimal command and variant, executes all phases without user intervention between phases |
+
+### Pre-Flight Loading (All Commands)
+
+Every command router requires loading these rule files before execution:
+
+| Order | File | Purpose |
+|-------|------|---------|
+| 1 | `CORE.md` | Identity, Laws, Routing |
+| 2 | `PHASES.md` | Phase execution protocol |
+| 3 | `AGENTS.md` | Tiered execution protocol |
+
+Execution is blocked until all three are loaded.
+
+### Variant Behavior Matrix
+
+| Behavior | fast | hard | focus | team |
+|----------|------|------|-------|------|
+| Phase count | Minimal (2-3) | Full (5-7) | Full (5-7) | Full (5-7) |
+| Skill discovery | Matrix only | Matrix + dynamic | Matrix + dynamic | Matrix + dynamic |
+| Context clearing | No | No | Yes (between phases) | No |
+| Agents per phase | 1 | 1 | 1 | 3 (Golden Triangle) |
+| Debate rounds | N/A | N/A | N/A | Up to 3 |
+| Deliverable review | Exit criteria only | Exit criteria | Exit criteria + context check | Consensus stamp required |
+
+---
+
+## HSOL Skill Resolution Protocol
+
+The Hybrid Skill Orchestration Layer is an internal protocol the AI model executes to inject relevant skills into agents during workflow phases.
+
+### Resolution Flow
+
+```mermaid
+flowchart TD
+    A[Agent assigned to phase] --> B[Parse agent profile from frontmatter]
+    B --> C[Load inherited domains from _index.yaml]
+    C --> D[Filter skills by relevance_mapping]
+    D --> E[Apply priority thresholds]
+    E --> F[Calculate fitness scores]
+    F --> G{Fitness >= 0.8?}
+    G -->|Yes| H[Execute with matrix skills]
+    G -->|No| I{Fitness >= 0.75?}
+    I -->|Yes| J[Execute with matrix + async discovery recommendation]
+    I -->|No| K[Blocking discovery via find-skills]
+    K --> L{Skills found?}
+    L -->|Yes| M[Install and execute with new skills]
+    L -->|No| N[Report gap, use general capabilities]
+    H --> O[Read matched SKILL.md files]
+    J --> O
+    M --> O
+    O --> P[Agent executes with injected skills]
+```
+
+### Fitness Calculation Formula
+
+```
+fitness = 0.35 × SEMANTIC_MATCH
+        + 0.25 × SPECIFICITY
+        + 0.20 × TRUST_LEVEL
+        + 0.10 × FRESHNESS_SCORE
+        + 0.10 × SUCCESS_RATE
+```
+
+| Factor | Weight | Description | Range |
+|--------|--------|-------------|-------|
+| Semantic Match | 0.35 | How closely the skill's description matches the task keywords | 0.0 — 1.0 |
+| Specificity | 0.25 | How specialized the skill is for this exact task (vs. general) | 0.0 — 1.0 |
+| Trust Level | 0.20 | Matrix skills = 1.0; dynamic skills = 0.3 to 1.0 based on history | 0.3 — 1.0 |
+| Freshness Score | 0.10 | How recently the skill was verified or updated | 0.0 — 1.0 |
+| Success Rate | 0.10 | Historical success rate of the skill in prior executions | 0.0 — 1.0 |
+
+### Decision Thresholds
+
+| Threshold | Value | Action |
+|-----------|-------|--------|
+| Matrix Sufficient | >= 0.8 | Use matrix skills directly, skip dynamic discovery |
+| Matrix Adequate | 0.75 — 0.8 | Use matrix skills, run async discovery for future recommendation |
+| Matrix Insufficient | < 0.75 | Blocking discovery — wait for `find-skills` before proceeding |
+| Superiority Delta | 0.15 | Dynamic skill must exceed matrix skill's fitness by this amount to be preferred |
+
+### Profile-to-Domain Resolution
+
+The HSOL maps agent profiles to skill domains via the `agent_profiles` section in `_index.yaml`:
+
+```
+1. PARSE agent's `profile` field (e.g., "backend:execution")
+2. LOOK UP profile in _index.yaml agent_profiles
+3. READ `inherit_from` array (e.g., ["backend", "architecture", "quality", "data", "languages"])
+4. LOAD each domain's YAML file
+5. FILTER skills where relevance_mapping matches the agent or profile
+6. SORT by priority_score descending
+7. APPLY fitness calculation
+8. RETURN sorted skill set for injection
+```
+
+### Dynamic Discovery Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npx skills find "{keywords}"` | Search for skills matching keywords |
+| `npx skills add {owner/repo@skill} -g -y` | Install skill globally for current platform |
+| `npx skills check` | Verify installed skill integrity |
+| `npx skills update` | Update installed dynamic skills |
+
+### Variant-Specific Discovery Behavior
+
+| Variant | Discovery Behavior |
+|---------|-------------------|
+| `fast` | Skip dynamic discovery entirely — matrix skills only |
+| `hard` | Full resolution — matrix first, dynamic discovery if fitness < 0.8 |
+| `focus` | Same as `hard` — full resolution with dynamic discovery |
+| `team` | Same as `hard` — full resolution with dynamic discovery |
+| Other (core, business, audit, check, etc.) | Standard matrix resolution |
+
+### Complexity Assessment
+
+Before HSOL resolution, the Orchestrator assesses task complexity:
+
+| Assessment | Resolution |
+|------------|-----------|
+| Simple | Base knowledge sufficient — skip HSOL resolution entirely |
+| Complex | HSOL resolution mandatory — base knowledge alone is never sufficient |
+
+The assessment determines whether formal skill injection is needed. For complex tasks, skipping resolution is a protocol violation.
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| CLI installer full source | `cli/install.js` |
+| Package scripts (npm shortcuts) | `package.json` |
+| Core rules (command routing) | `rules/CORE.md` |
+| HSOL resolution rules | `rules/SKILLS.md` |
+| HSOL config (thresholds, weights) | `matrix-skills/_index.yaml` |
+| Reference tables (command/variant list) | `rules/REFERENCE.md` |
+| Command router example | `commands/cook.md` |
+| Auto router | `commands/auto.md` |
+| Phase execution rules | `rules/PHASES.md` |
+| Agent handling (tiered execution) | `rules/AGENTS.md` |
+| Copilot platform config | `cli/install.js` (TOOLS.copilot) |
+| Cursor platform config | `cli/install.js` (TOOLS.cursor) |