@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/knowledge-architecture/01-system-overview.md

@@ -0,0 +1,240 @@
+# Agent Assistant — System Overview
+
+> **Purpose**: High-level architecture diagram, architecture style, layer boundaries, and key design decisions
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [Architecture Style](#architecture-style)
+2. [High-Level Architecture Diagram](#high-level-architecture-diagram)
+3. [Layer Boundaries](#layer-boundaries)
+4. [Key Design Decisions](#key-design-decisions)
+5. [Governance Model](#governance-model)
+6. [Evidence Sources](#evidence-sources)
+
+---
+
+## Architecture Style
+
+Agent Assistant is a **plugin-based orchestrator framework** where Markdown and YAML files serve as the instruction set, and the AI model itself serves as the runtime. There is no traditional server, no running process, and no compiled binary. The framework is distributed as an npm package containing structured instruction files that, once installed into an AI tool's global directory, reconfigure that tool's behavior into a multi-agent orchestration system.
+
+### What It Is
+
+| Characteristic | Description |
+|---------------|-------------|
+| **Type** | Instruction-distribution framework (content as code) |
+| **Runtime** | The AI model reads and follows Markdown/YAML files at inference time |
+| **Deployment** | `npm install` → `cli/install.js` copies files to `~/.{tool}/skills/agent-assistant/` |
+| **Execution** | No process runs — the AI loads CORE.md as its "operating system" on every prompt |
+| **State** | Stateless between sessions; file-based communication within sessions (Mailbox pattern) |
+
+### What It Is NOT
+
+- Not a web application or microservice
+- Not a server that runs in the background
+- Not a library with callable APIs
+- Not a traditional plugin with lifecycle hooks
+
+### Architectural Influences
+
+The framework draws from several patterns without being a pure instance of any:
+
+| Influence | How It Manifests |
+|-----------|-----------------|
+| **Orchestrator/Choreography** | Single orchestrator delegates to specialist agents via tiered execution |
+| **Plugin Architecture** | 1,430 skill modules are independently discoverable and composable |
+| **Pipeline** | Commands execute as phase-sequential pipelines with exit criteria |
+| **Strategy Pattern** | Command routers select variant workflows (fast/hard/focus/team) at runtime |
+| **Actor Model** | Agents communicate through append-only mailbox files, not direct calls |
+
+---
+
+## High-Level Architecture Diagram
+
+```mermaid
+graph TB
+    USER["👤 User Prompt"]
+
+    subgraph "PLATFORM LAYER — Entry Points"
+        direction LR
+        EP_CLAUDE["CLAUDE.md"]
+        EP_COPILOT["COPILOT.md"]
+        EP_CURSOR["CURSOR.md"]
+        EP_CODEX["CODEX.md"]
+        EP_GEMINI["GEMINI.md"]
+    end
+
+    subgraph "ORCHESTRATOR CORE — Brain"
+        CORE["CORE.md v4.1<br/>Identity · 10 Laws<br/>Command Routing<br/>Tiered Execution"]
+        subgraph "Rules (loaded on demand)"
+            PHASES["PHASES.md"]
+            AGENTS_R["AGENTS.md"]
+            SKILLS_R["SKILLS.md"]
+            TEAMS_R["TEAMS.md"]
+            ERRORS_R["ERRORS.md"]
+            REF["REFERENCE.md"]
+        end
+    end
+
+    subgraph "COMMAND LAYER — Routing"
+        ROUTERS["14 Command Routers<br/>cook · fix · plan · debug<br/>test · review · docs · design<br/>deploy · report · brainstorm<br/>ask · code · auto"]
+        VARIANTS["Workflow Variants<br/>:fast · :hard · :focus · :team"]
+    end
+
+    subgraph "AGENT LAYER — Execution"
+        META["Meta Agents<br/>tech-lead · planner"]
+        EXEC["Execution Agents<br/>backend · frontend · mobile<br/>game · database-architect"]
+        VALID["Validation Agents<br/>tester · reviewer · security<br/>performance · debugger"]
+        RESEARCH["Research Agents<br/>researcher · scouter<br/>brainstormer · designer"]
+        SUPPORT["Support Agents<br/>docs-manager · devops<br/>business-analyst · PM · reporter"]
+        GT["Golden Triangle Teams<br/>17 teams × 3 roles"]
+    end
+
+    subgraph "SKILL LAYER — Knowledge"
+        MATRIX["Matrix Skills<br/>19 Domains · 1,430 Skills"]
+        DYN["Dynamic Skills<br/>Community Discovery"]
+        HSOL["HSOL Engine<br/>Fitness = 0.35×Semantic<br/>+ 0.25×Specificity<br/>+ 0.20×Trust<br/>+ 0.10×Freshness<br/>+ 0.10×Success"]
+    end
+
+    subgraph "DISTRIBUTION LAYER"
+        CLI["cli/install.js"]
+        NPM["npm Package"]
+        CA["Code Assistants<br/>Platform Templates"]
+    end
+
+    USER --> EP_CLAUDE & EP_COPILOT & EP_CURSOR & EP_CODEX & EP_GEMINI
+    EP_CLAUDE & EP_COPILOT & EP_CURSOR & EP_CODEX & EP_GEMINI --> CORE
+    CORE --> PHASES & AGENTS_R & SKILLS_R & TEAMS_R & ERRORS_R & REF
+    CORE --> ROUTERS
+    ROUTERS --> VARIANTS
+    VARIANTS --> META & EXEC & VALID & RESEARCH & SUPPORT
+    VARIANTS -->|":team variant"| GT
+    META & EXEC & VALID & RESEARCH & SUPPORT --> HSOL
+    GT --> HSOL
+    HSOL --> MATRIX
+    HSOL -->|"fitness < 0.8"| DYN
+    NPM --> CLI
+    CLI -->|"copy + {TOOL} replace"| EP_CLAUDE & EP_COPILOT & EP_CURSOR & EP_CODEX & EP_GEMINI
+    CA --> CLI
+```
+
+---
+
+## Layer Boundaries
+
+The framework is organized into 5 distinct layers. Each layer has a clear responsibility and communicates with adjacent layers through well-defined interfaces.
+
+### Layer 1: Platform Layer (Entry Points)
+
+| Attribute | Value |
+|-----------|-------|
+| **Files** | `CLAUDE.md`, `COPILOT.md`, `CURSOR.md`, `CODEX.md`, `GEMINI.md`, `AGENT.md` |
+| **Responsibility** | Bind the AI's identity as Orchestrator; load CORE.md; set platform-specific paths |
+| **Boundary** | Each file is identical in structure — only `{TOOL}` paths differ (resolved at install time) |
+| **Communicates With** | Orchestrator Core (downward only) |
+
+### Layer 2: Orchestrator Core (Rules Engine)
+
+| Attribute | Value |
+|-----------|-------|
+| **Files** | `rules/CORE.md`, `rules/PHASES.md`, `rules/AGENTS.md`, `rules/SKILLS.md`, `rules/TEAMS.md`, `rules/ERRORS.md`, `rules/REFERENCE.md` |
+| **Responsibility** | Define all operational protocols — identity, laws, phase execution, agent delegation, skill resolution, team collaboration, error recovery |
+| **Boundary** | CORE.md is always loaded; other rule files are loaded on demand (L3: Explicit Loading) |
+| **Communicates With** | Platform Layer (upward, identity binding), Command Layer (downward, routing) |
+
+### Layer 3: Command Layer (Routing)
+
+| Attribute | Value |
+|-----------|-------|
+| **Files** | `commands/*.md` (14 routers), `commands/{cmd}/*.md` (variant workflows) |
+| **Responsibility** | Analyze user input, assess complexity, route to appropriate variant workflow |
+| **Boundary** | Routers never implement — they load pre-flight rules, analyze, and redirect to a variant file |
+| **Communicates With** | Orchestrator Core (upward, rule loading), Agent Layer (downward, phase delegation) |
+
+### Layer 4: Agent Layer (Execution)
+
+| Attribute | Value |
+|-----------|-------|
+| **Files** | `agents/*.md` (21 agents), `agents/teams/*/` (17 teams × 3 roles) |
+| **Responsibility** | Execute phase work — implement, validate, research, or support based on specialist role |
+| **Boundary** | Agents are invoked via TIER 1 (sub-agent) or TIER 2 (embodiment); output must meet exit criteria |
+| **Communicates With** | Command Layer (upward, phase assignments), Skill Layer (downward, knowledge injection), other Agents (lateral, via Mailbox) |
+
+### Layer 5: Skill Layer (Knowledge)
+
+| Attribute | Value |
+|-----------|-------|
+| **Files** | `matrix-skills/*.yaml` (19 domain files + _index.yaml + _dynamic.yaml), `skills/*/SKILL.md` (1,430+ modules) |
+| **Responsibility** | Provide domain-specific knowledge to agents based on profile matching and fitness scoring |
+| **Boundary** | Skills are read-only knowledge modules — they do not execute, call APIs, or modify state |
+| **Communicates With** | Agent Layer (upward, injected via HSOL based on agent profile) |
+
+### Cross-Cutting: Distribution Layer
+
+| Attribute | Value |
+|-----------|-------|
+| **Files** | `cli/install.js`, `package.json`, `code-assistants/*/` |
+| **Responsibility** | Package the framework as an npm module and install to platform-specific directories with `{TOOL}` placeholder substitution |
+| **Boundary** | Operates only at install/uninstall time — has zero runtime presence |
+| **Communicates With** | All layers (copies and transforms all files) |
+
+---
+
+## Key Design Decisions
+
+| # | Decision | Choice | Rationale | Impact |
+|---|----------|--------|-----------|--------|
+| 1 | **Instruction language** | Markdown + YAML | AI models natively understand Markdown; no compilation needed; version-controllable | Framework logic is human-readable but not unit-testable |
+| 2 | **Runtime model** | AI model as runtime | Zero infrastructure cost; runs wherever the AI runs; no server to maintain | Behavior depends on AI model capability and compliance |
+| 3 | **Dependency policy** | Zero production dependencies | Maximum portability; no supply-chain risk; CLI uses only Node.js built-in modules (`fs`, `path`, `os`, `readline`) | Limited to what built-in modules provide |
+| 4 | **Platform strategy** | Write-once, deploy-to-many via `{TOOL}` placeholders | Single codebase for 5 platforms; install-time substitution avoids runtime branching | Platform-specific capabilities (e.g., sub-agents) vary silently |
+| 5 | **Agent execution** | Tiered: sub-agent isolation (TIER 1) preferred, shared embodiment (TIER 2) as fallback | Isolated context prevents pollution; fallback guarantees completion on all platforms | Quality may differ between tiers |
+| 6 | **Quality mechanism** | Adversarial Golden Triangle (3 agents, max 3 debate rounds) | Structured tension produces higher quality than parallel cooperation or single-agent review | Higher token cost per phase when using `:team` variant |
+| 7 | **Skill resolution** | HSOL two-layer (matrix + dynamic) with 5-factor fitness scoring | Pre-curated skills guarantee baseline; community discovery fills gaps; trust progression prevents quality regression | Fitness scoring is interpretive (AI evaluates), not deterministic |
+| 8 | **Phase execution** | Strictly sequential (Phase N → N+1) with exit criteria | Prevents downstream errors from incomplete phases; immutable prior deliverables (L8) | No parallelism within a workflow (except team roles within a phase) |
+| 9 | **Error handling** | 5-class self-healing with auto-recovery | Silent halts are forbidden; every error leads to completion or explicit user decision | Recovery logic is behavioral, not programmatic |
+| 10 | **Governance** | 10 immutable Orchestration Laws in CORE.md | Prevent common AI failure modes (assumption, hallucination, skipping, silent halt) | Adds overhead to every interaction (self-check before every response) |
+
+---
+
+## Governance Model
+
+The framework enforces behavior through 10 Orchestration Laws defined in `rules/CORE.md` v4.1:
+
+| Law | Name | Enforcement Mechanism |
+|-----|------|----------------------|
+| L1 | Single Point of Truth | Platform entry file loads CORE.md first; all other rules loaded on demand |
+| L2 | Requirement Integrity | 100% fidelity — parse EVERY requirement into a numbered registry; zero loss |
+| L3 | Explicit Loading | State what you loaded before using it; no implicit assumptions |
+| L4 | Deep Embodiment | When embodying an agent (TIER 2), follow their Directive + Protocol + Constraints exactly |
+| L5 | Sequential Execution | Phase N completes and meets exit criteria before Phase N+1 starts |
+| L6 | Language Compliance | Respond in user's language; code, comments, and report files always in English |
+| L7 | Recursive Delegation | Meta agents (tech-lead, planner) coordinate only — they NEVER implement |
+| L8 | Stateful Handoff | Prior deliverables are immutable constraints for downstream phases |
+| L9 | Constraint Propagation | scouter → planner → implementer chain is locked — constraints flow forward |
+| L10 | Deliverable Integrity | Files created by an agent define the quality standard |
+
+Additionally, 10 anti-patterns (A1–A10) are defined in `rules/ERRORS.md` as explicit violations with corrective actions.
+
+---
+
+## Evidence Sources
+
+| Source | Path | What It Provides |
+|--------|------|------------------|
+| CORE.md v4.1 | `rules/CORE.md` | Identity binding, 10 laws, command routing table, tiered execution protocol, prohibitions |
+| PHASES.md | `rules/PHASES.md` | Phase output format (standard + Golden Triangle), requirements registry template |
+| AGENTS.md | `rules/AGENTS.md` | TIER 1/TIER 2 protocols, tool discovery, agent categories (5), completion guarantee |
+| SKILLS.md | `rules/SKILLS.md` | HSOL overview, resolution algorithm, fitness formula (5 weighted factors), trust lifecycle |
+| TEAMS.md | `rules/TEAMS.md` | Golden Triangle roles (3), debate mechanism (max 3 rounds), C8 enforcement checkpoints |
+| ERRORS.md | `rules/ERRORS.md` | Error classes (E1–E4), recovery protocol, 10 anti-patterns (A1–A10) |
+| REFERENCE.md | `rules/REFERENCE.md` | Command table (14 commands), agent table (21 agents), deliverable path conventions |
+| _index.yaml | `matrix-skills/_index.yaml` | HSOL config, total skill count (1,430), discovery settings, async threshold (0.8) |
+| package.json | `package.json` | Version 1.3.0, zero production deps, 5 platform install scripts, engine >=18.0.0 |
+| cli/install.js | `cli/install.js` | Platform configs (5), `{TOOL}` replacement maps, directory structure per platform |
+| cook.md | `commands/cook.md` | Example command router — routing logic, pre-flight rule loading, variant table |
+| backend-engineer.md | `agents/backend-engineer.md` | Example agent — YAML frontmatter with profile/handoffs, cognitive anchor, skill injection |

package/documents/knowledge-architecture/02-components.md

@@ -0,0 +1,419 @@
+# Agent Assistant — Components
+
+> **Purpose**: Per-component breakdown of every major subsystem — responsibility, interfaces, dependencies, and file locations
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [Component Map](#component-map)
+2. [Orchestrator](#orchestrator)
+3. [Rules Engine](#rules-engine)
+4. [Command Routers](#command-routers)
+5. [Agents](#agents)
+6. [Team Agents (Golden Triangle)](#team-agents-golden-triangle)
+7. [Matrix Skills](#matrix-skills)
+8. [Skills (Modules)](#skills-modules)
+9. [CLI Installer](#cli-installer)
+10. [Code Assistants (Platform Templates)](#code-assistants-platform-templates)
+11. [Platform Entry Points](#platform-entry-points)
+12. [Web Application](#web-application)
+13. [Evidence Sources](#evidence-sources)
+
+---
+
+## Component Map
+
+```mermaid
+graph LR
+    subgraph "Distribution"
+        CLI["CLI Installer"]
+        CA["Code Assistants"]
+        PKG["npm Package"]
+    end
+
+    subgraph "Core Framework"
+        EP["Platform Entry Points"]
+        ORC["Orchestrator<br/>(CORE.md)"]
+        RULES["Rules Engine<br/>(7 files)"]
+        CMD["Command Routers<br/>(14 routers)"]
+        AG["Agents<br/>(21 individual)"]
+        TM["Team Agents<br/>(17 × 3 roles)"]
+    end
+
+    subgraph "Knowledge"
+        MS["Matrix Skills<br/>(19 domains)"]
+        SK["Skill Modules<br/>(1,430+)"]
+    end
+
+    subgraph "Independent"
+        WEB["Web App<br/>(React + Vite)"]
+    end
+
+    PKG --> CLI
+    CA --> CLI
+    CLI --> EP
+    EP --> ORC
+    ORC --> RULES
+    ORC --> CMD
+    CMD --> AG
+    CMD --> TM
+    AG --> MS
+    AG --> SK
+    TM --> MS
+```
+
+---
+
+## Orchestrator
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Orchestrator |
+| **Responsibility** | Central coordination — detect commands, load rules, delegate to agents, verify exit criteria, deliver results. Never implements directly. |
+| **Identity** | Defined by the `🆔 IDENTITY — ABSOLUTE BINDING` block in CORE.md: "YOU ARE THE ORCHESTRATOR — NOT AN IMPLEMENTER" |
+| **Key Files** | `rules/CORE.md` (v4.1 — primary), platform entry points (load CORE.md) |
+| **Interfaces** | **Input**: User natural language or `/command` syntax. **Output**: Structured phase deliverables per PHASES.md format. |
+| **Dependencies** | Rules Engine (on-demand loading), Command Routers (routing), Agents (delegation) |
+| **Governance** | 10 Orchestration Laws (L1–L10), self-check before every response, prohibitions table |
+
+### Execution Loop (from CORE.md)
+
+```
+1. DETECT command (explicit /command or natural language mapping)
+2. LOAD workflow file (command router → variant)
+3. EXECUTE phases in order (one at a time, same reply)
+4. VERIFY exit criteria per phase
+5. DELIVER final result
+```
+
+---
+
+## Rules Engine
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Rules Engine |
+| **Responsibility** | Define all operational protocols the orchestrator and agents follow — identity, phases, delegation, skills, teams, errors, reference tables |
+| **Key Files** | `rules/CORE.md`, `rules/PHASES.md`, `rules/AGENTS.md`, `rules/SKILLS.md`, `rules/TEAMS.md`, `rules/ERRORS.md`, `rules/REFERENCE.md` |
+| **Interfaces** | Read-only Markdown files loaded by the orchestrator on demand per L3 (Explicit Loading) |
+| **Dependencies** | None — rules are self-contained |
+| **Loading Strategy** | CORE.md always loaded first; others loaded contextually |
+
+### Rule File Inventory
+
+| File | Purpose | Load Trigger |
+|------|---------|-------------|
+| `CORE.md` v4.1 | Identity, 10 laws, command routing, tiered execution, prohibitions | Always (mandatory boot) |
+| `PHASES.md` | Phase output format, requirements registry, Golden Triangle phase format | Running workflow phases |
+| `AGENTS.md` | TIER 1/TIER 2 protocol, tool discovery, agent categories, completion guarantee | Delegating to agents |
+| `SKILLS.md` | HSOL resolution algorithm, fitness formula, trust progression, complexity gating | Skill resolution needed |
+| `TEAMS.md` | Golden Triangle roles, debate mechanism (max 3 rounds), C8 checkpoints, mailbox protocol | `:team` variant invoked |
+| `ERRORS.md` | Error classification (E1–E4), recovery protocol, anti-patterns (A1–A10) | Error occurs |
+| `REFERENCE.md` | Command table, agent table, natural language detection map, deliverable paths | Quick lookup |
+
+---
+
+## Command Routers
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Command Routers |
+| **Responsibility** | Parse user input, assess complexity, route to the correct workflow variant |
+| **Key Files** | `commands/*.md` (14 routers), `commands/{cmd}/*.md` (variant workflows) |
+| **Interfaces** | **Input**: User arguments (`$ARGUMENTS`). **Output**: Redirect to variant file. |
+| **Dependencies** | Rules Engine (pre-flight loading of CORE.md, PHASES.md, AGENTS.md) |
+| **Pattern** | Strategy Pattern — runtime selection of variant based on complexity analysis |
+
+### Command Inventory (from REFERENCE.md)
+
+| Command | Router File | Variants | Category |
+|---------|------------|----------|----------|
+| `/cook` | `commands/cook.md` | fast, hard, focus, team | Engineering |
+| `/fix` | `commands/fix.md` | fast, hard, focus, team | Engineering |
+| `/plan` | `commands/plan.md` | fast, hard, focus, team | Planning |
+| `/debug` | `commands/debug.md` | fast, hard, focus, team | Validation |
+| `/test` | `commands/test.md` | fast, hard, focus, team | Validation |
+| `/review` | `commands/review.md` | fast, hard | Validation |
+| `/docs` | `commands/docs.md` | core, business, audit | Documentation |
+| `/design` | `commands/design.md` | fast, hard, focus, team | Design |
+| `/deploy` | `commands/deploy.md` | check, preview, production, rollback | Operations |
+| `/report` | `commands/report.md` | fast, hard, focus, team | Reporting |
+| `/brainstorm` | `commands/brainstorm.md` | fast, hard | Research |
+| `/ask` | `commands/ask.md` | fast, hard | Research |
+| `/code` | `commands/code.md` | fast, hard, focus, team | Engineering |
+| `/auto` | `commands/auto.md` | — | Meta |
+
+### Router Structure (common pattern from cook.md)
+
+Each router follows a standard structure:
+
+1. **YAML frontmatter** — description, version, category, execution-mode: router
+2. **PRE-FLIGHT** — Mandatory rule loading (CORE.md → PHASES.md → AGENTS.md)
+3. **ROUTING LOGIC** — Complexity-based conditional routing
+4. **AVAILABLE ROUTES** — Table of variant → use-case mappings
+5. **PRESENT OPTIONS** — User-facing selection when ambiguous
+
+---
+
+## Agents
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Individual Agents |
+| **Responsibility** | Execute specialist work within a phase — implement, validate, research, or support |
+| **Key Files** | `agents/*.md` (21 files) |
+| **Interfaces** | **Input**: Phase assignment with requirements + acceptance criteria. **Output**: Deliverable meeting exit criteria. |
+| **Dependencies** | Rules Engine (protocol), Skill Layer (knowledge injection via HSOL), other Agents (handoffs) |
+| **Invocation** | TIER 1 (sub-agent with isolated context) or TIER 2 (embodiment in shared context) |
+
+### Agent Inventory (from REFERENCE.md and AGENTS.md)
+
+| Agent | Category | Profile | Primary Responsibility | Handoffs To |
+|-------|----------|---------|----------------------|-------------|
+| `tech-lead` | meta | — | Architecture decisions, orchestration | All agents |
+| `planner` | meta | — | Task breakdown, roadmap creation | tech-lead, engineers |
+| `backend-engineer` | execution | `backend:execution` | APIs, services, server-side logic | tester, database-architect, performance-engineer, devops-engineer, frontend-engineer, security-engineer |
+| `frontend-engineer` | execution | `frontend:execution` | UI components, styling, interactions | tester, designer, backend-engineer |
+| `database-architect` | execution | `data:execution` | Schema design, queries, migrations | backend-engineer, performance-engineer |
+| `mobile-engineer` | execution | `mobile:execution` | iOS, Android, React Native | tester, designer |
+| `game-engineer` | execution | `gaming:execution` | Game logic, Unity, Unreal | tester, designer |
+| `tester` | validation | `quality:validation` | Unit, integration, E2E tests | debugger, engineers |
+| `reviewer` | validation | `quality:review` | Code review, PR feedback | engineers |
+| `security-engineer` | validation | `security:validation` | Security audit, penetration testing | backend-engineer, devops-engineer |
+| `performance-engineer` | validation | `performance:validation` | Profiling, optimization | backend-engineer, frontend-engineer |
+| `debugger` | validation | `quality:debugging` | Bug investigation and resolution | engineers |
+| `researcher` | research | `research:exploration` | External research | tech-lead, planner |
+| `scouter` | research | `research:codebase` | Codebase analysis | tech-lead, planner |
+| `brainstormer` | research | `research:ideation` | Creative ideation, requirements | planner |
+| `designer` | research | `design:execution` | UI/UX design | frontend-engineer |
+| `docs-manager` | support | `research:documentation` | Technical documentation | tech-lead, engineers |
+| `devops-engineer` | support | `devops:execution` | CI/CD, deployment | backend-engineer, security-engineer |
+| `business-analyst` | support | `management:analysis` | Business requirements | planner, tech-lead |
+| `project-manager` | support | `management:coordination` | Project coordination | planner, tech-lead |
+| `reporter` | support | `research:reporting` | Reports, summaries | tech-lead |
+
+### Agent File Structure (common pattern)
+
+Each agent file follows a standard structure:
+
+1. **YAML frontmatter** — `name`, `description`, `profile`, `handoffs`, `version`, `category`
+2. **Cognitive Anchor** — `🔒 COGNITIVE ANCHOR — MANDATORY OPERATING SYSTEM` binding block
+3. **Identity table** — ID, Role, Profile, Reports To, Consults, Confidence threshold
+4. **Core Directive** — One-sentence mission statement
+5. **Skills section** — Matrix discovery reference with profile and domain list
+6. **Expert Mindset** — YAML think-like patterns and always/never rules
+7. **Thinking Protocol** — Step-by-step workflow the agent must follow
+8. **Output Format** — Structured deliverable template
+9. **Constraints** — Quality gates and boundaries
+
+---
+
+## Team Agents (Golden Triangle)
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Golden Triangle Teams |
+| **Responsibility** | Execute phases through adversarial collaboration — 3 agents per phase producing higher quality through structured debate |
+| **Key Files** | `agents/teams/*/` (17 team directories, each containing `techlead.md`, `executor.md`, `reviewer.md`) |
+| **Interfaces** | **Input**: Phase assignment from `:team` variant. **Output**: Consensus-stamped deliverable. **Lateral**: Mailbox at `./reports/{topic}/MAILBOX-{date}.md` |
+| **Dependencies** | TEAMS.md (protocol), Shared Task List (state), Mailbox (communication) |
+| **Activation** | Only when user invokes `:team` variant (e.g., `/cook:team`) |
+
+### Team Roster (17 teams × 3 roles = 51 team agents)
+
+| Team Directory | Domain |
+|---------------|--------|
+| `backend-team/` | Backend implementation |
+| `database-team/` | Database design |
+| `debug-team/` | Bug diagnosis |
+| `design-team/` | UI/UX |
+| `devops-team/` | Infrastructure |
+| `docs-team/` | Documentation |
+| `frontend-team/` | Frontend implementation |
+| `fullstack-team/` | Full-stack |
+| `game-team/` | Game development |
+| `mobile-team/` | Mobile development |
+| `performance-team/` | Performance optimization |
+| `planning-team/` | Project planning |
+| `project-team/` | Project coordination |
+| `qa-team/` | Quality assurance |
+| `report-team/` | Reporting |
+| `research-team/` | Research |
+| `security-team/` | Security |
+
+### Golden Triangle Roles (from TEAMS.md)
+
+| Role | File | Function | Authority |
+|------|------|----------|-----------|
+| **Tech Lead** | `techlead.md` | Decomposes tasks, coordinates, arbitrates disputes, synthesizes final output | FINAL on all decisions |
+| **Executor** | `executor.md` | Implements the deliverable, defends work with evidence | Owns implementation decisions |
+| **Reviewer** | `reviewer.md` | Challenges with devil's advocate mindset, validates quality | Can FAIL submissions, escalate disputes |
+
+---
+
+## Matrix Skills
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Matrix Skills (HSOL Static Layer) |
+| **Responsibility** | Provide a pre-curated registry of 1,430 skills across 19 domains, indexed for fitness-based resolution |
+| **Key Files** | `matrix-skills/_index.yaml` (central registry), `matrix-skills/_dynamic.yaml` (community skills), `matrix-skills/{domain}.yaml` (19 domain files) |
+| **Interfaces** | **Input**: Agent profile (e.g., `backend:execution`). **Output**: Sorted skill set filtered by relevance and fitness score. |
+| **Dependencies** | None — static YAML data |
+
+### Domain File Inventory (19 domains)
+
+| File | Domain |
+|------|--------|
+| `ai-ml.yaml` | AI and Machine Learning |
+| `architecture.yaml` | Software Architecture |
+| `backend.yaml` | Backend Development |
+| `cloud.yaml` | Cloud Infrastructure |
+| `data.yaml` | Data Engineering |
+| `design.yaml` | UI/UX Design |
+| `devops.yaml` | DevOps and CI/CD |
+| `frontend.yaml` | Frontend Development |
+| `gaming.yaml` | Game Development |
+| `languages.yaml` | Programming Languages |
+| `management.yaml` | Project Management |
+| `mcp.yaml` | Model Context Protocol |
+| `mobile.yaml` | Mobile Development |
+| `performance.yaml` | Performance Engineering |
+| `planning.yaml` | Planning |
+| `quality.yaml` | Quality Assurance |
+| `research.yaml` | Research |
+| `security.yaml` | Security |
+| `tools.yaml` | Developer Tools |
+
+---
+
+## Skills (Modules)
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Skill Modules |
+| **Responsibility** | Provide domain-specific knowledge, best practices, and patterns that agents read to produce higher-quality output |
+| **Key Files** | `skills/*/SKILL.md` (1,430+ directories, each with a SKILL.md file) |
+| **Interfaces** | Read-only — agents load SKILL.md content and follow its instructions |
+| **Dependencies** | Referenced by Matrix Skills domain files; discovered by HSOL resolution or `find-skills` dynamic discovery |
+| **Structure** | Each skill is a self-contained directory with at minimum a `SKILL.md` defining best practices |
+
+---
+
+## CLI Installer
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | CLI Installer |
+| **Responsibility** | Copy framework files from npm package to each platform's global directory, performing `{TOOL}` placeholder substitution |
+| **Key Files** | `cli/install.js` (main), `cli/README.md` (usage docs) |
+| **Interfaces** | **Input**: `npx agent-assistant install [tool\|--all]`. **Output**: Files in `~/.{tool}/skills/agent-assistant/`. |
+| **Dependencies** | Node.js >=18.0.0, built-in modules only (`fs`, `path`, `os`, `readline`) |
+| **Platforms Supported** | Cursor, GitHub Copilot, Claude Code (via Antigravity path), Codex, Antigravity/Gemini |
+
+### CLI Commands (from package.json)
+
+| Command | Action |
+|---------|--------|
+| `npx agent-assistant install cursor` | Install to `~/.cursor/skills/agent-assistant/` |
+| `npx agent-assistant install copilot` | Install to `~/.copilot/skills/agent-assistant/` |
+| `npx agent-assistant install antigravity` | Install to Gemini/Antigravity path |
+| `npx agent-assistant install codex` | Install to `~/.codex/skills/agent-assistant/` |
+| `npx agent-assistant install --all` | Install to all platforms |
+| `npx agent-assistant uninstall [tool]` | Remove from specified platform |
+| `npx agent-assistant list` | Show installed platforms |
+
+### Replacement Maps (from cli/install.js)
+
+The installer replaces these placeholders in all copied Markdown/YAML files:
+
+| Placeholder | Example Replacement (Cursor) |
+|------------|------------------------------|
+| `~/.{TOOL}/skills/agent-assistant/` | `~/.cursor/skills/agent-assistant/` |
+| `{TOOL}/agent-assistant/` | `cursor/skills/agent-assistant/` |
+| `{TOOL}` | `cursor` |
+| `{HOME}` | `~` |
+| `~/.agent/` | `~/.cursor/skills/agent-assistant/` |
+
+---
+
+## Code Assistants (Platform Templates)
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Code Assistants |
+| **Responsibility** | Provide platform-specific assets that are copied alongside the core framework during installation |
+| **Key Files** | `code-assistants/cursor-assistant/`, `code-assistants/copilot-assistant/`, `code-assistants/claude-assistant/`, `code-assistants/codex-assistant/`, `code-assistants/antigravity-assistant/` |
+| **Interfaces** | Consumed by `cli/install.js` during installation — not used at runtime |
+| **Dependencies** | CLI Installer (consumer) |
+
+Each platform template directory contains platform-specific configuration files:
+
+| Platform | Notable Assets |
+|----------|---------------|
+| Cursor | Rules directory, `.cursorrules` file |
+| Copilot | `agent-assistant.agent.md` (VS Code prompt file) |
+| Claude Code | Claude-specific configuration |
+| Codex | Codex-specific configuration |
+| Antigravity | Gemini-specific configuration |
+
+---
+
+## Platform Entry Points
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Platform Entry Points |
+| **Responsibility** | Serve as the first file the AI reads — bind identity, set paths, and mandate CORE.md loading |
+| **Key Files** | `CLAUDE.md`, `COPILOT.md`, `CURSOR.md`, `CODEX.md`, `GEMINI.md`, `AGENT.md` (generic) |
+| **Interfaces** | **Input**: AI model boot. **Output**: Orchestrator identity activation. |
+| **Dependencies** | `rules/CORE.md` (loaded immediately) |
+| **Pattern** | All entry points share identical structure with platform-specific paths resolved at install |
+
+### Common Structure (verified from CLAUDE.md, COPILOT.md)
+
+1. **Mandatory boot sequence** — Read CORE.md before any action
+2. **Identity binding** — "YOU ARE THE ORCHESTRATOR — NOT AN IMPLEMENTER"
+3. **Path definitions** — COMMANDS, AGENTS, SKILLS, RULES, REPORTS
+4. **Command routing table** — Input → file mapping
+5. **Tiered execution** — TIER 1 mandatory, TIER 2 fallback
+6. **Prohibitions** — Never write code, debug, test, or design directly
+7. **Self-check** — Execute before every response
+
+---
+
+## Web Application
+
+| Attribute | Value |
+|-----------|-------|
+| **Name** | Marketing Website |
+| **Responsibility** | Public-facing marketing site for the Agent Assistant project |
+| **Key Files** | `web/` directory (React 19 + Vite + Tailwind CSS v4) |
+| **Interfaces** | Standalone web application deployed to Vercel |
+| **Dependencies** | Independent sub-project — not part of the core framework or npm distribution |
+| **Relationship** | Listed in the workspace but architecturally separate from the orchestrator framework |
+
+---
+
+## Evidence Sources
+
+| Source | Path | What It Provides |
+|--------|------|------------------|
+| CORE.md v4.1 | `rules/CORE.md` | Orchestrator identity, execution loop, 10 laws, command routing, platform table |
+| AGENTS.md | `rules/AGENTS.md` | Tiered execution, agent categories (5), tool discovery, completion guarantee |
+| TEAMS.md | `rules/TEAMS.md` | Golden Triangle: 3 roles, debate mechanism, mailbox protocol, C8 checkpoints |
+| SKILLS.md | `rules/SKILLS.md` | HSOL algorithm, fitness formula, trust progression lifecycle |
+| REFERENCE.md | `rules/REFERENCE.md` | Command table (14), agent table (21), NLP detection, deliverable paths |
+| PHASES.md | `rules/PHASES.md` | Phase output format (standard + Golden Triangle), requirements registry |
+| ERRORS.md | `rules/ERRORS.md` | Error classification (5 classes), recovery protocol, anti-patterns (10) |
+| _index.yaml | `matrix-skills/_index.yaml` | HSOL config, 1,430 skills, 19 domains, discovery settings |
+| package.json | `package.json` | Version, scripts, deps, files array, engine requirements |
+| cli/install.js | `cli/install.js` | Platform configs (5), replacement maps, directory paths |
+| cook.md | `commands/cook.md` | Example router: pre-flight, routing logic, variant table |
+| backend-engineer.md | `agents/backend-engineer.md` | Example agent: frontmatter, cognitive anchor, profile, handoffs |
+| docs-manager.md | `agents/docs-manager.md` | Example support agent: profile `research:documentation` |
+| agents/teams/ | `agents/teams/` | 17 team directories confirmed via directory listing |