@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/knowledge-source-base/03-key-modules.md

@@ -0,0 +1,582 @@
+# Agent Assistant — Key Modules
+
+> **Purpose**: Per-module breakdown of purpose, exports, dependencies, and internal structure for all major modules in the framework
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Module 1: CLI Installer (cli/)](#module-1-cli-installer-cli)
+- [Module 2: Agents (agents/)](#module-2-agents-agents)
+- [Module 3: Commands (commands/)](#module-3-commands-commands)
+- [Module 4: Rules (rules/)](#module-4-rules-rules)
+- [Module 5: Matrix Skills — HSOL (matrix-skills/)](#module-5-matrix-skills--hsol-matrix-skills)
+- [Module 6: Skills (skills/)](#module-6-skills-skills)
+- [Module 7: Code Assistants (code-assistants/)](#module-7-code-assistants-code-assistants)
+- [Module 8: Platform Entry Points (Root Markdown)](#module-8-platform-entry-points-root-markdown)
+- [Module 9: Web Marketing Site (web/)](#module-9-web-marketing-site-web)
+- [Module 10: Documents (documents/)](#module-10-documents-documents)
+- [Module Dependency Map](#module-dependency-map)
+- [Evidence Sources](#evidence-sources)
+
+---
+
+## Overview
+
+Agent Assistant operates as a "content framework" — the majority of its modules are Markdown/YAML files interpreted by AI coding tools. Only two modules contain executable code: the CLI installer (`cli/`) and the web marketing site (`web/`). All other modules are declarative configuration consumed by AI assistants at prompt-interpretation time.
+
+---
+
+## Module 1: CLI Installer (cli/)
+
+### Purpose
+The sole executable module in the published npm package. Copies framework files from the package to platform-specific directories on the user's machine, with placeholder replacement for cross-platform compatibility.
+
+### Files
+
+| File | Size | Role |
+|------|------|------|
+| `install.js` | ~600 LOC | Main CLI entry, all logic in one file |
+| `install.test.js.example` | Template | Example test file (not active) |
+| `README.md` | Doc | CLI-specific usage guide |
+
+### Internal Structure of install.js
+
+The file is organized into clearly labeled sections:
+
+| Section | Lines (approx.) | Contents |
+|---------|-----------------|----------|
+| Header / JSDoc | 1–30 | Shebang, documentation comment, usage examples |
+| Imports | 31–34 | `node:fs`, `node:path`, `node:os`, `node:readline` |
+| Configuration | 35–210 | `HOME`, `ROOT`, `getVSCodePromptsFolder()`, `TOOLS` object (5 platforms), `CORE_DIRS`, `ROOT_FILES`, `BUNDLED_AGENTS` |
+| Progress Tracking | 210–320 | `progressState`, `resetProgress()`, `countFiles()`, `drawProgress()`, `updateProgress()`, `completeProgress()`, `logError()` |
+| File Operations | 320–460 | `ensureDir()`, `copyWithReplace()`, `copyFileWithReplace()`, `removeDir()`, `removeFile()`, `formatNumber()`, `estimateInstallFiles()`, `verifyInstallation()`, `printSummary()` |
+| Install Functions | 460–end | `installCursor()`, `installCopilot()`, `installAntigravity()`, `installClaude()`, `installCodex()` + corresponding uninstall functions, `list()`, `main()` |
+
+### Key Data Structures
+
+**TOOLS Config Object** — Defines per-platform installation configuration:
+
+```javascript
+TOOLS = {
+  cursor: {
+    name: 'Cursor',
+    description: 'Cursor AI Editor',
+    paths: {
+      editorHome: '~/.cursor',
+      rules: '~/.cursor/rules',
+      skills: '~/.cursor/skills',
+      agents: '~/.cursor/agents',
+      commands: '~/.cursor/commands',
+      agentAssistant: '~/.cursor/skills/agent-assistant'
+    },
+    replacements: { '{TOOL}': 'cursor', ... },
+    assets: { rules: '...', cursorRules: '...' }
+  },
+  // copilot, antigravity, claude, codex follow same shape
+}
+```
+
+**CORE_DIRS** — Directories copied into the framework install location:
+```javascript
+['agents', 'rules', 'documents', 'commands', 'matrix-skills']
+```
+
+**BUNDLED_AGENTS** — 20 agent filenames for cleanup (remove only framework agents, preserve user-custom):
+```javascript
+['backend-engineer.md', 'brainstormer.md', ..., 'tester.md']
+```
+
+### Dependencies
+- **Runtime**: Zero external dependencies. Uses only Node.js built-ins (`node:fs`, `node:path`, `node:os`, `node:readline`)
+- **Minimum Node version**: 18.0.0 (enforced in `package.json` `engines`)
+
+### Security Measures
+- Symbolic links are explicitly skipped during file copy (`entry.isSymbolicLink()` check) to prevent path traversal attacks
+- Hidden files (`.` prefix) and `node_modules` are skipped during recursive copy
+- File writes use `fsync` for reliability: `fs.openSync()` → `fs.writeSync()` → `fs.fsyncSync()` → `fs.closeSync()`
+
+---
+
+## Module 2: Agents (agents/)
+
+### Purpose
+Defines specialist agent personas that the Orchestrator delegates tasks to. Each agent file is a Markdown document with YAML frontmatter specifying capabilities, tool access, and HSOL profile for skill resolution.
+
+### Structure
+
+| Category | Count | Location |
+|----------|-------|----------|
+| Solo agents | 21 | `agents/*.md` |
+| Team directories | 17 | `agents/teams/{team-name}/` |
+| Team roles per team | 3 | `executor.md`, `reviewer.md`, `techlead.md` |
+| Team agent files | 51 | `agents/teams/*/` |
+| **Total** | **72** | |
+
+### Agent File Format (from AGENT-TEMPLATE.md)
+
+Required YAML frontmatter fields:
+- `name` — Agent identifier
+- `description` — One-line purpose
+- `profile` — HSOL profile string: `"{domain}:{category}"` (e.g., `"backend:execution"`)
+- `tools` — Available tools list
+- `handoffs` — Agents this agent can delegate to
+- `version` — Agent version
+- `category` — One of: `execution`, `planning`, `validation`, `research`, `debugging`, `orchestration`
+
+Required Markdown sections (in order):
+1. Cognitive Anchor (binding directive)
+2. Identity (role description)
+3. Matrix skill discovery profile
+4. Execution workflow
+5. Output format
+
+### Solo Agent Roster
+
+| Agent | Domain Focus |
+|-------|-------------|
+| `backend-engineer` | Server-side implementation |
+| `brainstormer` | Ideation and creative solutions |
+| `business-analyst` | Business requirements analysis |
+| `database-architect` | Database design and optimization |
+| `debugger` | Bug investigation and resolution |
+| `designer` | UI/UX design |
+| `devops-engineer` | CI/CD and infrastructure |
+| `docs-manager` | Documentation architecture |
+| `frontend-engineer` | Client-side implementation |
+| `game-engineer` | Game development |
+| `mobile-engineer` | Mobile app development |
+| `performance-engineer` | Performance optimization |
+| `planner` | Task planning and decomposition |
+| `project-manager` | Project coordination |
+| `reporter` | Report generation |
+| `researcher` | Research and analysis |
+| `reviewer` | Code review |
+| `scouter` | Technology scouting |
+| `security-engineer` | Security analysis and hardening |
+| `tech-lead` | Architecture decisions |
+| `tester` | Testing strategy and execution |
+
+### Team Directory Structure
+
+Each team has 3 role files with consistent naming:
+
+| Team | executor.md | reviewer.md | techlead.md |
+|------|------------|-------------|-------------|
+| backend-team | ✓ | ✓ | ✓ |
+| database-team | ✓ | ✓ | ✓ |
+| debug-team | ✓ | ✓ | ✓ |
+| design-team | ✓ | ✓ | ✓ |
+| devops-team | ✓ | ✓ | ✓ |
+| docs-team | ✓ | ✓ | ✓ |
+| frontend-team | ✓ | ✓ | ✓ |
+| fullstack-team | ✓ | ✓ | ✓ |
+| game-team | ✓ | ✓ | ✓ |
+| mobile-team | ✓ | ✓ | ✓ |
+| performance-team | ✓ | ✓ | ✓ |
+| planning-team | ✓ | ✓ | ✓ |
+| project-team | ✓ | ✓ | ✓ |
+| qa-team | ✓ | ✓ | ✓ |
+| report-team | ✓ | ✓ | ✓ |
+| research-team | ✓ | ✓ | ✓ |
+| security-team | ✓ | ✓ | ✓ |
+
+### Dependencies
+- Consumed by: AI coding tools at runtime, `rules/AGENTS.md`, `rules/TEAMS.md`
+- Depends on: `AGENT-TEMPLATE.md` (format), `matrix-skills/` (profile-based skill injection)
+
+---
+
+## Module 3: Commands (commands/)
+
+### Purpose
+Implements the command routing system — the primary user-facing interface. Users invoke commands like `/cook`, `/fix`, `/plan` and the Orchestrator loads the corresponding command file, optionally with a variant modifier.
+
+### Structure
+
+**14 Router Files** (at `commands/` root):
+
+| Command | Variant Subdirectory | Variants |
+|---------|---------------------|----------|
+| `ask.md` | `ask/` | `fast`, `hard` |
+| `auto.md` | — | (no variants) |
+| `brainstorm.md` | `brainstorm/` | `fast`, `hard`, `team` |
+| `code.md` | `code/` | `fast`, `focus`, `hard`, `team` |
+| `cook.md` | `cook/` | `fast`, `focus`, `hard`, `team` |
+| `debug.md` | `debug/` | `fast`, `focus`, `hard`, `team` |
+| `deploy.md` | `deploy/` | `check`, `preview`, `production`, `rollback` |
+| `design.md` | `design/` | `fast`, `focus`, `hard`, `team` |
+| `docs.md` | `docs/` | `audit`, `business`, `core` |
+| `fix.md` | `fix/` | `fast`, `focus`, `hard`, `team` |
+| `plan.md` | `plan/` | `fast`, `focus`, `hard`, `team` |
+| `report.md` | `report/` | `fast`, `focus`, `hard`, `team` |
+| `review.md` | `review/` | `fast`, `hard`, `team` |
+| `test.md` | `test/` | `fast`, `focus`, `hard`, `team` |
+
+**Variant Pattern Categories**:
+
+| Pattern | Variants | Used By |
+|---------|----------|---------|
+| Standard (4 variants) | `fast`, `focus`, `hard`, `team` | code, cook, debug, design, fix, plan, report, test |
+| Standard-3 (no focus) | `fast`, `hard`, `team` | brainstorm, review |
+| Minimal (2 variants) | `fast`, `hard` | ask |
+| Deploy-specific | `check`, `preview`, `production`, `rollback` | deploy |
+| Docs-specific | `audit`, `business`, `core` | docs |
+| No variants | — | auto |
+
+**Total**: 14 router files + 47 variant files = 61 command Markdown files
+
+### Routing Logic
+The Orchestrator (defined in `rules/CORE.md`) routes commands as follows:
+1. User invokes `/command` or `/command:variant`
+2. Orchestrator loads `commands/{command}.md` as the router
+3. If variant specified, loads `commands/{command}/{variant}.md`
+4. Natural language mapping: "implement/build/create" → `/cook` or `/code`, "fix/bug" → `/fix`, "plan" → `/plan`
+
+### Dependencies
+- Referenced by: `rules/CORE.md` (command routing table), `rules/REFERENCE.md` (quick lookup)
+- Commands are copied to both `commands/` and `workflows/` during installation for backward compatibility
+- Team variants (`:team`) depend on `rules/TEAMS.md` for multi-agent coordination
+
+---
+
+## Module 4: Rules (rules/)
+
+### Purpose
+Defines the Orchestrator's operating protocol — the "operating system" for the AI agent. Rules are loaded on-demand to conserve context window space.
+
+### Files
+
+| File | Version | Load Priority | Purpose |
+|------|---------|--------------|---------|
+| `CORE.md` | v4.1 | **Mandatory — always first** | Identity, paths, 10 Laws, prohibitions, self-check, platform resolution |
+| `PHASES.md` | — | On demand (running phases) | Phase execution workflow, output format requirements, exit criteria |
+| `AGENTS.md` | — | On demand (delegating) | Tiered execution: Tier 1 (sub-agent), Tier 2 (embodiment fallback) |
+| `SKILLS.md` | — | On demand (skill resolution) | HSOL protocol: matrix-first resolution, dynamic discovery, fitness scoring |
+| `TEAMS.md` | — | On demand (team commands) | Team execution protocol for `:team` variant commands |
+| `ERRORS.md` | — | On demand (errors) | Error recovery procedures, fallback strategies |
+| `REFERENCE.md` | — | On demand (quick lookup) | Quick lookup tables: commands, agents, skills mapping |
+
+### Key Concepts from CORE.md
+
+**Identity Binding**: The Orchestrator is explicitly prohibited from writing code, debugging, testing, or designing directly. It must delegate all implementation to specialist agents.
+
+**Path Resolution**: Uses `{TOOL}` placeholder replaced at install time:
+| Platform | `{TOOL}` Value | Install Path |
+|----------|---------------|--------------|
+| Cursor | `cursor` | `~/.cursor/skills/agent-assistant/` |
+| Copilot | `copilot` | `~/.copilot/skills/agent-assistant/` |
+| Antigravity | `gemini/antigravity` | `~/.gemini/antigravity/skills/agent-assistant/` |
+| Claude | `claude` | `~/.claude/skills/agent-assistant/` |
+| Codex | `codex` | `~/.codex/skills/agent-assistant/` |
+
+**Tiered Execution** (from AGENTS.md):
+- **Tier 1**: Use sub-agent (isolated context) when `runSubagent` capability exists
+- **Tier 2**: Fallback to embodiment (Orchestrator assumes agent role) when Tier 1 unavailable
+
+### Dependencies
+- Loaded by: Platform entry point files (AGENT.md, CLAUDE.md, etc.)
+- References: `commands/`, `agents/`, `matrix-skills/`, `skills/`
+
+---
+
+## Module 5: Matrix Skills — HSOL (matrix-skills/)
+
+### Purpose
+Implements the Hybrid Skill Orchestration Layer (HSOL) — a two-layer system for dynamically resolving and injecting skills into agent contexts based on their profile and the task at hand.
+
+### Architecture
+
+```
+HSOL Resolution Flow:
+  Agent Request → Profile ('backend:execution')
+       ↓
+  Static Layer: Load domain YAML (backend.yaml)
+       ↓
+  Match skills by relevance_mapping + priority
+       ↓
+  Dynamic Layer: Check _dynamic.yaml for community skills
+       ↓
+  If matrix fitness < 0.8: Run find-skills discovery
+       ↓
+  Inject matched SKILL.md files into agent context
+```
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `_index.yaml` | Master HSOL configuration v1.1: enables HSOL, sets discovery parameters, defines `find-skills` integration commands, configures async threshold (0.8), variant applicability (`hard`, `focus` only — `fast` skips discovery) |
+| `_dynamic.yaml` | Manifest for community-installed skills added via `npx skills add` |
+| 19 domain `.yaml` files | Pre-curated skill registries mapped to agent profiles |
+
+### Domain Registry Files
+
+| Domain File | Skill Area |
+|-------------|-----------|
+| `ai-ml.yaml` | AI and machine learning |
+| `architecture.yaml` | Software architecture |
+| `backend.yaml` | Server-side development |
+| `cloud.yaml` | Cloud infrastructure |
+| `data.yaml` | Data engineering |
+| `design.yaml` | UI/UX design |
+| `devops.yaml` | DevOps and CI/CD |
+| `frontend.yaml` | Client-side development |
+| `gaming.yaml` | Game development |
+| `languages.yaml` | Programming language specifics |
+| `management.yaml` | Project management |
+| `mcp.yaml` | Model Context Protocol integration |
+| `mobile.yaml` | Mobile development |
+| `performance.yaml` | Performance optimization |
+| `planning.yaml` | Planning and strategy |
+| `quality.yaml` | Quality assurance |
+| `research.yaml` | Research methodologies |
+| `security.yaml` | Security practices |
+| `tools.yaml` | Development tooling |
+
+### HSOL Configuration Highlights (from _index.yaml)
+
+| Setting | Value | Meaning |
+|---------|-------|---------|
+| `version` | 1.1 | HSOL protocol version |
+| `total_matrix_skills` | 1,430 | Total pre-curated skills |
+| `async_threshold` | 0.8 | Matrix fitness above this skips dynamic discovery |
+| `apply_for_variants` | `["hard", "focus"]` | Dynamic discovery only runs for these variants |
+| `timeout_ms` | 5,000 | Discovery timeout |
+| `cache_ttl_seconds` | 3,600 | Discovery cache duration |
+| `find-skills` CLI commands | `npx skills find`, `npx skills add`, `npx skills check`, `npx skills update` | External skill service integration |
+
+### Dependencies
+- Referenced by: `rules/SKILLS.md` (resolution protocol), agents (via `profile` frontmatter)
+- References: `skills/` directory (resolved skill folders), `skills/find-skills/SKILL.md` (discovery skill)
+- External: `https://skills.sh/` (browse URL for dynamic discovery)
+- Referenced in: `documents/SMART-SKILL-ORCHESTRATION-BLUEPRINT.md`
+
+---
+
+## Module 6: Skills (skills/)
+
+### Purpose
+Contains 1,430 individual skill folders, each containing a `SKILL.md` file that defines the skill's purpose, best practices, and usage patterns. Skills are the atomic units of knowledge injected into agent contexts by the HSOL.
+
+### Structure
+```
+skills/
+├── 00-andruia-consultant/
+│   └── SKILL.md
+├── 007/
+│   └── SKILL.md
+├── 10-andruia-skill-smith/
+│   └── SKILL.md
+├── ... (1,430 total)
+└── find-skills/
+    └── SKILL.md          # Special: HSOL dynamic discovery
+```
+
+### Special Skill: find-skills
+
+The `find-skills/SKILL.md` skill is referenced by the HSOL `_index.yaml` as the dynamic discovery mechanism. It defines how to search for, install, and manage community skills from the external `skills.sh` service.
+
+### Dependencies
+- Resolved by: `matrix-skills/` YAML registries via HSOL profile matching
+- Installed to: `~/.{tool}/skills/` (alongside the `agent-assistant/` framework directory)
+
+---
+
+## Module 7: Code Assistants (code-assistants/)
+
+### Purpose
+Stores platform-specific template files and assets that extend the base framework for each supported AI coding tool. These files handle platform-specific conventions, file formats, and directory structures.
+
+### Platform Breakdown
+
+#### cursor-assistant/
+
+| Asset | Purpose |
+|-------|---------|
+| `.cursorrules` | Cursor-specific rules file; installed as `CURSOR.md` into `~/.cursor/` |
+| `rules/` | MDC (Markdown Cursor) rule files for Cursor's native rules system |
+
+#### copilot-assistant/
+
+| Asset | Purpose |
+|-------|---------|
+| `agent-assistant.agent.md` | Copilot agent mode specification file; installed to VS Code prompts folder |
+
+#### antigravity-assistant/
+
+| Asset | Purpose |
+|-------|---------|
+| `GEMINI.md` | Gemini-specific entry point; installed to `~/.gemini/` |
+| `AntigravityGlobal.agent.md` | Global agent file; installed to `~/.gemini/agents/` |
+
+#### claude-assistant/
+
+| Asset | Purpose |
+|-------|---------|
+| `CLAUDE.md` | Claude Code-specific entry point; installed to `~/.claude/` |
+
+#### codex-assistant/
+
+| Asset | Purpose |
+|-------|---------|
+| `CODEX.md` | Codex-specific entry point; installed to `~/.codex/` |
+| `config.toml` | Codex configuration in TOML format |
+| `agents/` | Codex-specific agent definitions |
+| `skills/` | Codex-specific skill overrides |
+
+### Dependencies
+- Consumed by: `cli/install.js` (TOOLS config references these paths via `assets` property)
+- Each platform template references: root `AGENT.md`, `CLAUDE.md`, framework rules
+
+---
+
+## Module 8: Platform Entry Points (Root Markdown)
+
+### Purpose
+Root-level Markdown files serve as the "boot configuration" for each AI coding tool. When the AI tool starts, it reads the appropriate file to initialize the Orchestrator role with platform-specific path resolution.
+
+### Files
+
+| File | Consumed By | Key Content |
+|------|-----------|-------------|
+| `AGENT.md` | All platforms (generic) | Orchestrator identity, command routing, path definitions with `{TOOL}` placeholders |
+| `CLAUDE.md` | Claude Code | Claude-specific orchestrator boot instructions |
+| `COPILOT.md` | GitHub Copilot | Copilot-specific entry point |
+| `CURSOR.md` | Cursor | Cursor-specific rules and conventions |
+| `CODEX.md` | OpenAI Codex | Codex-specific entry point |
+| `GEMINI.md` | Antigravity/Gemini | Gemini-specific entry point |
+| `AGENT-TEMPLATE.md` | Developers | Template for creating new agent files (not installed) |
+
+### Dependencies
+- Loaded by: AI coding tools on startup
+- References: `rules/CORE.md` (loaded first), `commands/`, `agents/`
+- Installed copies are modified by `cli/install.js` with platform-specific replacements
+
+---
+
+## Module 9: Web Marketing Site (web/)
+
+### Purpose
+A standalone React 19 + Vite + Tailwind CSS marketing website for the agent-assistant project. Deployed to Vercel. Not part of the published npm package.
+
+### Technology Stack
+
+| Technology | Version | Role |
+|------------|---------|------|
+| React | 19.2.0 | UI framework |
+| React DOM | 19.2.0 | DOM rendering |
+| React Router DOM | 7.13.0 | Client-side routing |
+| Framer Motion | 12.29.2 | Animations |
+| Lucide React | 0.563.0 | Icon library |
+| @xyflow/react | 12.10.0 | Flow/graph visualization |
+| clsx | 2.1.1 | Class name utility |
+| react-helmet-async | 2.0.5 | Document head management |
+| Vite | (devDep) | Build tool |
+| Tailwind CSS v4 | (via @tailwindcss/vite) | CSS framework |
+| TypeScript | (devDep) | Type-checking |
+| ESLint v9 | (devDep) | Linting |
+
+### Source Structure
+
+| Path | Purpose |
+|------|---------|
+| `src/main.tsx` | React DOM entry point |
+| `src/App.tsx` | Root component with routing |
+| `src/components/` | Reusable UI components |
+| `src/pages/` | Route page components |
+| `src/data/` | Static data files |
+| `src/hooks/` | Custom React hooks |
+| `src/lib/` | Utility libraries |
+| `src/styles/` | CSS / Tailwind styles |
+| `src/types/` | TypeScript type definitions |
+
+### Build Configuration
+- **Vite plugins**: `@vitejs/plugin-react`, `@tailwindcss/vite`
+- **Build target**: `esnext`
+- **Minifier**: `esbuild`
+- **Code splitting**: Manual chunks for `react-vendor` (react, react-dom, react-router-dom) and `animation-vendor` (framer-motion)
+- **TypeScript**: ES2022 target, bundler module resolution, React JSX transform
+- **ESLint**: Flat config with `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, `eslint-plugin-react-refresh`
+
+### Deployment
+- **Platform**: Vercel
+- **Config**: `vercel.json` with SPA rewrite: all routes → `/index.html`
+
+### Dependencies
+- Independent from main package (separate `package.json`)
+- Not included in npm `files` array
+
+---
+
+## Module 10: Documents (documents/)
+
+### Purpose
+Houses project-level documentation that goes beyond the README. Provides architectural assessments and knowledge bases for contributors.
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `HSOL-ASSESSMENT.md` | Evaluation and assessment of the Hybrid Skill Orchestration Layer |
+| `SMART-SKILL-ORCHESTRATION-BLUEPRINT.md` | Architectural blueprint for the HSOL skill resolution system |
+| `knowledge-source-base/` | This comprehensive documentation set |
+
+### Dependencies
+- Referenced by: `matrix-skills/_index.yaml` (links to blueprint), `rules/SKILLS.md`
+- Included in npm `files` array and `CORE_DIRS` (copied during installation)
+
+---
+
+## Module Dependency Map
+
+```
+Platform Markdown Files (AGENT.md, CLAUDE.md, etc.)
+    └── rules/CORE.md (mandatory first load)
+        ├── rules/PHASES.md (phase execution)
+        ├── rules/AGENTS.md (delegation protocol)
+        │   └── agents/*.md (specialist agents)
+        │       └── agents/teams/*/ (team variants)
+        ├── rules/SKILLS.md (skill resolution)
+        │   └── matrix-skills/_index.yaml (HSOL config)
+        │       ├── matrix-skills/{domain}.yaml (static layer)
+        │       ├── matrix-skills/_dynamic.yaml (dynamic layer)
+        │       └── skills/find-skills/SKILL.md (discovery)
+        │           └── skills/*/ (1,430 skill definitions)
+        ├── rules/TEAMS.md (team coordination)
+        ├── rules/ERRORS.md (error handling)
+        └── rules/REFERENCE.md (lookup tables)
+            └── commands/*.md + commands/*/  (command routing)
+
+cli/install.js (independent entry — copies all above into tool directories)
+    └── code-assistants/*/ (platform-specific assets)
+
+web/ (independent — not connected to framework modules)
+```
+
+---
+
+## Evidence Sources
+
+| File | Why it was used |
+|------|-----------------|
+| `cli/install.js` (full file) | Internal structure, TOOLS config, CORE_DIRS, BUNDLED_AGENTS, file operation functions, install functions, security measures |
+| `package.json` | Module entry points (`main`, `bin`), zero production deps, engine constraint |
+| `AGENT-TEMPLATE.md` | Agent file format: required frontmatter fields, profile values, section order |
+| `agents/` listing | Solo agent roster (21 files) |
+| `agents/teams/` listing | 17 team directories × 3 roles |
+| `commands/` and `commands/*/` listings | Router files and variant structure |
+| `rules/CORE.md` | Orchestrator identity, path resolution, platform table, tiered execution |
+| `matrix-skills/_index.yaml` | HSOL v1.1 config, total skills, discovery settings, variant applicability |
+| `code-assistants/*/` listings | Per-platform asset files |
+| `web/package.json` | Web app dependencies and versions |
+| `web/vite.config.ts` | Build plugins, chunk splitting, targets |
+| `web/tsconfig.app.json` | TypeScript compiler options |
+| `web/eslint.config.js` | ESLint flat config plugins |
+| `web/vercel.json` | Deployment configuration |
+| `web/src/` listing | Source directory organization |
+| `documents/` listing | Documentation inventory |