@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-prd/04-acceptance-risks-assumptions.md

@@ -0,0 +1,246 @@
+# Agent Assistant — Acceptance Criteria, Risks, and Assumptions
+
+> **Purpose**: Acceptance criteria for the framework, risk register, assumptions, and open questions
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Acceptance Criteria
+
+### AC-001: Global Installation
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-001, BR-001, BF-001 |
+| **Given** | A clean machine with Node.js 18+ and npm |
+| **When** | User runs `npm install -g @namch/agent-assistant && agent-assistant install --all` |
+| **Then** | Config files exist at all 5 platform directories (`~/.cursor/skills/agent-assistant/`, `~/.copilot/skills/agent-assistant/`, `~/.claude/skills/agent-assistant/`, `~/.codex/skills/agent-assistant/`, `~/.gemini/antigravity/skills/agent-assistant/`) AND exit code is 0 AND total time ≤5 minutes |
+
+### AC-002: Multi-Platform Parity
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-002, BR-002, BF-002 |
+| **Given** | The framework is installed on all 5 platforms |
+| **When** | Each platform's AI tool opens a workspace |
+| **Then** | The platform entry point file is loaded, the Orchestrator pattern activates, and the same 14 commands are available on all platforms |
+
+### AC-003: Orchestrator Delegation
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-003, BG-004, BR-003, BF-003 |
+| **Given** | A loaded orchestrator context on any supported platform |
+| **When** | User types a request (slash command or natural language) |
+| **Then** | The Orchestrator detects the command, loads the workflow, and delegates to the appropriate specialist agent WITHOUT implementing directly. Direct implementation is a law violation (L7). |
+
+### AC-004: Agent Completeness
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-004, BR-004, BF-004 |
+| **Given** | The agents directory |
+| **When** | All 21 agent files are examined |
+| **Then** | Each contains: name, description, profile, category, Thinking Protocol, Constraints, Output Format, and Cognitive Anchor sections. Each agent has a unique profile tag. |
+
+### AC-005: Command Routing
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-006, BR-006, BR-007, BR-015, BF-006, BF-007, BF-015 |
+| **Given** | All 14 commands and their variant subdirectories |
+| **When** | A command is invoked (via slash or NLP detection) |
+| **Then** | The correct workflow file is loaded with PRE-FLIGHT sequence (CORE.md → PHASES.md → AGENTS.md), phases execute sequentially (L5), and variant modifiers route to the correct sub-workflow file |
+
+### AC-006: HSOL Skill Resolution
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-007, BR-008, BF-008 |
+| **Given** | A task requiring domain-specific knowledge |
+| **When** | HSOL resolution runs |
+| **Then** | Agent profile parsed from frontmatter, inherited domains loaded from `_index.yaml`, skills filtered by relevance, fitness score calculated via 5-factor formula (semantic 0.35 + specificity 0.25 + trust 0.20 + freshness 0.10 + success 0.10), and skills with fitness ≥0.8 auto-injected |
+
+### AC-007: Golden Triangle Team Protocol
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-008, BR-005, BR-014, BF-005, BF-014 |
+| **Given** | A `:team` variant is invoked |
+| **When** | Any phase executes |
+| **Then** | Exactly 3 agents spawn (Tech Lead, Executor, Reviewer), Mailbox log is created, debate capped at 3 rounds, unresolved disputes escalate to Tech Lead (binding arbitration), and consensus stamp is required before phase release |
+
+### AC-008: Error Recovery
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-004, BR-013, BF-013 |
+| **Given** | An error occurs during workflow execution |
+| **When** | The error is classified |
+| **Then** | E1 (transient): retry 3× with backoff. E2 (recoverable): alternative approach attempted. E3 (blocking): safe point created, auto-recovery. E4 (cascading): propagation stopped, rollback, user notified. The workflow never halts silently. |
+
+### AC-009: Tiered Execution
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-003, BR-011, BF-011 |
+| **Given** | A delegation request to a specialist agent |
+| **When** | `runSubagent` tool exists |
+| **Then** | TIER 1 (sub-agent) is used. TIER 2 (embody) is forbidden. When `runSubagent` is unavailable, TIER 2 is used with logged reason, and the agent file is read completely before embodiment. |
+
+### AC-010: Documentation Generation
+
+| Attribute | Detail |
+|-----------|--------|
+| **Covers** | BG-010, BR-017, BF-017 |
+| **Given** | User invokes `/docs` on a workspace with source code |
+| **When** | All 3 sub-commands complete sequentially |
+| **Then** | `/docs:core` produces 5 knowledge folders, `/docs:business` produces 4 business folders, `/docs:audit` produces 4 audit folders, all under `./documents/` |
+
+---
+
+## Risk Register
+
+### RISK-001: Unvalidated Performance Claims
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Credibility / Marketing |
+| **Description** | The framework claims 70% faster time-to-production, 70% bug reduction, and 85% token cost savings. No benchmark data, test results, or measurement methodology exists in the repository. |
+| **Probability** | High (claims are currently stated as facts in README and marketing) |
+| **Impact** | High — stakeholders adopt based on expected returns that may not materialize; credibility loss if claims are challenged |
+| **Affected Goals** | BG-003, BG-004, BG-005 |
+| **Affected Requirements** | BR-003, BR-008 |
+| **Mitigation** | Establish a benchmark suite comparing structured (agent-assistant) vs. unstructured prompting on standardized tasks. Reclassify claims as "design targets" until validated. Add disclaimer to README and marketing site. |
+| **Status** | Open — no action taken |
+
+### RISK-002: External Dependency on skills.sh
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Availability / Resilience |
+| **Description** | Dynamic skill discovery (BR-009), trust progression (BR-010), and community ecosystem growth (BG-009) depend on the external skills.sh service and `npx skills` CLI, neither of which is bundled with or controlled by the framework. |
+| **Probability** | Medium — third-party services can become unreachable, deprecated, or change APIs |
+| **Impact** | Medium — dynamic discovery degrades to no-op; matrix skills (1,430) remain functional as fallback |
+| **Affected Goals** | BG-007, BG-009 |
+| **Affected Requirements** | BR-009, BR-010 |
+| **Mitigation** | Document clear fallback behavior when skills.sh is unreachable. Consider implementing a local skill registry cache. HSOL already specifies timeout-and-proceed behavior (E1 recovery). |
+| **Status** | Partially mitigated — HSOL timeout fallback documented in SKILLS.md |
+
+### RISK-003: No Automated Test Suite
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Quality / Regression |
+| **Description** | No automated tests exist for framework behavior. The `test` script in package.json points to `cli/*.test.js` but only an example file exists (`install.test.js.example`). Orchestration law compliance (L1–L10), error recovery (E1–E4), command routing, and HSOL resolution have no automated verification. |
+| **Probability** | High — test infrastructure is absent |
+| **Impact** | High — regressions in rule behavior, agent loading, or skill resolution will go undetected until a user reports them |
+| **Affected Goals** | BG-009 (quality/cadence) |
+| **Affected Requirements** | BR-012 (laws), BR-013 (error recovery) |
+| **Mitigation** | Create behavioral test suite covering: (1) CLI install/uninstall across platforms, (2) command routing correctness, (3) agent file format validation, (4) HSOL fitness calculation. Priority: CLI tests first (most automatable). |
+| **Status** | Open — no tests implemented |
+
+### RISK-004: No Public Roadmap
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Community / Adoption |
+| **Description** | No public roadmap, GitHub project board, or milestone plan exists. Contributors and potential adopters cannot assess planned features, release timelines, or investment direction. |
+| **Probability** | High — roadmap is confirmed absent |
+| **Impact** | Medium — reduced contributor engagement; enterprise adopters may hesitate without visibility |
+| **Affected Goals** | BG-009, BG-010 |
+| **Mitigation** | Publish a minimal roadmap in README or GitHub Discussions. Even a quarterly priority list improves transparency. |
+| **Status** | Open |
+
+### RISK-005: Trust Progression Lifecycle Unverified
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Feature Completeness |
+| **Description** | The Trust Progression system (NEW 0.3 → EVALUATING 0.5 → VALIDATED 0.7 → PROMOTED 1.0) is defined in documentation but has no implementation evidence. `_dynamic.yaml` may not actively track execution counts or trust transitions at runtime. |
+| **Probability** | Medium — specification exists but runtime behavior is unconfirmed |
+| **Impact** | Medium — BG-009 (community ecosystem quality gates) depends on trust progression working correctly |
+| **Affected Goals** | BG-009 |
+| **Affected Requirements** | BR-010 |
+| **Mitigation** | Verify that `_dynamic.yaml` actually records execution counts and trust state transitions. If not implemented, prioritize for next release or document as aspirational. |
+| **Status** | Open — investigation needed |
+
+### RISK-006: AI Model Behavior Variability
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Technical / Compatibility |
+| **Description** | The framework relies on AI models correctly interpreting Markdown instructions, following 10 orchestration laws, and performing cognitive anchoring. Different models (GPT-4, Claude, Gemini) may interpret instructions with varying fidelity. |
+| **Probability** | Medium — model capabilities vary and change with updates |
+| **Impact** | Medium — inconsistent delegation quality across platforms; some models may violate laws more frequently |
+| **Affected Goals** | BG-002, BG-004 |
+| **Affected Requirements** | BR-003, BR-012, BR-021 |
+| **Mitigation** | Test orchestration behavior on each supported model. Document known model-specific limitations. Cognitive anchoring (BR-021) partially addresses this. |
+| **Status** | Open — no cross-model testing documented |
+
+### RISK-007: Platform Breaking Changes
+
+| Attribute | Detail |
+|-----------|--------|
+| **Category** | Compatibility / Maintenance |
+| **Description** | AI coding tools (Cursor, Copilot, Claude Code, Codex, Antigravity) frequently update their instruction loading mechanisms. A platform change could break the framework's integration. |
+| **Probability** | Medium — AI tool ecosystem is rapidly evolving |
+| **Impact** | High — affected platform becomes unusable until install.js is updated |
+| **Affected Goals** | BG-002 |
+| **Affected Requirements** | BR-002 |
+| **Mitigation** | Monitor platform changelogs. Maintain platform-specific integration tests. The CLI's modular platform configuration in install.js isolates platform-specific logic. |
+| **Status** | Open — no automated compatibility monitoring |
+
+---
+
+## Assumptions
+
+| ID | Assumption | Impact if Invalid | Validation Method |
+|----|-----------|-------------------|-------------------|
+| A-001 | AI coding assistants will continue to support file-based instruction loading from global directories | Framework delivery mechanism becomes non-functional | Monitor platform documentation and release notes |
+| A-002 | Node.js 18+ will remain widely available and supported | Installation fails for users on older Node.js versions | Node.js LTS schedule shows v18 supported through April 2025; v20+ is current LTS |
+| A-003 | Developers are willing to install a global npm package for AI workflow improvement | Low adoption if resistance to global installs exists | User feedback, npm download metrics |
+| A-004 | The 5 currently supported platforms represent the majority of AI coding assistant usage | Missing platforms reduce addressable market | Market share data for AI coding tools |
+| A-005 | AI models are capable of following complex multi-step Markdown instructions with sufficient fidelity | Orchestration laws violated; quality degrades | Cross-model testing (currently not performed) |
+| A-006 | The 1,430 matrix skills provide sufficient coverage for most development domains | Users frequently encounter low-fitness scenarios requiring dynamic discovery | HSOL resolution logs (not currently collected) |
+| A-007 | Community skill authors will adopt the SKILL.md template and publish via skills.sh | Ecosystem growth stalls; BG-009 unachievable | skills.sh registry metrics |
+| A-008 | The Golden Triangle protocol produces measurably better output than single-agent execution | Team variant overhead is unjustified if quality delta is negligible | A/B testing (not currently planned) |
+| A-009 | Semantic-release with conventional commits provides adequate release automation | Release quality degrades if commit conventions are not followed | CI/CD pipeline monitoring |
+| A-010 | Contributors can effectively add agents and commands within 2 hours using provided templates | High contribution friction discourages ecosystem growth | Contributor surveys, onboarding time tracking |
+
+---
+
+## Open Questions
+
+| ID | Question | Context | Urgency | Suggested Resolution |
+|----|----------|---------|---------|---------------------|
+| OQ-001 | How will performance claims (70%/70%/85%) be validated? | Claims appear in README and marketing but no benchmark methodology exists | High | Define standardized benchmark tasks; measure with and without framework; publish results |
+| OQ-002 | What is the fallback experience when skills.sh is permanently unavailable? | Dynamic discovery is a Could-priority feature but referenced prominently | Medium | Document graceful degradation; consider bundling a local skill cache |
+| OQ-003 | Should trust progression be a runtime-enforced feature or a recommended practice? | `_dynamic.yaml` tracking is unverified; may be documentation-only | Medium | Investigate current implementation; decide enforce vs. recommend |
+| OQ-004 | What is the framework's position on telemetry/analytics for measuring adoption KPIs? | Multiple KPIs (team adoption, community skills, install success) have no measurement mechanism | Medium | Decide whether opt-in telemetry is acceptable; if not, define alternative measurement approaches |
+| OQ-005 | How will cross-model behavioral consistency be tested? | 5 platforms × multiple model versions = large test matrix | Medium | Establish minimal behavioral test suite; run manually per release on each platform |
+| OQ-006 | What is the roadmap for v2.0? | Contributors and enterprise adopters need visibility into planned direction | Low | Publish quarterly priorities in README or GitHub Discussions |
+| OQ-007 | Should the framework provide a local skill registry as alternative to skills.sh? | Reduces external dependency risk; increases maintenance burden | Low | Evaluate effort vs. RISK-002 impact; consider for v1.4 or v2.0 |
+| OQ-008 | How are orchestration law violations detected and reported? | No runtime monitoring exists; violations are silent | High | Implement at minimum a self-check mechanism the AI can invoke |
+| OQ-009 | What happens when a platform introduces a sub-agent mechanism (changing TIER 1 availability)? | Framework needs to detect and adapt; currently relies on tool presence check | Low | Document tool detection mechanism; test on platforms as features roll out |
+| OQ-010 | Is the ≤2 hour contribution target (BG-010) realistic for a first-time contributor? | No contributor onboarding study has been performed | Low | Run contributor onboarding sessions; measure actual time; adjust target if needed |
+
+---
+
+## Evidence Sources
+
+| Source | Path | Used For |
+|--------|------|----------|
+| Structured Business Pack | `reports/business-analysis/structured-business-pack.md` | Goals, requirements, traceability, coverage gaps, stakeholder mapping |
+| HSOL Assessment | `documents/HSOL-ASSESSMENT.md` | Skill layer production readiness, edge cases, trust progression analysis |
+| Package manifest | `package.json` | Test script existence, dependency count, version |
+| Core Rules | `rules/CORE.md` | Orchestration laws, tiered execution, command routing |
+| Error Rules | `rules/ERRORS.md` | Error classification E1–E4 |
+| Skills Rules | `rules/SKILLS.md` | HSOL resolution algorithm, dynamic discovery, trust progression |
+| Teams Rules | `rules/TEAMS.md` | Golden Triangle protocol, debate mechanism |
+| CLI installer | `cli/install.js` | Installation mechanism, platform detection |
+| Test example | `cli/install.test.js.example` | Evidence of absent test suite |
+| Features documentation | `documents/knowledge-overview/03-features.md` | Performance claims, feature evidence |
+| Dynamic skills config | `matrix-skills/_dynamic.yaml` | Trust progression state tracking |

