@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-workflows/04-decision-rules-and-exceptions.md

@@ -0,0 +1,216 @@
+# Agent Assistant — Decision Rules & Exceptions
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Codify all business rules governing workflow behavior, including orchestration laws, tiered execution, phase sequencing, HSOL thresholds, debate limits, error classification, and the exception catalog |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## 1. Orchestration Laws (Workflow-Relevant)
+
+The 10 Orchestration Laws define absolute behavioral constraints on the Orchestrator. The following laws have direct workflow implications:
+
+| Law | Name | Rule | Workflow Impact |
+|-----|------|------|----------------|
+| L1 | Load Before Act | CORE.md must be loaded before any action | BW-003: pre-flight requires CORE.md loaded |
+| L2 | Never Guess | Ambiguous requirements → PAUSE + ASK | BW-003: halts command execution until clarified |
+| L3 | Follow the File | Workflow files are authoritative — follow them exactly | BW-003: variant file dictates phase sequence |
+| L4 | Phase Order | Phase N must complete before Phase N+1 | BW-003, BW-009: strict sequential execution |
+| L5 | Verify Exit | Every phase exit criteria must be verified | BW-003, BW-004: gate between phases |
+| L6 | Prefer TIER 1 | Sub-agent (isolated) always preferred over embodiment | BW-004: delegation tier selection |
+| L7 | Never Implement | Orchestrator delegates — never writes code or implements directly | All workflows: Orchestrator is coordinator only |
+| L8 | Immutable Deliverables | Output from Phase N is read-only in Phase N+1 | BW-003: inter-phase data contract |
+| L9 | Explicit Failure | No silent failures — every error must surface | BW-010: terminal guarantee |
+| L10 | Scope Lock | Stay within the defined scope — no scope creep | All workflows: boundary enforcement |
+
+---
+
+## 2. Tiered Execution Rules
+
+### Rule Set
+
+| Rule ID | Rule | Condition | Action |
+|---------|------|-----------|--------|
+| TE-001 | TIER 1 priority | `runSubagent` is available | MUST use TIER 1 (isolated sub-agent) |
+| TE-002 | TIER 2 fallback | `runSubagent` unavailable OR fails | MAY use TIER 2 (embodiment) with logged justification |
+| TE-003 | TIER 2 logging | TIER 2 used | MUST log reason for TIER 2 selection |
+| TE-004 | No TIER 2 when TIER 1 works | `runSubagent` available and functional | FORBIDDEN to use TIER 2 |
+| TE-005 | Deliverable parity | Either tier produces output | Deliverable format and exit criteria are identical regardless of tier |
+
+### TIER Comparison
+
+| Aspect | TIER 1 (Sub-Agent) | TIER 2 (Embodiment) |
+|--------|--------------------|--------------------|
+| Context | Isolated — scoped to phase | Shared — Orchestrator's full context |
+| Risk | Low — no context bleed | Higher — potential context interference |
+| Preference | Always preferred | Fallback only |
+| Logging | Standard | Must include TIER 2 justification |
+| Deliverable | Returned from sub-agent | Extracted from shared context |
+
+---
+
+## 3. Phase Sequencing Rules
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| PS-001 | Sequential execution | Phases execute in defined order — no parallelism, no reordering |
+| PS-002 | Gate verification | Each phase's exit criteria must be verified before proceeding |
+| PS-003 | Input immutability | A phase receives prior deliverables as read-only inputs (Law 8) |
+| PS-004 | Halt on failure | If exit criteria not met and BW-010 cannot recover → halt workflow |
+| PS-005 | No skip | Phases cannot be skipped except via explicit short-circuit (BW-011) |
+| PS-006 | Plan short-circuit | If valid PLAN-*.md referenced in /code:hard or /code:team → skip research/scout/brainstorm phases |
+| PS-007 | Variant authority | The variant file defines the phase sequence — no deviation |
+
+---
+
+## 4. HSOL Threshold Rules
+
+### Fitness Band Routing
+
+| Rule ID | Fitness Band | Route | Blocking? | Discovery? |
+|---------|-------------|-------|-----------|------------|
+| HS-001 | ≥ 0.8 | Matrix skills only | No | No |
+| HS-002 | 0.75 – 0.8 | Matrix skills + async discovery | No | Async (BW-006) |
+| HS-003 | < 0.75 | Blocking discovery | Yes | Sync (BW-006) |
+
+### Discovery Rules
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| HS-004 | Superiority delta | Dynamic skill must exceed current best by > 0.15 to be adopted |
+| HS-005 | Confirmation gate | Low-trust skill + critical task → Framework User confirmation required |
+| HS-006 | Timeout ceiling | Discovery must complete within 5 seconds; timeout → matrix-only |
+| HS-007 | Install rollback | Failed installation → rollback + offer matrix alternatives |
+| HS-008 | Hard/team only | Dynamic discovery only triggers for hard and team command variants |
+
+### Trust Progression Rules
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| TP-001 | Initial trust | Newly discovered skills start at NEW (0.3) |
+| TP-002 | Promotion: NEW → EVALUATING | 3 successive successful executions |
+| TP-003 | Promotion: EVALUATING → VALIDATED | 10 successive successful executions |
+| TP-004 | Promotion: VALIDATED → PROMOTED | count ≥ 10, success rate ≥ 85%, inactive ≤ 30 days |
+| TP-005 | Block: performance | Success rate < 85% at any checkpoint → BLOCKED |
+| TP-006 | Block: inactivity30 | Inactive > 30 days → BLOCKED |
+| TP-007 | Decay: inactivity90 | Inactive > 90 days → full trust decay to 0.0 |
+| TP-008 | No auto-unblock | BLOCKED skills require manual review to reinstate |
+
+---
+
+## 5. Team Collaboration Rules
+
+### Debate Protocol
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| TC-001 | Max rounds | Maximum 3 debate rounds between Executor and Reviewer |
+| TC-002 | Arbitration | After 3 rounds, Tech Lead makes final binding decision |
+| TC-003 | Evidence required | FAIL reviews must include specific evidence/reasoning |
+| TC-004 | Auto-FAIL | "Disagree without proof" → automatic FAIL of the review itself |
+| TC-005 | Consensus stamp | Every team deliverable requires consensus stamp before release |
+
+### Mailbox Protocol
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| TC-006 | Message types | TASK_ASSIGNMENT, SUBMISSION, REVIEW only |
+| TC-007 | Ordered flow | TASK_ASSIGNMENT → SUBMISSION → REVIEW → (loop or release) |
+| TC-008 | Channel isolation | Team agents communicate only through Mailbox — no side channels |
+| TC-009 | Tech Lead authority | Tech Lead has final authority after discussion exhaustion |
+
+---
+
+## 6. Error Classification Rules
+
+### Tier Definitions
+
+| Tier | Name | Strategy | Attempts | Escalates To |
+|------|------|----------|----------|-------------|
+| E1 | Retry | Re-execute identical operation | 3 | E1b |
+| E1b | Chunk | Break into smaller units, retry each | 1 | E2 |
+| E2 | Alternative | Entirely different approach | 1 | E3 |
+| E3 | Safe Point | Save progress to recoverable state | 1 | E4 |
+| E4 | Rollback | Revert + user escalation | 1 | User decision |
+
+### Error Recovery Rules
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| ER-001 | Graduated escalation | E1 → E1b → E2 → E3 → E4, in order — no skipping |
+| ER-002 | No silent failure | Every error path must terminate in success or explicit user decision (Law 9) |
+| ER-003 | Context preservation | Error recovery preserves all deliverables from completed phases |
+| ER-004 | Cascading prevention | E4 stops error propagation to prevent cascading failures |
+| ER-005 | User agency | After E4, user gets full context and options: retry, accept partial, abort |
+| ER-006 | Rollback integrity | E4 rollback restores to last known good state — partial rollback not permitted |
+
+---
+
+## 7. Command Routing Rules
+
+| Rule ID | Rule | Description |
+|---------|------|-------------|
+| CR-001 | Explicit commands | `/{cmd}` or `/{cmd}:{variant}` → direct route to `commands/{cmd}/{variant}.md` |
+| CR-002 | Natural language | NL input → mapped to closest command (implement→/cook, fix/bug→/fix, plan→/plan) |
+| CR-003 | Default variant | No variant specified → use default (base) variant |
+| CR-004 | Team routing | `:team` variant → route to BW-008 (Golden Triangle) |
+| CR-005 | Unknown command | Unrecognized input → attempt NL mapping → still unknown → ASK user |
+
+---
+
+## 8. Exception Catalog
+
+| Exception ID | Workflow | Trigger | Handling | Severity |
+|-------------|----------|---------|----------|----------|
+| EX-001 | BW-001 | Node.js < 18 | Error message + exit 1 | Blocking |
+| EX-002 | BW-001 | Invalid tool name | "Unknown tool" + exit 1 | Blocking |
+| EX-003 | BW-001 | Directory creation failure | Report error + exit 1 | Blocking |
+| EX-004 | BW-002 | Installation not found | Skip with info message | Non-blocking |
+| EX-005 | BW-003 | Ambiguous requirement | PAUSE + ASK user (Law 2) | Blocking (waiting) |
+| EX-006 | BW-003 | Exit criteria not met | Invoke BW-010 | Escalating |
+| EX-007 | BW-003 | Unknown command/NL | ASK user for clarification | Blocking (waiting) |
+| EX-008 | BW-004 | runSubagent failure | Fall back to TIER 2 + log | Non-blocking |
+| EX-009 | BW-005 | Network timeout | Matrix-only fallback | Degraded |
+| EX-010 | BW-005 | No matching skills | Report gap to Orchestrator | Informational |
+| EX-011 | BW-006 | Discovery timeout (5s) | Matrix-only fallback | Degraded |
+| EX-012 | BW-006 | Install failure | Rollback + offer matrix | Recoverable |
+| EX-013 | BW-006 | User declines skill | Matrix-only | Non-blocking |
+| EX-014 | BW-007 | Success rate < 85% | Skill → BLOCKED | Automatic |
+| EX-015 | BW-007 | Inactive > 30d | Skill → BLOCKED | Automatic |
+| EX-016 | BW-008 | 3 rounds exhausted | Tech Lead arbitrates | Escalating |
+| EX-017 | BW-008 | FAIL without evidence | Auto-FAIL the review | Automatic |
+| EX-018 | BW-009 | Layer incomplete | FAILED status, halt | Blocking |
+| EX-019 | BW-010 | E4 rollback fails | User escalation immediate | Critical |
+| EX-020 | BW-011 | Invalid plan file | Fall back to standard BW-003 | Non-blocking |
+| EX-021 | BW-012 | Convention deviation | Design review required | Blocking |
+
+---
+
+## 9. Rule Precedence
+
+When rules conflict, precedence follows this hierarchy (highest first):
+
+1. **Safety**: Error recovery and no-silent-failure guarantee (ER-002)
+2. **Orchestration Laws**: L1–L10 are absolute and non-negotiable
+3. **Phase Sequencing**: PS-001 through PS-007
+4. **Tiered Execution**: TE-001 through TE-005
+5. **HSOL Thresholds**: HS-001 through HS-008
+6. **Team Protocol**: TC-001 through TC-009
+7. **Command Routing**: CR-001 through CR-005
+
+---
+
+## Evidence Sources
+
+- `rules/CORE.md` — 10 Orchestration Laws (L1–L10)
+- `rules/AGENTS.md` — TIER 1/TIER 2 execution rules, sub-agent protocol
+- `rules/PHASES.md` — Phase sequencing, exit criteria, immutability
+- `rules/SKILLS.md` — HSOL fitness algorithm, threshold bands, trust state machine, dynamic discovery
+- `rules/TEAMS.md` — Golden Triangle protocol, debate rounds, Mailbox, consensus stamps
+- `rules/ERRORS.md` — E1–E4 error tiers, graduated escalation, no-silent-halt
+- `CLAUDE.md` — Orchestrator prohibitions, command routing
+- `commands/*.md` — Command and variant definitions
+- `cli/install.js` — CLI error handling and validation

