@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/knowledge-architecture/03-data-flow.md

@@ -0,0 +1,368 @@
+# Agent Assistant — Data Flow
+
+> **Purpose**: Request lifecycle, CLI install flow, skill resolution flow, and Golden Triangle team flow — all with Mermaid diagrams
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [User Command Lifecycle](#user-command-lifecycle)
+2. [CLI Install Flow](#cli-install-flow)
+3. [Skill Resolution Flow (HSOL)](#skill-resolution-flow-hsol)
+4. [Golden Triangle Team Flow](#golden-triangle-team-flow)
+5. [Error Recovery Flow](#error-recovery-flow)
+6. [Evidence Sources](#evidence-sources)
+
+---
+
+## User Command Lifecycle
+
+This is the primary data flow — from a user typing a prompt to receiving a structured deliverable. The orchestrator detects the command, routes to a variant, then executes phases sequentially, delegating each phase to a specialist agent.
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant EP as Platform Entry Point
+    participant ORC as Orchestrator (CORE.md)
+    participant R as Command Router
+    participant V as Variant Workflow
+    participant A as Agent (TIER 1 or 2)
+    participant S as Skill Layer (HSOL)
+
+    U->>EP: User prompt or /command
+    EP->>ORC: Load CORE.md (identity + laws)
+    
+    Note over ORC: DETECT command<br/>(explicit or NLP mapping)
+    ORC->>ORC: Load PHASES.md + AGENTS.md
+    ORC->>R: Route to commands/{cmd}.md
+    
+    Note over R: Parse $ARGUMENTS<br/>Assess complexity
+    R->>V: Route to commands/{cmd}/{variant}.md
+    
+    Note over V: PRE-FLIGHT complete<br/>Begin phase execution
+
+    loop For each Phase N
+        V->>ORC: Phase N assignment
+        ORC->>ORC: Parse requirements into Registry
+        
+        alt TIER 1 available
+            ORC->>A: runSubagent(agent, context)
+            Note over A: Isolated context
+        else TIER 2 fallback
+            ORC->>ORC: EMBODY agent
+            Note over ORC: Shared context<br/>Read agent file completely
+        end
+        
+        A->>S: Request skill injection (profile-based)
+        S->>A: Return matched skills (fitness ≥ threshold)
+        A->>A: Execute phase work
+        A->>ORC: Return deliverable
+        
+        Note over ORC: VERIFY exit criteria<br/>Mark phase complete<br/>Deliverable becomes immutable (L8)
+    end
+
+    ORC->>U: Deliver final result
+```
+
+### Key Data at Each Stage
+
+| Stage | Data Flowing | Format |
+|-------|-------------|--------|
+| User → Entry Point | Natural language or `/command:variant args` | Free text |
+| Entry Point → Orchestrator | Identity binding + path configuration | CORE.md loaded into context |
+| Orchestrator → Router | Command name + arguments | Mapped via REFERENCE.md table |
+| Router → Variant | Complexity assessment + user arguments | Redirect to variant file |
+| Variant → Orchestrator | Phase assignment (agent name, task, criteria) | Phase definition in variant file |
+| Orchestrator → Agent | Requirements registry, task description, acceptance criteria, constraints | Structured handoff context |
+| Agent → Skill Layer | Agent profile from YAML frontmatter (e.g., `backend:execution`) | Profile string |
+| Skill Layer → Agent | Matched SKILL.md contents sorted by fitness score | Markdown content |
+| Agent → Orchestrator | Completed deliverable | Per PHASES.md output format |
+| Orchestrator → User | Final result (all phases composed) | Markdown with phase sections |
+
+---
+
+## CLI Install Flow
+
+The CLI installer is the distribution mechanism — it copies framework files from the npm package to each platform's global directory, performing placeholder substitution on every Markdown and YAML file.
+
+```mermaid
+flowchart TD
+    START["npm install @namch/agent-assistant<br/>or npx agent-assistant install {tool}"]
+    
+    PARSE["Parse CLI arguments<br/>install | uninstall | list"]
+    RESOLVE["Resolve target platform(s)<br/>cursor | copilot | antigravity | codex | --all"]
+    
+    subgraph "Per Platform"
+        DIRS["Create directory structure<br/>~/.{tool}/skills/agent-assistant/"]
+        
+        subgraph "Copy Loop (all framework files)"
+            READ["Read source file from npm package"]
+            REPLACE["Apply {TOOL} replacements:<br/>~/.{TOOL}/skills/ → ~/.cursor/skills/<br/>{TOOL} → cursor<br/>{HOME} → ~"]
+            WRITE["Write transformed file to target"]
+            SYNC["fs.sync for reliability"]
+        end
+        
+        ASSETS["Copy platform-specific assets<br/>from code-assistants/{tool}-assistant/"]
+        VERIFY["Verification phase<br/>Check all files written"]
+        REPORT["Summary report with statistics"]
+    end
+
+    START --> PARSE --> RESOLVE
+    RESOLVE --> DIRS
+    DIRS --> READ --> REPLACE --> WRITE --> SYNC
+    SYNC -->|"Next file"| READ
+    SYNC -->|"All files done"| ASSETS
+    ASSETS --> VERIFY --> REPORT
+```
+
+### Files Distributed per Platform
+
+| Category | Source Path | Destination |
+|----------|-----------|-------------|
+| Rules | `rules/*.md` | `~/.{tool}/skills/agent-assistant/rules/` |
+| Agents | `agents/*.md` | `~/.{tool}/skills/agent-assistant/agents/` |
+| Team Agents | `agents/teams/*/` | `~/.{tool}/skills/agent-assistant/agents/teams/` |
+| Commands | `commands/**/*.md` | `~/.{tool}/skills/agent-assistant/commands/` |
+| Matrix Skills | `matrix-skills/*.yaml` | `~/.{tool}/skills/agent-assistant/matrix-skills/` |
+| Skills | `skills/*/SKILL.md` | `~/.{tool}/skills/*/SKILL.md` (at skills root) |
+| Documents | `documents/**` | `~/.{tool}/skills/agent-assistant/documents/` |
+| Platform Assets | `code-assistants/{tool}-assistant/` | Platform-specific locations (varies) |
+
+### Replacement Table (from cli/install.js)
+
+All `.md` and `.yaml` files undergo text replacement. The replacement map is platform-specific:
+
+| Placeholder | Cursor | Copilot | Codex |
+|------------|--------|---------|-------|
+| `{TOOL}` | `cursor` | `copilot` | `codex` |
+| `~/.{TOOL}/skills/agent-assistant/` | `~/.cursor/skills/agent-assistant/` | `~/.copilot/skills/agent-assistant/` | `~/.codex/skills/agent-assistant/` |
+| `{HOME}` | `~` | `~` | `~` |
+
+---
+
+## Skill Resolution Flow (HSOL)
+
+The Hybrid Skill Orchestration Layer resolves domain skills for an agent based on their profile, applies a 5-factor fitness score, and either uses matrix skills directly or triggers community discovery for gaps.
+
+```mermaid
+flowchart TD
+    TRIGGER["Agent delegated for phase<br/>Profile: backend:execution"]
+    
+    ASSESS["Assess task complexity<br/>Simple or Complex?"]
+    
+    SIMPLE["Simple → Skip skill resolution<br/>Use base knowledge"]
+    
+    PARSE["Parse agent profile<br/>from YAML frontmatter"]
+    LOAD["Load inherited domains<br/>from _index.yaml"]
+    FILTER["Filter skills by relevance_mapping<br/>from domain YAML files"]
+    
+    SCORE["Calculate fitness score per skill:<br/>0.35 × Semantic Match<br/>+ 0.25 × Specificity<br/>+ 0.20 × Trust Level<br/>+ 0.10 × Freshness<br/>+ 0.10 × Success Rate"]
+    
+    THRESHOLD{{"Fitness ≥ 0.8?"}}
+    ASYNC{{"Fitness 0.75–0.8?"}}
+    
+    USE["Execute with matrix skills<br/>(skip discovery)"]
+    RECOMMEND["Execute with matrix skills<br/>+ surface recommendation later"]
+    
+    DISCOVER["BLOCKING: Run dynamic discovery<br/>npx skills find [query]"]
+    INSTALL["Install discovered skill<br/>npx skills add owner/repo@skill"]
+    
+    TRUST["Apply trust level:<br/>Matrix = 1.0 (always trusted)<br/>Dynamic = 0.3 (new) → 1.0 (promoted)"]
+    
+    INJECT["Inject skill SKILL.md content<br/>into agent context"]
+
+    TRIGGER --> ASSESS
+    ASSESS -->|"Simple"| SIMPLE
+    ASSESS -->|"Complex"| PARSE
+    PARSE --> LOAD --> FILTER --> SCORE
+    SCORE --> THRESHOLD
+    THRESHOLD -->|"≥ 0.8"| USE
+    THRESHOLD -->|"< 0.8"| ASYNC
+    ASYNC -->|"0.75–0.8"| RECOMMEND
+    ASYNC -->|"< 0.75"| DISCOVER
+    DISCOVER --> INSTALL --> TRUST
+    TRUST --> INJECT
+    USE --> INJECT
+    RECOMMEND --> INJECT
+```
+
+### Trust Progression Lifecycle (from SKILLS.md)
+
+```mermaid
+stateDiagram-v2
+    [*] --> NEW: Dynamic skill installed
+    NEW --> EVALUATING: 3 successful executions
+    EVALUATING --> VALIDATED: 10 successful executions
+    VALIDATED --> PROMOTED: Auto-promote to matrix
+    PROMOTED --> [*]: Added to matrix-skills YAML
+
+    state NEW {
+        note right of NEW: Trust = 0.3
+    }
+    state EVALUATING {
+        note right of EVALUATING: Trust = 0.5
+    }
+    state VALIDATED {
+        note right of VALIDATED: Trust = 0.7
+    }
+    state PROMOTED {
+        note right of PROMOTED: Trust = 1.0
+    }
+```
+
+### Variant Impact on Discovery (from SKILLS.md)
+
+| Variant | Discovery Behavior |
+|---------|-------------------|
+| `:fast` | Skip — use matrix skills only, no dynamic discovery |
+| `:hard` | Check matrix fitness; trigger discovery if < 0.8 |
+| `:team` | Same as `:hard` — applies per agent in the triangle |
+
+---
+
+## Golden Triangle Team Flow
+
+When a `:team` variant is activated, each phase spawns exactly 3 agents who collaborate through a structured adversarial protocol with file-based communication.
+
+```mermaid
+sequenceDiagram
+    participant ORC as Orchestrator
+    participant TL as Tech Lead
+    participant EX as Executor
+    participant RV as Reviewer
+    participant MB as Mailbox<br/>(append-only file)
+    participant TK as Shared Task List
+
+    ORC->>TL: Phase N assignment (:team variant)
+    
+    Note over TL: Decompose into tasks
+    TL->>TK: Create Shared Task List
+    TL->>MB: TASK_ASSIGNMENT → Executor
+
+    EX->>TK: Read task assignments
+    Note over EX: Implement deliverable
+    EX->>MB: SUBMISSION → Reviewer
+
+    RV->>MB: Read submission
+    Note over RV: Devil's Advocate review<br/>"Assume defects exist"
+    
+    alt PASS
+        RV->>MB: REVIEW (PASS) → All
+        Note over TL,RV: Consensus reached
+    else FAIL (Round 1)
+        RV->>MB: REVIEW (FAIL) → Executor
+        
+        alt Executor agrees
+            EX->>EX: Apply fixes
+            EX->>MB: RESUBMISSION → Reviewer
+        else Executor defends
+            EX->>MB: DEFENSE (with evidence) → Reviewer
+            Note over EX: Must include technical proof<br/>(benchmarks, specs, references)
+        end
+        
+        RV->>MB: Re-review
+        
+        alt PASS
+            RV->>MB: REVIEW (PASS) → All
+        else FAIL (Round 2-3)
+            Note over RV: Loop continues<br/>Max 3 rounds
+        end
+    end
+
+    alt No consensus after 3 rounds
+        RV->>TL: Escalate unresolved dispute
+        TL->>MB: Read ALL exchanges
+        Note over TL: Evaluate evidence quality<br/>Not seniority or role
+        TL->>MB: DECISION (binding) → All
+    end
+
+    Note over TL,RV: CONSENSUS STAMP<br/>TechLead ✓ | Executor ✓ | Reviewer ✓
+    TL->>ORC: Return consensus-stamped deliverable
+```
+
+### Communication Artifacts
+
+| Artifact | Location | Owner | Rules |
+|----------|----------|-------|-------|
+| Shared Task List | Inline in phase output | Tech Lead | Status tracking: assignments, priorities, completion |
+| Mailbox | `./reports/{topic}/MAILBOX-{date}.md` | All agents (append-only) | No edits or deletions; every exchange is logged |
+
+### Message Types in Mailbox
+
+| Type | From → To | Purpose |
+|------|-----------|---------|
+| `TASK_ASSIGNMENT` | Tech Lead → Executor | Assign implementation tasks |
+| `SUBMISSION` | Executor → Reviewer | Submit completed work for review |
+| `REVIEW (PASS)` | Reviewer → All | Approve submission |
+| `REVIEW (FAIL)` | Reviewer → Executor | Reject with specific issues |
+| `DEFENSE` | Executor → Reviewer | Defend work with evidence |
+| `RESUBMISSION` | Executor → Reviewer | Resubmit after fixes |
+| `DECISION` | Tech Lead → All | Binding arbitration (after 3 rounds) |
+
+### C8 Enforcement Checkpoints (from TEAMS.md)
+
+| Checkpoint | Rule | Block Level |
+|-----------|------|-------------|
+| C8-TEAMS-01 | Mailbox is append-only and required for all inter-agent exchanges | BLOCK |
+| C8-TEAMS-02 | Debate capped at 3 rounds; unresolved disputes escalate to Tech Lead | BLOCK |
+| C8-TEAMS-03 | Phase output requires explicit consensus stamp before release | BLOCK |
+
+---
+
+## Error Recovery Flow
+
+When errors occur during any flow above, the framework follows a self-healing protocol with 5 error classes.
+
+```mermaid
+flowchart TD
+    ERROR["Error Detected"]
+    CAPTURE["1. CAPTURE<br/>error type, phase, agent, state"]
+    CLASSIFY["2. CLASSIFY"]
+    
+    E1["E1: Transient<br/>(timeout, network)"]
+    E1B["E1b: Output Overflow<br/>(file too large)"]
+    E2["E2: Recoverable<br/>(logic error)"]
+    E3["E3: Blocking<br/>(critical failure)"]
+    E4["E4: Cascading<br/>(affects downstream)"]
+    
+    RETRY["Retry 3× with backoff"]
+    CHUNK["Switch to chunked<br/>deliverable strategy"]
+    ALT["Attempt alternative<br/>approach"]
+    SAFE["Safe point →<br/>Best option →<br/>Auto-recover"]
+    ROLLBACK["Stop propagation →<br/>Rollback →<br/>Report impact"]
+    
+    RESUME["4. RESUME immediately"]
+    ESCALATE["USER ESCALATION<br/>⚠️ BLOCKED — Decision Required<br/>Options A/B/C/D"]
+
+    ERROR --> CAPTURE --> CLASSIFY
+    CLASSIFY --> E1 --> RETRY --> RESUME
+    CLASSIFY --> E1B --> CHUNK --> RESUME
+    CLASSIFY --> E2 --> ALT --> RESUME
+    CLASSIFY --> E3 --> SAFE --> RESUME
+    CLASSIFY --> E4 --> ROLLBACK --> RESUME
+    
+    RETRY -->|"3 retries failed"| ESCALATE
+    ALT -->|"No alternative"| ESCALATE
+    SAFE -->|"Cannot auto-recover"| ESCALATE
+    ROLLBACK -->|"Rollback failed"| ESCALATE
+```
+
+---
+
+## Evidence Sources
+
+| Source | Path | What It Provides |
+|--------|------|------------------|
+| CORE.md v4.1 | `rules/CORE.md` | Execution loop (5 steps), command routing table, tiered execution, NLP detection |
+| PHASES.md | `rules/PHASES.md` | Requirements intake format, phase output format (standard + GT), exit criteria |
+| AGENTS.md | `rules/AGENTS.md` | TIER 1/TIER 2 handoff protocol, tool discovery, embodiment announcement format |
+| SKILLS.md | `rules/SKILLS.md` | Resolution algorithm (6 steps), fitness formula (5 factors), trust lifecycle (4 stages), variant behavior |
+| TEAMS.md | `rules/TEAMS.md` | Golden Triangle diagram, 3 roles, debate flow, max 3 rounds, defense rules, mailbox protocol, C8 checkpoints |
+| ERRORS.md | `rules/ERRORS.md` | Error classification table (E1–E4), recovery protocol (5 steps), user escalation format |
+| _index.yaml | `matrix-skills/_index.yaml` | HSOL config: async_threshold 0.8, discovery settings, variant apply rules |
+| cli/install.js | `cli/install.js` | Platform TOOLS config, replacement maps, directory creation, file copy logic |
+| package.json | `package.json` | npm scripts for install/uninstall per platform, files array for distribution |
+| REFERENCE.md | `rules/REFERENCE.md` | Deliverable paths per agent, command-variant mappings |