package/documents/business/business-workflows/00-index.md

@@ -0,0 +1,107 @@
+# Agent Assistant — Business Workflows Index
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Summary index of all business workflows, actors, cross-references, and known gaps |
+| **Parent** | [../README.md](../README.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Quick Summary
+
+The Agent Assistant framework operates through **12 canonical workflows** executed by **7 distinct actor types**. Workflows span the full lifecycle from CLI installation (BW-001) through command routing (BW-003), agent delegation (BW-004), skill resolution (BW-005), team collaboration (BW-008), error recovery (BW-010), and platform integration (BW-012). Every workflow enforces strict phase sequencing, tiered execution, and deterministic error handling — no silent failures are permitted.
+
+---
+
+## Sub-Files
+
+| File | Title | Description |
+|------|-------|-------------|
+| [01-actor-map.md](01-actor-map.md) | Actor Map | All 7 actors with definitions, responsibilities, capabilities, boundary constraints, touchpoints |
+| [02-workflow-catalog.md](02-workflow-catalog.md) | Workflow Catalog | All 12 workflows (BW-001 – BW-012): ID, name, actor, trigger, outcome, complexity, frequency |
+| [03-detailed-workflows.md](03-detailed-workflows.md) | Detailed Workflows | Step-by-step flows with Mermaid diagrams, decision points, branching, error paths |
+| [04-decision-rules-and-exceptions.md](04-decision-rules-and-exceptions.md) | Decision Rules & Exceptions | Orchestration laws, tiered execution rules, HSOL thresholds, exception catalog |
+| [05-sla-and-handoffs.md](05-sla-and-handoffs.md) | SLA & Handoffs | Timing expectations, handoff contracts, SLA/SLO targets |
+
+---
+
+## Key Facts
+
+| Metric | Value |
+|--------|-------|
+| Total Workflows | 12 (BW-001 – BW-012) |
+| Actor Types | 7 |
+| CLI Commands | 14 |
+| Supported Platforms | 5 (Claude, Copilot, Cursor, Codex, Gemini) |
+| Specialist Agents | 21 |
+| Defined Teams | 17 |
+| Skill Catalog Size | 1,430 |
+| Error Recovery Tiers | 4 (E1 – E4) |
+| HSOL Fitness Thresholds | 3 bands (≥0.8, 0.75–0.8, <0.75) |
+| Max Team Debate Rounds | 3 |
+| Trust Progression Stages | 4 (NEW → EVALUATING → VALIDATED → PROMOTED) |
+
+---
+
+## Workflow Distribution by Actor
+
+| Actor | Primary Workflows | Supporting Workflows |
+|-------|-------------------|---------------------|
+| Framework User | BW-001, BW-002 | BW-003 (trigger) |
+| AI Model (Orchestrator) | BW-003, BW-004, BW-008, BW-009, BW-010, BW-011 | BW-005 (coordinates) |
+| HSOL System | BW-005, BW-006, BW-007 | — |
+| Team Agents | BW-008 | BW-003 (phase execution) |
+| Framework Maintainer | BW-012 | BW-002 (defines removal logic) |
+| Skill Author | — | BW-006 (publishes skills) |
+| Contributor | — | BW-012 (adds agents/commands) |
+
+---
+
+## Cross-References
+
+| Workflow | Depends On | Feeds Into |
+|----------|------------|------------|
+| BW-001 (Installation) | — | BW-003 (enables command execution) |
+| BW-002 (Uninstallation) | BW-001 (requires prior install) | — |
+| BW-003 (Command Execution) | BW-001, BW-004, BW-005 | BW-009 (doc generation), BW-011 (plan shortcut) |
+| BW-004 (Agent Delegation) | BW-003 (phase context) | BW-005 (triggers skill resolution) |
+| BW-005 (Skill Resolution) | BW-004 (agent needs skills) | BW-006 (below threshold) |
+| BW-006 (Dynamic Discovery) | BW-005 (low fitness) | BW-007 (trust tracking) |
+| BW-007 (Trust Progression) | BW-006 (new dynamic skill) | BW-005 (updated fitness) |
+| BW-008 (Team Collaboration) | BW-003 (`:team` variant) | BW-004 (each team member delegated) |
+| BW-009 (Doc Generation) | BW-003 (command trigger) | — |
+| BW-010 (Error Recovery) | Any workflow (on failure) | Resumes originating workflow |
+| BW-011 (Plan Short-Circuit) | BW-003 (detects plan ref) | BW-004 (skips to implementation) |
+| BW-012 (Platform Integration) | — | BW-001 (new install targets) |
+
+---
+
+## Known Gaps
+
+| Gap ID | Area | Description | Impact | Suggested Resolution |
+|--------|------|-------------|--------|---------------------|
+| BG-001 | Skill Author Workflow | No formal workflow for skill authoring, publishing, or quality review | Skill quality inconsistency | Define BW-013: Skill Authoring & Publishing |
+| BG-002 | Contributor Onboarding | No workflow for contributor onboarding or contribution validation | Barrier to contribution | Define BW-014: Contribution Lifecycle |
+| BG-003 | Versioning | No workflow for framework version migration or backward compatibility | Breaking changes unmanaged | Define BW-015: Version Migration |
+| BG-004 | Observability | No workflow for runtime telemetry or workflow execution audit | Debugging blind spots | Define BW-016: Observability & Audit Trail |
+| BG-005 | Rollback Scope | BW-010 E4 rollback mechanism lacks granularity definition | Incomplete rollback possible | Expand E4 with per-phase rollback contracts |
+| BG-006 | Trust Decay Monitoring | BW-007 specifies 90-day decay but no monitoring/alerting workflow | Silent skill degradation | Add monitoring hook to HSOL System |
+
+---
+
+## Evidence Sources
+
+- `CLAUDE.md` — Orchestrator identity, tiered execution model, prohibitions
+- `rules/CORE.md` — 10 Orchestration Laws, phase sequencing rules
+- `rules/AGENTS.md` — Agent delegation protocol, TIER 1/TIER 2 definitions
+- `rules/SKILLS.md` — HSOL resolution algorithm, fitness thresholds, trust progression
+- `rules/TEAMS.md` — Golden Triangle protocol, debate rounds, consensus stamps
+- `rules/ERRORS.md` — E1–E4 error classification and recovery paths
+- `rules/PHASES.md` — Phase sequencing constraints, exit criteria
+- `cli/install.js` — Installation/uninstallation implementation
+- `commands/*.md` — Command definitions and variant routing
+- `agents/*.md` — Agent profiles, capabilities, tool access
+- `matrix-skills/_index.yaml` — Skill catalog index
+- `matrix-skills/_dynamic.yaml` — Dynamic skill registry

package/documents/business/business-workflows/01-actor-map.md

@@ -0,0 +1,303 @@
+# Agent Assistant — Actor Map
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Define all actors participating in business workflows with responsibilities, capabilities, constraints, and workflow touchpoints |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Actor Overview
+
+The framework recognizes 7 distinct actor types operating across 12 business workflows. Each actor has defined boundaries — no actor may assume another's responsibilities. The Orchestrator sits at the center, coordinating all specialist work without implementing directly.
+
+| # | Actor | Type | Primary Domain |
+|---|-------|------|---------------|
+| A-01 | Framework User | Human | CLI interaction, command invocation |
+| A-02 | AI Model (Orchestrator) | AI Runtime | Coordination, delegation, verification |
+| A-03 | Skill Author | Human | Skill creation and publishing |
+| A-04 | Framework Maintainer (NamCH) | Human | Framework evolution, releases |
+| A-05 | Contributor | Human | Agents, commands, skills additions |
+| A-06 | HSOL System | Automated | Skill resolution, trust management |
+| A-07 | Team Agents | AI Runtime | Specialized execution in team context |
+
+---
+
+## A-01: Framework User
+
+**Definition**: An individual developer or development team that installs and uses the agent-assistant framework through its CLI and prompt commands within a supported AI coding assistant.
+
+### Responsibilities
+- Install/uninstall framework via CLI (`agent-assistant install/uninstall`)
+- Invoke commands through prompt input (`/{cmd}`, `/{cmd}:{variant}`, or natural language)
+- Provide requirements and context for tasks
+- Confirm or reject decisions when prompted (e.g., HSOL low-trust skill confirmation)
+- Receive and evaluate deliverables
+
+### Capabilities
+- Shell/terminal access for CLI operations
+- Prompt interaction with AI coding assistant
+- Decision authority on ambiguous requirements
+- Final acceptance of deliverables
+
+### Boundary Constraints
+- Cannot directly invoke agent delegation — must go through Orchestrator
+- Cannot modify framework internals without Maintainer role
+- Cannot bypass Orchestrator's phase sequencing
+- Has no visibility into HSOL internal scoring
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-001 | Primary actor | Runs `agent-assistant install` |
+| BW-002 | Primary actor | Runs `agent-assistant uninstall` |
+| BW-003 | Trigger | Types command or natural language request |
+| BW-006 | Confirmer | Approves low-trust critical skill installation |
+| BW-010 | Escalation target | Final decision after E4 exhaustion |
+
+---
+
+## A-02: AI Model (Orchestrator)
+
+**Definition**: The AI runtime (Claude, Copilot, Cursor, Codex, Gemini) that reads framework instructions (CLAUDE.md, COPILOT.md, etc.) and follows orchestration protocols. Functions as conductor — delegates all implementation to specialists.
+
+### Responsibilities
+- Route commands to correct workflow and variant
+- Decompose work into phases following defined sequences
+- Delegate each phase to the appropriate specialist agent
+- Verify exit criteria for every phase before proceeding
+- Enforce all 10 Orchestration Laws
+- Execute error recovery (BW-010) when failures occur
+- Deliver final results to Framework User
+
+### Capabilities
+- Full context of framework rules, agents, commands, skills
+- Sub-agent spawning (TIER 1) or embodiment (TIER 2)
+- Phase state tracking and exit criteria verification
+- Cross-workflow coordination
+- Error classification and recovery path selection
+
+### Boundary Constraints
+- **NEVER implements directly** (Law 7 — absolute prohibition)
+- Cannot skip phases or reorder phase sequences
+- Cannot guess on ambiguous requirements — must PAUSE and ASK (Law 2)
+- Cannot modify deliverables from prior phases (Law 8 — immutability)
+- Must use TIER 1 when `runSubagent` is available — TIER 2 only as fallback
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-003 | Primary executor | Routes and manages command execution |
+| BW-004 | Primary executor | Delegates to specialist agents |
+| BW-005 | Coordinator | Initiates HSOL resolution for agents |
+| BW-008 | Primary executor | Manages Golden Triangle team flow |
+| BW-009 | Primary executor | Manages documentation generation phases |
+| BW-010 | Primary executor | Classifies errors, executes recovery |
+| BW-011 | Primary executor | Detects plan reference, skips phases |
+
+---
+
+## A-03: Skill Author
+
+**Definition**: A creator who builds and publishes domain-specific skills to the skill catalog. Skills are structured packages with SKILL.md definitions that agents consume during task execution.
+
+### Responsibilities
+- Author SKILL.md files following the skill template
+- Define skill metadata (domain, keywords, complexity)
+- Publish skills to discoverable registries
+- Maintain and update published skills
+
+### Capabilities
+- Skill template access
+- Publishing to skill registries
+- Versioning of skill packages
+
+### Boundary Constraints
+- Cannot control how HSOL scores or selects skills
+- Cannot force skill usage — selection is fitness-based
+- Cannot modify matrix-skills YAML files directly (Maintainer-only)
+- Published skills start at NEW trust level (0.3)
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-006 | Upstream provider | Published skills discovered by `npx skills find` |
+| BW-007 | Indirect | Skill trust progresses based on execution outcomes |
+
+---
+
+## A-04: Framework Maintainer (NamCH)
+
+**Definition**: The framework owner who evolves architecture, manages releases, defines platform integrations, and maintains core rules, agents, and command definitions.
+
+### Responsibilities
+- Evolve framework architecture and release versions
+- Define and maintain Orchestration Laws (rules/CORE.md)
+- Manage agent definitions and team compositions
+- Add/remove platform support
+- Curate matrix-skills YAML catalog
+- Review and merge contributions
+- Manage npm package releases
+
+### Capabilities
+- Full repository write access
+- npm publish authority
+- Platform integration definition
+- Rule and law authoring
+- Agent and command lifecycle management
+
+### Boundary Constraints
+- Changes to Orchestration Laws require version bump
+- New platforms must follow existing conventions (BW-012)
+- Cannot override runtime behavior of AI Model at execution time
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-001 | Defines | Designs installation logic and file mappings |
+| BW-002 | Defines | Designs uninstallation logic and preservation rules |
+| BW-012 | Primary actor | Adds new platform support |
+
+---
+
+## A-05: Contributor
+
+**Definition**: An external or team contributor who adds agents, commands, skills, or other framework components through pull requests or direct collaboration.
+
+### Responsibilities
+- Add new agent definitions following AGENT-TEMPLATE.md
+- Create new commands or command variants
+- Contribute skills to the catalog
+- Follow contribution conventions
+- Submit changes for review
+
+### Capabilities
+- Fork/branch repository access
+- Agent and command template access
+- Skill authoring tools
+
+### Boundary Constraints
+- Cannot modify core rules without Maintainer approval
+- Cannot publish npm releases
+- Contributions must pass review (implicit BW-008 quality standard)
+- Cannot modify existing agent boundaries
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-012 | Supporting | Adds agents, commands, or skills |
+
+---
+
+## A-06: HSOL System
+
+**Definition**: The Harmonized Skill Orchestration Layer — an automated subsystem responsible for resolving which skills an agent uses during task execution. Operates through matrix scoring, dynamic discovery, and trust progression.
+
+### Responsibilities
+- Parse agent skill profiles from agent definition files
+- Load relevant domain YAML files from matrix-skills/
+- Filter skills by relevance to current task
+- Compute fitness scores using 5-weight algorithm
+- Route to appropriate resolution path based on fitness band
+- Execute dynamic discovery when fitness is below threshold
+- Track trust progression for dynamically discovered skills
+- Manage skill lifecycle (NEW → EVALUATING → VALIDATED → PROMOTED → BLOCKED)
+
+### Capabilities
+- Matrix-skills YAML access (read)
+- Dynamic YAML registry access (read/write to `_dynamic.yaml`)
+- `npx skills find` execution
+- `npx skills add` execution
+- Fitness scoring algorithm (5 weighted factors)
+- Trust state machine management
+
+### Boundary Constraints
+- Cannot override Orchestrator's phase decisions
+- Cannot install skills without proper fitness evaluation
+- Low-trust + critical skills require Framework User confirmation
+- Network timeout caps at 5 seconds — falls back to matrix-only
+- Cannot promote skills that fail rate threshold (<85% success)
+- Cannot prevent 90-day inactivity decay
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-005 | Primary executor | Resolves skills for agent phases |
+| BW-006 | Primary executor | Discovers and installs dynamic skills |
+| BW-007 | Primary executor | Manages trust state transitions |
+
+---
+
+## A-07: Team Agents
+
+**Definition**: Specialist AI agents operating within the Golden Triangle team protocol — specifically the Tech Lead, Executor, and Reviewer roles. They work collaboratively on `:team` variant commands through structured debate.
+
+### Sub-Actors
+
+| Role | Agent | Responsibility |
+|------|-------|---------------|
+| Tech Lead | tech-lead.md | Decomposes tasks, assigns work, arbitrates disputes |
+| Executor | (varies by domain) | Implements assigned tasks |
+| Reviewer | reviewer.md | Critiques deliverables, enforces quality |
+
+### Responsibilities
+- **Tech Lead**: Decompose task → create TASK_ASSIGNMENT → post to Mailbox → arbitrate after 3 rounds
+- **Executor**: Read assignment → implement → SUBMISSION to Mailbox
+- **Reviewer**: Read submission → critique with REVIEW (PASS/FAIL) → require evidence for FAIL
+
+### Capabilities
+- Mailbox protocol (read/write task assignments, submissions, reviews)
+- Domain-specific implementation (Executor varies by skill domain)
+- Code review and quality assessment (Reviewer)
+- Architectural decomposition (Tech Lead)
+
+### Boundary Constraints
+- Maximum 3 debate rounds — then Tech Lead arbitrates final decision
+- "Disagree without proof" results in automatic FAIL
+- Cannot bypass consensus stamp requirement
+- Cannot communicate outside Mailbox protocol during team workflow
+- Reviewer cannot implement — only review
+- Executor cannot override review decisions directly
+
+### Workflow Touchpoints
+
+| Workflow | Role | Interaction |
+|----------|------|-------------|
+| BW-008 | Primary actors | Execute Golden Triangle collaboration |
+| BW-003 | Phase executors | Delegated by Orchestrator for individual phases |
+
+---
+
+## Actor Interaction Matrix
+
+| | Framework User | Orchestrator | Skill Author | Maintainer | Contributor | HSOL System | Team Agents |
+|---|---|---|---|---|---|---|---|
+| **Framework User** | — | Commands/receives | — | Reports issues | — | Confirms skills | — |
+| **Orchestrator** | Delivers/asks | — | — | — | — | Requests skills | Delegates/verifies |
+| **Skill Author** | — | — | — | Submits skills | — | Publishes to | — |
+| **Maintainer** | Releases to | Defines rules for | Reviews skills | — | Reviews PRs | Configures | Defines agents |
+| **Contributor** | — | — | — | Submits PRs | — | — | — |
+| **HSOL System** | Asks confirmation | Reports scores to | Discovers from | — | — | — | Provides skills to |
+| **Team Agents** | — | Reports to | — | — | — | Receives skills | Collaborates |
+
+---
+
+## Evidence Sources
+
+- `CLAUDE.md` — Orchestrator identity and prohibitions (Law 7)
+- `rules/CORE.md` — 10 Orchestration Laws defining actor boundaries
+- `rules/AGENTS.md` — TIER 1/TIER 2 agent delegation protocol
+- `rules/SKILLS.md` — HSOL resolution algorithm, trust progression state machine
+- `rules/TEAMS.md` — Golden Triangle protocol, Mailbox system, debate limits
+- `agents/*.md` — Individual agent profiles (21 agents)
+- `agents/teams/` — Team composition definitions
+- `cli/install.js` — CLI actor interaction model
+- `AGENT-TEMPLATE.md` — Contributor agent template