package/documents/business/business-workflows/05-sla-and-handoffs.md

@@ -0,0 +1,253 @@
+# Agent Assistant — SLA & Handoffs
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Define timing expectations, handoff contracts between actors, and SLA/SLO context for all business workflows |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## 1. Timing Expectations by Workflow
+
+### System-Controlled Operations
+
+| Workflow | Operation | Target Time | Tolerance | Notes |
+|----------|-----------|-------------|-----------|-------|
+| BW-001 | Full installation (single tool) | < 15s | 30s max | File copy + placeholder replacement |
+| BW-001 | Full installation (--all, 5 tools) | < 30s | 60s max | Sequential per-tool |
+| BW-002 | Uninstallation (single tool) | < 10s | 20s max | File removal + cleanup |
+| BW-002 | Uninstallation (--all) | < 20s | 40s max | Sequential per-tool |
+| BW-003 | Command routing + variant resolution | < 5s | 10s max | Pre-flight + file load |
+| BW-005 | Matrix-only skill resolution (≥0.8) | < 2s | 5s max | YAML parse + scoring |
+| BW-005 | Matrix + async discovery (0.75–0.8) | < 2s sync | 5s async cap | Matrix immediate; discovery background |
+| BW-006 | Dynamic skill discovery | ≤ 5s | Hard timeout | `npx skills find` enforced ceiling |
+| BW-006 | Skill installation | < 10s | 15s max | `npx skills add` |
+
+### AI-Dependent Operations
+
+These timings depend on the AI model's inference speed and context window. They represent best-effort targets, not enforced SLAs.
+
+| Workflow | Operation | Expected Range | Bounded By |
+|----------|-----------|---------------|------------|
+| BW-003 | Single phase execution | 5s – 60s | Model inference + tool execution |
+| BW-003 | Full command (simple variant) | 30s – 5min | Phase count × phase time |
+| BW-003 | Full command (hard/team variant) | 2min – 30min | Research + implementation complexity |
+| BW-004 | Agent delegation (TIER 1) | 5s – 30s per phase | Sub-agent spawn + execution |
+| BW-004 | Agent delegation (TIER 2) | 3s – 20s per phase | No spawn overhead |
+| BW-008 | Team collaboration (full cycle) | 5min – 45min | 1–3 debate rounds × 3 agents |
+| BW-009 | Documentation generation (full) | 10min – 60min | 13 folders sequential |
+| BW-010 | Error recovery (E1) | 5s – 30s per retry | Up to 3 retries |
+| BW-010 | Error recovery (full E1–E4) | 30s – 10min | Graduated escalation |
+
+---
+
+## 2. Handoff Contracts
+
+### 2.1 User → Orchestrator
+
+| Contract ID | HC-001 |
+|-------------|--------|
+| **From** | Framework User |
+| **To** | AI Model (Orchestrator) |
+| **Trigger** | User types command or natural language instruction |
+| **Payload** | Command text, optional file references, conversation context |
+| **Required** | Actionable intent (explicit command or mappable NL) |
+| **Acknowledgment** | Orchestrator begins pre-flight within 5s |
+| **Failure Mode** | Unrecognizable intent → Orchestrator ASKs for clarification |
+
+---
+
+### 2.2 Orchestrator → Agent (Phase Delegation)
+
+| Contract ID | HC-002 |
+|-------------|--------|
+| **From** | AI Model (Orchestrator) |
+| **To** | Specialist Agent (any of 21 agents) |
+| **Trigger** | Phase N begins execution |
+| **Payload** | Phase definition, exit criteria, prior phase deliverables (read-only), skill set (from BW-005) |
+| **Required** | Agent definition loaded, TIER selected, context scoped |
+| **Deliverable** | Phase output matching exit criteria format |
+| **Acknowledgment** | Agent confirms receipt and begins execution |
+| **Failure Mode** | TIER 1 failure → fallback to TIER 2; deliverable missing → BW-010 |
+
+---
+
+### 2.3 Agent → Orchestrator (Phase Completion)
+
+| Contract ID | HC-003 |
+|-------------|--------|
+| **From** | Specialist Agent |
+| **To** | AI Model (Orchestrator) |
+| **Trigger** | Agent completes phase work |
+| **Payload** | Phase deliverable (code, analysis, plan, etc.) |
+| **Required** | Deliverable must match exit criteria defined in phase spec |
+| **Verification** | Orchestrator verifies exit criteria before accepting |
+| **Failure Mode** | Exit criteria not met → BW-010 error recovery |
+
+---
+
+### 2.4 Orchestrator → Tech Lead (Team Init)
+
+| Contract ID | HC-004 |
+|-------------|--------|
+| **From** | AI Model (Orchestrator) |
+| **To** | Tech Lead (Team Agent) |
+| **Trigger** | `:team` variant command received |
+| **Payload** | Full task description, constraints, quality requirements |
+| **Required** | Task must be decomposable into assignable units |
+| **Deliverable** | TASK_ASSIGNMENT message posted to Mailbox |
+| **Timing** | Assignment within first phase cycle |
+| **Failure Mode** | Undecomposable task → escalate to user |
+
+---
+
+### 2.5 Tech Lead → Executor (via Mailbox)
+
+| Contract ID | HC-005 |
+|-------------|--------|
+| **From** | Tech Lead |
+| **To** | Executor (domain-specific agent) |
+| **Channel** | Mailbox (TASK_ASSIGNMENT message) |
+| **Payload** | Task decomposition, acceptance criteria, constraints, skill context |
+| **Required** | Clear, implementable task units with measurable criteria |
+| **Deliverable** | SUBMISSION message to Mailbox |
+| **Failure Mode** | Unclear assignment → Executor requests clarification via Mailbox |
+
+---
+
+### 2.6 Executor → Reviewer (via Mailbox)
+
+| Contract ID | HC-006 |
+|-------------|--------|
+| **From** | Executor |
+| **To** | Reviewer |
+| **Channel** | Mailbox (SUBMISSION message) |
+| **Payload** | Implementation output, reference to TASK_ASSIGNMENT |
+| **Required** | Complete implementation addressing all assignment criteria |
+| **Deliverable** | REVIEW message (PASS or FAIL with evidence) |
+| **Failure Mode** | Incomplete submission → Reviewer issues FAIL with specifics |
+
+---
+
+### 2.7 Reviewer → Executor (Debate Loop)
+
+| Contract ID | HC-007 |
+|-------------|--------|
+| **From** | Reviewer |
+| **To** | Executor |
+| **Channel** | Mailbox (REVIEW message with FAIL status) |
+| **Payload** | Specific critique with evidence |
+| **Required** | Evidence-based FAIL (no "disagree without proof") |
+| **Deliverable** | Revised SUBMISSION from Executor |
+| **Max Rounds** | 3 |
+| **Failure Mode** | Round 3 exhausted → Tech Lead arbitration (HC-008) |
+
+---
+
+### 2.8 Tech Lead Arbitration
+
+| Contract ID | HC-008 |
+|-------------|--------|
+| **From** | Orchestrator |
+| **To** | Tech Lead |
+| **Trigger** | 3 debate rounds exhausted without consensus |
+| **Payload** | Full debate history (all SUBMISSIONs and REVIEWs) |
+| **Deliverable** | Final binding decision + consensus stamp |
+| **Required** | Decision must reference debate evidence |
+| **Failure Mode** | None — Tech Lead decision is terminal for the team cycle |
+
+---
+
+### 2.9 HSOL → Agent (Skill Delivery)
+
+| Contract ID | HC-009 |
+|-------------|--------|
+| **From** | HSOL System |
+| **To** | Agent (via Orchestrator) |
+| **Trigger** | BW-005 completes skill resolution |
+| **Payload** | Sorted skill set with fitness scores |
+| **Required** | At least one skill, or explicit gap report |
+| **Timing** | ≤ 2s for matrix-only; ≤ 5s if discovery involved |
+| **Failure Mode** | No skills → gap report; timeout → matrix fallback |
+
+---
+
+### 2.10 Orchestrator → User (Error Escalation)
+
+| Contract ID | HC-010 |
+|-------------|--------|
+| **From** | AI Model (Orchestrator) |
+| **To** | Framework User |
+| **Trigger** | E4 reached or unrecoverable error |
+| **Payload** | Error context, completed deliverables, options (retry/accept/abort) |
+| **Required** | Full transparency — no hidden state |
+| **Deliverable** | User's explicit decision |
+| **Failure Mode** | None — user decision is always terminal |
+
+---
+
+## 3. SLA/SLO Summary
+
+### Enforced SLAs (System-Controlled)
+
+| ID | Metric | Target | Enforcement |
+|----|--------|--------|-------------|
+| SLA-001 | CLI install time (single) | < 30s | Hard timeout in install.js |
+| SLA-002 | HSOL discovery timeout | ≤ 5s | Hard timeout in discovery logic |
+| SLA-003 | Error: no silent failure | 100% | Law 9 — every error surfaces |
+| SLA-004 | TIER 1 preference | 100% when available | Law 6 — TIER 2 only as fallback |
+| SLA-005 | Phase ordering | 100% sequential | Law 4 — no skip, no reorder |
+| SLA-006 | Deliverable immutability | 100% | Law 8 — prior outputs read-only |
+
+### Best-Effort SLOs (AI-Dependent)
+
+| ID | Metric | Target | Measurement |
+|----|--------|--------|-------------|
+| SLO-001 | Command routing latency | < 5s | Time from input to first phase start |
+| SLO-002 | Simple command completion | < 5 min | End-to-end for easy/default variants |
+| SLO-003 | Team workflow completion | < 45 min | Full Golden Triangle cycle |
+| SLO-004 | Error recovery success | > 80% | Recovered before E3 stage |
+| SLO-005 | HSOL matrix-only resolution rate | > 70% | Commands resolved without discovery |
+| SLO-006 | Doc generation (full) | < 60 min | All 13 folders generated |
+
+### Trust SLOs (HSOL-Specific)
+
+| ID | Metric | Target | Period |
+|----|--------|--------|--------|
+| SLO-007 | NEW → EVALUATING promotion | ≤ 3 task cycles | Per dynamic skill |
+| SLO-008 | EVALUATING → VALIDATED promotion | ≤ 10 task cycles | Per dynamic skill |
+| SLO-009 | Skill success rate threshold | ≥ 85% | Rolling per skill |
+| SLO-010 | Inactivity detection | ≤ 30 days | Automatic BLOCKED transition |
+
+---
+
+## 4. Handoff Flow Summary
+
+```mermaid
+flowchart LR
+    U[User] -->|HC-001: Command| O[Orchestrator]
+    O -->|HC-002: Phase delegation| A[Agent]
+    A -->|HC-003: Deliverable| O
+    O -->|HC-004: Team init| TL[Tech Lead]
+    TL -->|HC-005: Assignment| EX[Executor]
+    EX -->|HC-006: Submission| RV[Reviewer]
+    RV -->|HC-007: Review/FAIL| EX
+    O -->|HC-008: Arbitration| TL
+    HSOL[HSOL System] -->|HC-009: Skills| A
+    O -->|HC-010: Error escalation| U
+```
+
+---
+
+## Evidence Sources
+
+- `cli/install.js` — Installation timing characteristics, error exit codes
+- `rules/CORE.md` — Orchestration Laws L4 (phase order), L6 (TIER 1 preference), L8 (immutability), L9 (no silent failure)
+- `rules/AGENTS.md` — TIER 1/TIER 2 handoff protocol, sub-agent context scoping
+- `rules/SKILLS.md` — HSOL timing (5s discovery cap), fitness band routing, trust progression timelines
+- `rules/TEAMS.md` — Golden Triangle Mailbox protocol, message types, debate round limits
+- `rules/ERRORS.md` — E1–E4 escalation path, user escalation terminal guarantee
+- `rules/PHASES.md` — Exit criteria verification as handoff gate
+- `CLAUDE.md` — Orchestrator behavioral constraints

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

@@ -0,0 +1,159 @@
+# Knowledge Architecture
+
+> **Purpose**: Architecture summary, table of contents, and cross-references for the Agent Assistant framework architecture
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Quick Summary
+
+Agent Assistant is a **plugin-based orchestrator framework** where the AI model itself is the runtime. Rather than shipping executable code, the framework distributes Markdown and YAML instruction files that AI coding assistants read and follow as their operating protocol. The architecture centers on a single Orchestrator (defined in platform entry points) that delegates work to 21 specialist agents through 14 command routers, governed by 10 immutable orchestration laws and a Hybrid Skill Orchestration Layer (HSOL) that resolves and injects 1,430 skills across 19 domains.
+
+The system deploys identically to 5 platforms (Cursor, GitHub Copilot, Claude Code, Codex, Antigravity/Gemini) through a CLI installer that performs `{TOOL}` placeholder substitution. At runtime, the AI reads CORE.md as its operating system, loads rules on demand, routes user commands to workflow variants, and executes phase-sequential pipelines where each phase delegates to a specialist agent via tiered execution (sub-agent isolation preferred, shared-context embodiment as fallback). For high-stakes work, the `:team` variant activates a Golden Triangle of 3 agents (Tech Lead + Executor + Reviewer) with adversarial debate capped at 3 rounds.
+
+```mermaid
+graph TB
+    subgraph "Platform Layer"
+        CLAUDE["CLAUDE.md"]
+        COPILOT["COPILOT.md"]
+        CURSOR["CURSOR.md"]
+        CODEX["CODEX.md"]
+        GEMINI["GEMINI.md"]
+    end
+
+    subgraph "Orchestrator Core"
+        CORE["CORE.md<br/>Identity + 10 Laws"]
+        RULES["Rules Engine"]
+    end
+
+    subgraph "Command Layer"
+        ROUTER["14 Command Routers"]
+        VARIANTS["54 Workflow Variants<br/>(fast, hard, team)"]
+    end
+
+    subgraph "Agent Layer"
+        AGENTS["21 Individual Agents"]
+        TEAMS["17 Teams × 3 Roles<br/>(Golden Triangle)"]
+    end
+
+    subgraph "Skill Layer"
+        MATRIX["Matrix Skills<br/>19 Domains · 1,430 Skills"]
+        DYNAMIC["Dynamic Skills<br/>Community Discovery"]
+        HSOL["HSOL Engine<br/>Fitness Scoring"]
+    end
+
+    subgraph "Distribution"
+        CLI["CLI Installer<br/>cli/install.js"]
+        PKG["npm Package<br/>@namch/agent-assistant"]
+    end
+
+    CLAUDE & COPILOT & CURSOR & CODEX & GEMINI --> CORE
+    CORE --> RULES
+    CORE --> ROUTER
+    ROUTER --> VARIANTS
+    VARIANTS --> AGENTS
+    VARIANTS --> TEAMS
+    AGENTS --> HSOL
+    HSOL --> MATRIX
+    HSOL --> DYNAMIC
+    PKG --> CLI
+    CLI -->|"{TOOL} replacement"| CLAUDE & COPILOT & CURSOR & CODEX & GEMINI
+```
+
+---
+
+## Table of Contents
+
+1. [Quick Summary](#quick-summary)
+2. [Sub-Files](#sub-files)
+3. [Quick Facts](#quick-facts)
+4. [Cross-References](#cross-references)
+5. [Known Gaps and Open Questions](#known-gaps-and-open-questions)
+
+---
+
+## Sub-Files
+
+| # | File | Description |
+|---|------|-------------|
+| 1 | [01-system-overview.md](./01-system-overview.md) | High-level architecture diagram, architecture style, layer boundaries, and key design decisions table |
+| 2 | [02-components.md](./02-components.md) | Per-component breakdown — Orchestrator, Agents, Commands, Rules, Matrix Skills, Skills, CLI, Code Assistants, Web, Platform Entry Points |
+| 3 | [03-data-flow.md](./03-data-flow.md) | Request lifecycle, CLI install flow, skill resolution flow, and Golden Triangle team flow — all with Mermaid diagrams |
+| 4 | [04-design-patterns.md](./04-design-patterns.md) | 11 observed architectural patterns with descriptions, locations, rationale, and code references |
+| 5 | [05-decisions.md](./05-decisions.md) | Architecture Decision Records (ADRs) — 7 key decisions with choices, alternatives, rationale, and trade-offs |
+
+---
+
+## Quick Facts
+
+| Key | Value |
+|-----|-------|
+| Architecture Style | Plugin-based Orchestrator Framework |
+| Runtime Model | AI model reads Markdown/YAML instructions (no traditional server) |
+| Core Governance | 10 Orchestration Laws (CORE.md v4.1) |
+| Platform Entry Points | 5 (CLAUDE.md, COPILOT.md, CURSOR.md, CODEX.md, GEMINI.md) |
+| Rule Files | 7 (CORE, PHASES, AGENTS, SKILLS, TEAMS, ERRORS, REFERENCE) |
+| Command Routers | 14 |
+| Workflow Variants | 4 per command (fast, hard, team) |
+| Individual Agents | 21 across 5 categories (meta, execution, validation, research, support) |
+| Team Configurations | 17 teams × 3 roles = 51 team agents |
+| Skill Modules | 1,430 matrix + dynamic community skills |
+| Skill Domains | 19 YAML domain files |
+| Error Classes | 5 (E1, E1b, E2, E3, E4) |
+| Execution Tiers | 2 (sub-agent isolation, shared-context embodiment) |
+| Debate Rounds (Team) | Max 3, then Tech Lead arbitration |
+| Production Dependencies | 0 |
+
+---
+
+## Cross-References
+
+| Resource | Path | Relationship |
+|----------|------|-------------|
+| Knowledge Overview | [../knowledge-overview/00-index.md](../knowledge-overview/00-index.md) | Project-level overview, quick facts, and getting started |
+| Knowledge Source Base | [../knowledge-source-base/00-index.md](../knowledge-source-base/00-index.md) | Directory structure, entry points, key modules, and configuration |
+| HSOL Assessment | [../HSOL-ASSESSMENT.md](../HSOL-ASSESSMENT.md) | Detailed evaluation of the Hybrid Skill Orchestration Layer |
+| SMART Skill Orchestration | [../SMART-SKILL-ORCHESTRATION-BLUEPRINT.md](../SMART-SKILL-ORCHESTRATION-BLUEPRINT.md) | Blueprint for skill orchestration design |
+| Core Rules | [../../rules/CORE.md](../../rules/CORE.md) | Orchestrator protocol, 10 laws, tiered execution |
+| Phase Rules | [../../rules/PHASES.md](../../rules/PHASES.md) | Phase output format, requirements registry |
+| Agent Rules | [../../rules/AGENTS.md](../../rules/AGENTS.md) | Tiered execution protocol, agent categories |
+| Skills Rules | [../../rules/SKILLS.md](../../rules/SKILLS.md) | HSOL resolution algorithm, fitness calculation |
+| Teams Rules | [../../rules/TEAMS.md](../../rules/TEAMS.md) | Golden Triangle protocol, debate mechanism |
+| Error Rules | [../../rules/ERRORS.md](../../rules/ERRORS.md) | Error classification and recovery protocols |
+| Reference Rules | [../../rules/REFERENCE.md](../../rules/REFERENCE.md) | Command table, agent table, deliverable paths |
+| Matrix Skills Index | [../../matrix-skills/_index.yaml](../../matrix-skills/_index.yaml) | HSOL configuration, domain registry |
+| Package Manifest | [../../package.json](../../package.json) | npm metadata, scripts, platform install commands |
+| CLI Installer | [../../cli/install.js](../../cli/install.js) | Platform installation logic and `{TOOL}` replacement |
+
+---
+
+## Known Gaps and Open Questions
+
+| # | Gap | Impact | Notes |
+|---|-----|--------|-------|
+| 1 | No formal interface contracts between agents — handoff semantics are implied by Markdown conventions | Medium | Agent `handoffs` field in YAML frontmatter lists targets but does not define data schemas |
+| 2 | HSOL fitness scoring is declarative (defined in SKILLS.md and _index.yaml) but has no executable implementation to verify | Medium | The AI model interprets the algorithm; no unit-testable code exists |
+| 3 | Mailbox append-only guarantee relies on AI compliance, not filesystem enforcement | Low | TEAMS.md declares `C8-TEAMS-01` checkpoint but it is a behavioral contract |
+| 4 | Dynamic skill trust progression (0.3 → 1.0) lacks persistent state across sessions | Medium | Promotion criteria defined in SKILLS.md but no storage mechanism is documented |
+| 5 | Platform-specific behavior differences are not documented — the `{TOOL}` replacement is path-only, but AI model capabilities vary across platforms | Low | Sub-agent availability (TIER 1) is platform-dependent per AGENTS.md |
+| 6 | Web application architecture (web/) is not covered in this folder — it is an independent sub-project | Low | Tracked separately from the core framework architecture |
+
+---
+
+## Evidence Sources
+
+| Source | Path | What It Provides |
+|--------|------|------------------|
+| CORE.md | `rules/CORE.md` | Identity, paths, command routing, tiered execution, 10 laws, prohibitions |
+| PHASES.md | `rules/PHASES.md` | Phase output format, requirements registry, Golden Triangle phase format |
+| AGENTS.md | `rules/AGENTS.md` | Tiered execution protocol, tool discovery, agent categories, completion guarantee |
+| SKILLS.md | `rules/SKILLS.md` | HSOL overview, resolution algorithm, fitness calculation, trust progression |
+| TEAMS.md | `rules/TEAMS.md` | Golden Triangle roles, debate mechanism, mailbox communication, C8 checkpoints |
+| ERRORS.md | `rules/ERRORS.md` | Error classification (E1–E4), recovery protocol, anti-patterns (A1–A10) |
+| REFERENCE.md | `rules/REFERENCE.md` | Command table, agent table, natural language detection, deliverable paths |
+| _index.yaml | `matrix-skills/_index.yaml` | HSOL configuration, domain registry, discovery settings |
+| package.json | `package.json` | Version, scripts, dependencies, platforms, engine requirements |
+| cli/install.js | `cli/install.js` | Platform configuration, path mappings, `{TOOL}` replacement tables |
+| Agent files | `agents/*.md` | YAML frontmatter (profile, handoffs), cognitive anchor, skill injection |
+| Command files | `commands/*.md` | Router directives, routing logic, variant tables |