@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-prd/01-executive-summary.md

@@ -0,0 +1,131 @@
+# Agent Assistant — Executive Summary
+
+> **Purpose**: Mission statement, value proposition, target outcomes, target users, and key metrics for the Agent Assistant PRD
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Mission Statement
+
+Agent Assistant exists to transform a single AI coding assistant into a coordinated team of specialist agents, providing structured, repeatable workflows that eliminate manual prompt engineering and enforce quality governance — all from a one-time global installation with zero per-project configuration.
+
+---
+
+## Value Proposition
+
+### For Individual Developers
+
+One install. Every project. Agent Assistant installs once into your AI tool's global config directory (`~/.cursor/`, `~/.claude/`, `~/.copilot/`, `~/.codex/`, `~/.gemini/`) and applies automatically to every project you open. Instead of crafting prompts from scratch, you invoke structured commands (`/cook`, `/fix`, `/plan`, `/test`, `/review`, etc.) that delegate to specialist agents trained for specific tasks — a backend engineer for API code, a tester for test suites, a reviewer for code quality, a debugger for issue diagnosis.
+
+The framework claims 70% faster time-to-production, 70% bug reduction, and 85% token cost savings through focused agent profiles and HSOL skill injection. These claims are currently unvalidated and should be treated as design targets.
+
+### For Teams and Organizations
+
+The `:team` variant activates the Golden Triangle protocol — Tech Lead, Executor, and Reviewer collaborate adversarially with structured debate (max 3 rounds), consensus stamps, and full audit trails via Mailbox logs. This enforces consistent quality governance across team members without requiring process documentation or manual review checklists.
+
+### For the Ecosystem
+
+Skill Authors can create and publish domain skills to the community ecosystem. The Trust Progression Lifecycle (NEW → EVALUATING → VALIDATED → PROMOTED) provides quality gates. The HSOL layer automatically discovers and recommends relevant community skills when matrix coverage is insufficient.
+
+---
+
+## Target Outcomes
+
+| Outcome ID | Outcome | Measurement | Status |
+|------------|---------|-------------|--------|
+| TO-001 | One-time installation works across all projects without per-project config | Installation success rate ≥99%; zero config files required per project | Achievable — CLI install mechanism verified in source |
+| TO-002 | All 5 major AI coding platforms supported from single codebase | 5/5 platforms produce correct entry points and config files | Achieved — install.js supports all 5 platforms |
+| TO-003 | Structured workflows available for all common development tasks | 14 command types with 4 variant strategies each (56 total workflows) | Achieved — commands/ directory contains all 14 commands with variants |
+| TO-004 | Domain knowledge auto-injected without manual skill selection | HSOL fitness ≥0.8 for matrix skills; auto-injection by agent profile | Specified — HSOL rules and matrix YAML present; runtime behavior unverified |
+| TO-005 | Quality governance enforced for team workflows | Golden Triangle protocol with debate, consensus, audit trail | Specified — team agents and TEAMS.md defined; runtime verification pending |
+| TO-006 | Reduced time-to-production | ≥70% faster (claimed target) | Unvalidated — no benchmarks in repository |
+| TO-007 | Reduced bug rate in AI-generated code | ≥70% reduction (claimed target) | Unvalidated — no benchmarks in repository |
+| TO-008 | Reduced token cost | ≥85% savings (claimed target) | Unvalidated — no benchmarks in repository |
+
+---
+
+## Target Users
+
+### Primary: Individual Developer (Framework User)
+
+- **Profile**: Software developer using one or more AI coding assistants daily
+- **Need**: Reduce repetitive prompt engineering; get consistent, high-quality AI outputs across projects
+- **Touchpoints**: CLI installer (`agent-assistant install`), slash commands (`/cook`, `/fix`, `/plan`), natural language (the framework detects intent)
+- **Goals served**: BG-001 (one-time setup), BG-003 (faster delivery), BG-004 (fewer bugs), BG-005 (lower token cost), BG-006 (structured workflows)
+
+### Secondary: Team/Organization Lead
+
+- **Profile**: Technical lead or engineering manager standardizing AI-assisted development practices
+- **Need**: Consistent quality across team members; audit trail for AI-generated work
+- **Touchpoints**: `:team` and `:hard` command variants, Mailbox logs, Golden Triangle protocol
+- **Goals served**: BG-002 (consistent practices), BG-008 (adversarial collaboration)
+
+### Tertiary: Skill Author
+
+- **Profile**: Developer who creates reusable domain skills for the community
+- **Need**: Publish skills, gain trust, and eventually have skills promoted to the matrix
+- **Touchpoints**: `SKILL.md` template, `find-skills` CLI, skills.sh platform, Trust Progression Lifecycle
+- **Goals served**: BG-009 (community ecosystem)
+
+### Enabling: AI Model (Runtime)
+
+- **Profile**: The AI coding assistant itself (GPT-4, Claude, Gemini, etc.) that reads and executes framework instructions
+- **Need**: Clear, unambiguous instructions with cognitive anchoring that overrides default behavior
+- **Touchpoints**: Platform entry point files (CLAUDE.md, COPILOT.md, etc.), agent definitions, CORE.md rules
+- **Goals served**: BG-007 (auto skill injection), all goals indirectly (the AI model is the execution engine)
+
+### Supporting: Platform Maintainer
+
+- **Profile**: Developer at Cursor, GitHub, Anthropic, OpenAI, or Google maintaining AI tool compatibility
+- **Need**: Framework integrates cleanly with platform's file-based instruction loading
+- **Touchpoints**: install.js platform configuration, entry point templates
+- **Goals served**: BG-002 (multi-platform support)
+
+### Governing: Framework Maintainer (NamCH)
+
+- **Profile**: Creator and primary maintainer of the agent-assistant framework
+- **Need**: Sustainable release cadence, extensible architecture, community growth
+- **Touchpoints**: All source code, CI/CD pipeline, npm publishing, semantic versioning
+- **Goals served**: BG-009 (quality/cadence), BG-010 (extensibility)
+
+### Contributing: Contributor
+
+- **Profile**: Open-source developer adding agents, commands, skills, or documentation
+- **Need**: Clear templates, low friction to contribute, visible contribution path
+- **Touchpoints**: AGENT-TEMPLATE.md, command structure conventions, skill SKILL.md template
+- **Goals served**: BG-010 (extensibility), BG-009 (community ecosystem)
+
+---
+
+## Key Metrics
+
+| Metric | Target | Measurement Method | Validation Status |
+|--------|--------|--------------------|-------------------|
+| Installation success rate | ≥99% across all 5 platforms | CLI exit codes; manual testing | Partially validated (source review confirms mechanism; no automated test suite) |
+| Time-to-production improvement | ≥70% faster vs. unstructured prompting | Before/after elapsed time comparison | Unvalidated — no benchmark data |
+| Bug rate reduction | ≥70% fewer defects per feature | Before/after defect counts | Unvalidated — no benchmark data |
+| Token cost savings | ≥85% reduction vs. unstructured prompting | Token consumption per equivalent task | Unvalidated — no benchmark data |
+| Platform coverage | 5/5 platforms | install.js platform config count | Validated — 5 platforms configured in source |
+| Specialist agent coverage | 21 agents with unique profiles | agents/ directory file count and frontmatter audit | Validated — 21 agent files present |
+| Command coverage | 14 commands × 4 variants | commands/ directory audit | Validated — 14 commands with variant subdirectories |
+| Matrix skill coverage | 1,430+ skills across 19 domains | matrix-skills/ YAML entry count | Validated — 19 domain YAML files present |
+| Team adoption rate | ≥80% within 30 days | Survey or usage telemetry | No measurement mechanism exists |
+| Community skills published | ≥50 within 12 months of v1.0 | skills.sh registry count | No measurement mechanism exists |
+
+---
+
+## Evidence Sources
+
+| Source | Path | Used For |
+|--------|------|----------|
+| Structured Business Pack | `reports/business-analysis/structured-business-pack.md` | Goals, stakeholders, requirements, traceability |
+| Package manifest | `package.json` | Version, description, platform scripts |
+| Knowledge Overview | `documents/knowledge-overview/00-index.md` | Quick facts, project identity |
+| Features | `documents/knowledge-overview/03-features.md` | Performance claims, feature descriptions, platform table |
+| Core Rules | `rules/CORE.md` | Orchestrator identity, tiered execution, command routing |
+| HSOL Assessment | `documents/HSOL-ASSESSMENT.md` | Skill layer readiness |
+| Agents directory | `agents/*.md` | Agent count and profile verification |
+| Commands directory | `commands/*.md` | Command count verification |
+| Matrix Skills | `matrix-skills/*.yaml` | Skill count and domain coverage |

package/documents/business/business-prd/02-problem-goals-and-scope.md

@@ -0,0 +1,204 @@
+# Agent Assistant — Problem, Goals, and Scope
+
+> **Purpose**: Problem statement, 10 business goals (BG-001–BG-010), non-goals, and in-scope/out-of-scope boundary
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Problem Statement
+
+AI coding assistants (Cursor, Copilot, Claude Code, Codex, Gemini) are powerful individually but operate as generalist single-agents. Developers face three compounding problems:
+
+1. **Repetitive prompt engineering**: Every project, every task requires crafting prompts from scratch. There is no memory of what worked, no reuse of proven workflows, and no structured handoff between tasks. The result is inconsistent output quality and wasted time.
+
+2. **No specialist depth**: A single AI model attempts backend engineering, frontend design, testing, security review, and deployment planning with equal (and often shallow) competence. There is no mechanism to focus the model on a specific role with domain-appropriate constraints, thinking protocols, and quality gates.
+
+3. **No governance at scale**: Teams using AI assistants have no standard for how AI-generated code is reviewed, tested, or deployed. Each team member uses the AI differently, producing inconsistent results with no audit trail and no adversarial review process.
+
+The cost is measured in time (manual prompt iteration), quality (bugs from shallow generalist output), tokens (verbose unstructured prompts), and governance (no accountability for AI-generated deliverables).
+
+---
+
+## Business Goals
+
+### BG-001: One-Time Global Setup
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Enable one-time global setup that works across all projects |
+| **Rationale** | Per-project configuration creates friction and discourages adoption. A global install ensures the framework applies automatically to every workspace. |
+| **KPI** | Installation success rate ≥99%; zero per-project configuration files needed |
+| **Priority** | Must |
+| **Requirements** | BR-001 (global install), BR-023 (CLI list) |
+| **Features** | BF-001 (one-time install), BF-023 (CLI list) |
+
+### BG-002: Multi-Platform Support
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Support all major AI coding assistants from a single codebase |
+| **Rationale** | Developers use different AI tools. Platform lock-in is a dealbreaker for adoption. |
+| **KPI** | 5 platforms supported (Cursor, Copilot, Claude Code, Codex, Antigravity/Gemini); identical command set across all |
+| **Priority** | Must |
+| **Requirements** | BR-001 (global install), BR-002 (5 platforms) |
+| **Features** | BF-001 (install), BF-002 (multi-platform) |
+
+### BG-003: Reduce Time-to-Production
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Reduce time-to-production for AI-assisted development |
+| **Rationale** | Structured workflows with specialist agents and parallel execution eliminate manual coordination overhead. |
+| **KPI** | ≥70% faster elapsed time from requirement to merged PR |
+| **Priority** | Must |
+| **Validation Status** | **UNVALIDATED** — no benchmark data exists in the repository. Treat as a design target, not a measured result. |
+| **Requirements** | BR-003 (orchestrator), BR-006 (commands), BR-008 (HSOL), BR-019 (/auto) |
+| **Features** | BF-003 (orchestrator), BF-006 (commands), BF-008 (HSOL), BF-019 (/auto) |
+
+### BG-004: Reduce Bug Rate
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Reduce bug rate in AI-generated code |
+| **Rationale** | Quality gates in `:hard` variants enforce testing, review, and security checks before delivery. Specialist agents produce more focused, higher-quality output than generalist prompting. |
+| **KPI** | ≥70% reduction in defects per feature delivered |
+| **Priority** | Must |
+| **Validation Status** | **UNVALIDATED** — no benchmark data exists in the repository. Treat as a design target. |
+| **Requirements** | BR-004 (agents), BR-005 (teams), BR-012 (laws), BR-013 (error recovery), BR-014 (debate) |
+| **Features** | BF-004 (agents), BF-005 (teams), BF-012 (laws), BF-013 (error recovery), BF-014 (debate) |
+
+### BG-005: Reduce Token Cost
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Reduce token cost of AI interactions |
+| **Rationale** | Focused agent profiles with HSOL skill injection reduce prompt size by loading only relevant domain knowledge instead of verbose catch-all prompts. |
+| **KPI** | ≤85% token cost reduction vs. unstructured prompting |
+| **Priority** | Should |
+| **Validation Status** | **UNVALIDATED** — no benchmark data exists. Treat as a design target. |
+| **Requirements** | BR-003 (orchestrator), BR-008 (HSOL), BR-011 (tiered execution), BR-016 (plan short-circuit) |
+| **Features** | BF-003, BF-008, BF-011, BF-016 |
+
+### BG-006: Structured Repeatable Workflows
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Provide structured, repeatable workflows for all common development tasks |
+| **Rationale** | Without structured workflows, each AI session starts from zero. Commands with defined phases, agent assignments, and exit criteria ensure consistent execution. |
+| **KPI** | 14 command types with 4 variant strategies each (56 workflows) covering build, quality, planning, documentation, and deployment |
+| **Priority** | Must |
+| **Requirements** | BR-003 (orchestrator), BR-006 (commands), BR-007 (variants), BR-015 (NLP detection) |
+| **Features** | BF-003, BF-006, BF-007, BF-015 |
+
+### BG-007: Automatic Domain Skill Injection
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Enable automatic domain skill injection without manual configuration |
+| **Rationale** | Manual skill selection doesn't scale. HSOL resolves skills by matching agent profiles to 1,430+ matrix entries using a 5-factor fitness score, injecting relevant domain knowledge automatically. |
+| **KPI** | HSOL fitness ≥0.8 for matrix skills; auto-injection driven by agent profile |
+| **Priority** | Must |
+| **Requirements** | BR-008 (HSOL), BR-009 (dynamic discovery), BR-010 (trust progression) |
+| **Features** | BF-008, BF-009, BF-010 |
+
+### BG-008: Adversarial Collaboration
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Enable adversarial collaboration for quality-critical work |
+| **Rationale** | A single agent reviewing its own work misses errors. The Golden Triangle (Tech Lead + Executor + Reviewer) introduces structured disagreement with debate rounds, binding arbitration, and consensus stamps. |
+| **KPI** | Golden Triangle protocol active for all `:team` variants; debate rounds capped at 3; consensus stamp required before phase release |
+| **Priority** | Should |
+| **Requirements** | BR-005 (teams), BR-014 (debate mechanism) |
+| **Features** | BF-005, BF-014 |
+
+### BG-009: Community Skill Ecosystem
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Grow a community skill ecosystem with trust governance |
+| **Rationale** | The matrix covers 1,430 skills today but cannot cover every domain. A community ecosystem with quality gates (Trust Progression) allows organic growth while maintaining safety. |
+| **KPI** | Trust progression lifecycle operational; ≥50 community skills within 12 months; auto-promotion pipeline functional |
+| **Priority** | Should |
+| **Requirements** | BR-009 (dynamic discovery), BR-010 (trust progression) |
+| **Features** | BF-009, BF-010 |
+| **External Dependency** | skills.sh platform (not bundled with framework) |
+
+### BG-010: Auto-Generated Documentation
+
+| Attribute | Detail |
+|-----------|--------|
+| **Goal** | Provide comprehensive auto-generated project documentation |
+| **Rationale** | Documentation is chronically neglected. The `/docs` command automates generation of knowledge, business, and audit documentation from source code analysis. |
+| **KPI** | `/docs:core` produces 5 folders; `/docs:business` produces 4 folders; `/docs:audit` produces 4 folders |
+| **Priority** | Should |
+| **Requirements** | BR-017 (/docs generation) |
+| **Features** | BF-017 |
+
+---
+
+## Non-Goals
+
+The following are explicitly NOT objectives for Agent Assistant v1.3.0:
+
+| Non-Goal | Rationale |
+|----------|-----------|
+| Replace human developers | The framework augments developer productivity; human judgment and oversight remain essential |
+| Provide a backend server or HTTP API | Agent Assistant operates as a file-based configuration layer, not a running service |
+| Build a SaaS platform | No hosted service, no user accounts, no subscription model |
+| Create a database or data persistence layer | All state is file-based (Markdown, YAML); no database engine is used or required |
+| Develop a mobile application | The framework targets desktop AI coding assistant integrations only |
+| Guarantee measured performance improvements | Performance claims (70%/70%/85%) are design targets, not validated metrics |
+| Bundle the find-skills ecosystem | Dynamic skill discovery depends on the external skills.sh service; the framework works without it |
+| Enforce AI model selection | The framework is model-agnostic; it works with whatever model the AI tool provides |
+
+---
+
+## Scope Boundary
+
+### In Scope
+
+| Component | Description | Evidence |
+|-----------|-------------|----------|
+| CLI Installer | Node.js installer (`cli/install.js`) that copies framework files to platform-specific global directories | `cli/install.js` |
+| 21 Specialist Agents | Markdown agent definitions with frontmatter, thinking protocols, constraints, and output formats | `agents/*.md` |
+| 17 Domain Teams | Golden Triangle team configurations for adversarial collaboration | `agents/teams/` |
+| 14 Commands (54+ variants) | Structured workflow files with phases, agent assignments, and exit criteria | `commands/*.md`, `commands/*/` |
+| 7 Rule Files | Governance rules: CORE, PHASES, AGENTS, SKILLS, ERRORS, REFERENCE, TEAMS | `rules/*.md` |
+| HSOL (Matrix Skills) | 1,430+ pre-curated skills across 19 domain YAML files | `matrix-skills/*.yaml` |
+| HSOL (Dynamic Discovery) | Integration point for community skill discovery via find-skills | `rules/SKILLS.md`, `matrix-skills/_dynamic.yaml` |
+| Platform Entry Points | Per-platform bootstrap files: CLAUDE.md, COPILOT.md, CURSOR.md, CODEX.md, GEMINI.md | Root directory `*.md` files |
+| Web Marketing Site | React 19 + Vite + Tailwind CSS v4 site deployed on Vercel | `web/` |
+| Documentation Generation | `/docs` command producing knowledge, business, and audit document folders | `commands/docs.md`, `commands/docs/` |
+
+### Out of Scope
+
+| Component | Reason for Exclusion |
+|-----------|---------------------|
+| Backend server | No server-side application exists; framework is file-based configuration |
+| Database | No data persistence layer; all state is in Markdown/YAML files |
+| HTTP API | No API endpoints; interaction is through AI tool's native interface |
+| Mobile application | Framework targets desktop AI coding tools exclusively |
+| SaaS platform | No hosted service, no accounts, no subscriptions |
+| AI model training or fine-tuning | Framework provides instructions to existing models, not custom training |
+| skills.sh platform | External dependency; not maintained or bundled within this project |
+| Telemetry or analytics | No usage tracking, no metrics collection, no phone-home behavior |
+
+---
+
+## Evidence Sources
+
+| Source | Path | Used For |
+|--------|------|----------|
+| Structured Business Pack | `reports/business-analysis/structured-business-pack.md` | Goals, requirements, features, traceability matrix, coverage gaps |
+| Knowledge Overview | `documents/knowledge-overview/00-index.md` | Project facts, quick summary |
+| Features | `documents/knowledge-overview/03-features.md` | Performance claims, feature descriptions |
+| Core Rules | `rules/CORE.md` | Orchestrator identity, command routing |
+| HSOL Assessment | `documents/HSOL-ASSESSMENT.md` | Skill layer strengths and gaps |
+| Package manifest | `package.json` | Version, scripts, platform configuration |
+| Agents directory | `agents/*.md` | Agent count and scope |
+| Commands directory | `commands/*.md` | Command count and variant coverage |
+| Matrix Skills | `matrix-skills/*.yaml` | Skill count and domain enumeration |
+| Teams directory | `agents/teams/` | Team configuration count |

package/documents/business/business-prd/03-stakeholders-and-requirements.md

@@ -0,0 +1,210 @@
+# Agent Assistant — Stakeholders and Requirements
+
+> **Purpose**: Stakeholder map with goals and touchpoints, functional requirements (BR-001–BR-023), non-functional requirements, and traceability to business goals
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Stakeholder Map
+
+### S1: Framework User (Individual Developer)
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | Primary user of the framework |
+| **Description** | Software developer using one or more AI coding assistants daily for building, debugging, testing, and deploying software |
+| **Primary Goals** | BG-001 (one-time setup), BG-003 (faster delivery), BG-006 (structured workflows) |
+| **Secondary Goals** | BG-004 (fewer bugs), BG-005 (lower token cost) |
+| **Touchpoints** | CLI installer (`agent-assistant install --all`), slash commands (`/cook`, `/fix`, `/plan`, `/test`, `/review`), natural language input |
+| **Success Criteria** | Installs in ≤5 minutes; commands produce usable deliverables without prompt iteration |
+| **Pain Points Addressed** | Repetitive prompt engineering, inconsistent AI output, no workflow structure |
+
+### S2: Framework User (Team/Organization)
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | Team lead or organization standardizing AI-assisted development |
+| **Description** | Uses `:hard` and `:team` command variants to enforce quality governance and adversarial review across team members |
+| **Primary Goals** | BG-002 (consistent practices), BG-004 (fewer bugs) |
+| **Secondary Goals** | BG-003 (faster delivery), BG-008 (adversarial collaboration) |
+| **Touchpoints** | `:team` variant commands, Mailbox logs (`MAILBOX-{date}.md`), Golden Triangle protocol, `:hard` variants |
+| **Success Criteria** | ≥80% team adoption within 30 days; measurably fewer defects than solo agent workflows |
+| **Pain Points Addressed** | Inconsistent AI practices across team, no audit trail, no review process for AI output |
+
+### S3: Skill Author
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | Creator and publisher of domain skills |
+| **Description** | Developer who builds reusable skills following the SKILL.md template and publishes them to the community ecosystem via skills.sh |
+| **Primary Goals** | BG-009 (community ecosystem) |
+| **Secondary Goals** | BG-010 (extensibility) |
+| **Touchpoints** | SKILL.md template, `npx skills` CLI, skills.sh platform, `_dynamic.yaml` registration, Trust Progression Lifecycle |
+| **Success Criteria** | Published skill discoverable via `find-skills`; trust progresses through lifecycle stages |
+| **Pain Points Addressed** | No standard format for sharing AI workflow knowledge |
+
+### S4: AI Model (Runtime)
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | Execution engine — reads and follows framework instructions |
+| **Description** | The AI model (GPT-4, Claude, Gemini, etc.) loaded by the coding assistant. It reads the platform entry point, ingests rules and agent files, and executes the Orchestrator pattern. |
+| **Primary Goals** | BG-007 (auto skill injection) |
+| **Secondary Goals** | BG-003 (efficiency), BG-004 (quality) |
+| **Touchpoints** | Platform entry points (CLAUDE.md, COPILOT.md, CURSOR.md, CODEX.md, GEMINI.md), CORE.md, agent files, HSOL matrix |
+| **Success Criteria** | Correctly delegates to specialist agents (never implements directly) in ≥95% of invocations |
+| **Pain Points Addressed** | Default generalist behavior; no role specialization; no governance guardrails |
+
+### S5: Platform Maintainer
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | AI tool developer ensuring platform compatibility |
+| **Description** | Developer at Cursor, GitHub, Anthropic, OpenAI, or Google who maintains the AI tool's file-based instruction loading mechanism |
+| **Primary Goals** | BG-002 (multi-platform support) |
+| **Secondary Goals** | BG-009 (framework quality) |
+| **Touchpoints** | `install.js` platform configuration, entry point templates, platform file structure |
+| **Success Criteria** | Framework installs and loads correctly on their platform |
+| **Pain Points Addressed** | Third-party frameworks breaking on platform updates |
+
+### S6: Framework Maintainer (NamCH)
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | Creator, primary maintainer, and release manager |
+| **Description** | Evolves the framework architecture, manages npm releases via semantic-release, and governs the skill ecosystem quality |
+| **Primary Goals** | BG-009 (quality/release cadence), BG-010 (extensibility) |
+| **Secondary Goals** | BG-002 (multi-platform), BG-007 (community ecosystem) |
+| **Touchpoints** | All source code, CI/CD pipeline (semantic-release + husky), npm registry, GitHub repository |
+| **Success Criteria** | ≥1 minor release per quarter; 0 regressions per release |
+| **Pain Points Addressed** | Maintaining quality across growing codebase and community contributions |
+
+### S7: Contributor
+
+| Attribute | Detail |
+|-----------|--------|
+| **Role** | Open-source contributor |
+| **Description** | Adds agents, commands, skills, documentation, or platform support to the framework |
+| **Primary Goals** | BG-010 (extensibility) |
+| **Secondary Goals** | BG-009 (community ecosystem) |
+| **Touchpoints** | AGENT-TEMPLATE.md, command file conventions, SKILL.md template, contribution guidelines |
+| **Success Criteria** | New agent or command addable in ≤2 hours using provided templates |
+| **Pain Points Addressed** | High friction to contribute to AI workflow tooling |
+
+---
+
+## Functional Requirements
+
+### Core Infrastructure
+
+| Req ID | Requirement | Priority | INVEST Score | Stakeholders | Goals |
+|--------|-------------|----------|-------------|--------------|-------|
+| BR-001 | Framework installs globally via `npm install -g` and writes platform-specific config files to `~/.{TOOL}/skills/agent-assistant/` | Must | 29/30 | S1, S2 | BG-001, BG-002 |
+| BR-002 | Framework supports 5 platforms: Cursor, Copilot, Claude Code, Codex, Antigravity/Gemini | Must | 24/30 | S5 | BG-002 |
+| BR-023 | CLI list command shows installed platforms and status | Should | 27/30 | S1 | BG-001 |
+
+**Acceptance Criteria (BR-001)**: Given a clean machine with Node.js 18+, when user runs `npm install -g @namch/agent-assistant && agent-assistant install --all`, then config files exist at `~/.cursor/`, `~/.copilot/`, `~/.claude/`, `~/.codex/`, `~/.gemini/antigravity/` and exit code is 0.
+
+**Acceptance Criteria (BR-002)**: Given the framework is installed, when user runs `agent-assistant install {platform}` for each platform, then each platform's entry point file is created and the orchestrator instructions are loadable by that platform's AI runtime.
+
+### Agent System
+
+| Req ID | Requirement | Priority | INVEST Score | Stakeholders | Goals |
+|--------|-------------|----------|-------------|--------------|-------|
+| BR-003 | AI runtime acts as Orchestrator: receives user request, detects command, delegates to specialist agents | Must | 21/30 | S4 | BG-003, BG-006 |
+| BR-004 | 21 specialist agents available with distinct roles, profiles, and handoff chains | Must | 23/30 | S1, S4 | BG-004, BG-010 |
+| BR-005 | 17 domain teams available via `:team` variant using Golden Triangle (Tech Lead + Executor + Reviewer) | Should | 23/30 | S2 | BG-002, BG-008 |
+| BR-021 | Cognitive anchoring ensures each agent file overrides default AI patterns | Must | 20/30 | S4, S6 | BG-004 |
+
+**Acceptance Criteria (BR-004)**: Given the agents directory, when any agent file is loaded, then it contains: name, description, profile, category, Thinking Protocol, Constraints, and Output Format sections, and each agent has a unique profile tag.
+
+### Command System
+
+| Req ID | Requirement | Priority | INVEST Score | Stakeholders | Goals |
+|--------|-------------|----------|-------------|--------------|-------|
+| BR-006 | 14 structured commands available (`/cook`, `/fix`, `/plan`, `/debug`, `/test`, `/review`, `/docs`, `/design`, `/deploy`, `/report`, `/brainstorm`, `/ask`, `/code`, `/auto`) | Must | 25/30 | S1 | BG-006 |
+| BR-007 | 4 variant strategies per command: `fast`, `hard`, `team` | Should | 26/30 | S1 | BG-006 |
+| BR-015 | Natural language command detection maps free-text to structured commands | Must | 27/30 | S1 | BG-006 |
+| BR-016 | Plan-already-provided short-circuit skips planning when user supplies a plan | Should | 28/30 | S1 | BG-003, BG-005 |
+| BR-017 | Documentation generation via `/docs` creates knowledge, business, and audit docs | Should | 23/30 | S1, S6 | BG-010 |
+| BR-018 | Deployment workflows via `/deploy` with variants: check, preview, production, rollback | Could | 24/30 | S1 | BG-006 |
+| BR-019 | Autonomous execution via `/auto` analyzes task and runs full workflow without intervention | Could | 21/30 | S1 | BG-003 |
+| BR-020 | Reporting system via `/report` generates structured analysis reports | Could | 25/30 | S1, S2 | BG-006 |
+
+**Acceptance Criteria (BR-006)**: Given the commands directory, when each command is invoked, then a workflow file is loaded with PRE-FLIGHT, phases, agent assignments, and exit criteria, and the orchestrator follows sequential phase execution (L5).
+
+### Skill System
+
+| Req ID | Requirement | Priority | INVEST Score | Stakeholders | Goals |
+|--------|-------------|----------|-------------|--------------|-------|
+| BR-008 | Matrix Skill Discovery (HSOL) resolves skills from 1,430 pre-curated matrix skills across 19 domains | Must | 21/30 | S4 | BG-007 |
+| BR-009 | Dynamic Skill Discovery via `find-skills` searches and installs community skills when matrix fitness < 0.75 | Could | 24/30 | S3, S7 | BG-007, BG-009 |
+| BR-010 | Trust Progression Lifecycle: skills progress NEW(0.3) → EVALUATING(0.5) → VALIDATED(0.7) → PROMOTED(1.0) | Could | 25/30 | S6 | BG-009 |
+
+**Acceptance Criteria (BR-008)**: Given a complex task, when HSOL runs resolution, then fitness score is calculated using the 5-factor formula (semantic 0.35, specificity 0.25, trust 0.20, freshness 0.10, success 0.10) and skills with fitness ≥0.8 are injected.
+
+### Governance and Resilience
+
+| Req ID | Requirement | Priority | INVEST Score | Stakeholders | Goals |
+|--------|-------------|----------|-------------|--------------|-------|
+| BR-011 | Tiered Execution: TIER 1 (sub-agent) mandatory when available; TIER 2 (embody) fallback only | Must | 24/30 | S4 | BG-003, BG-005 |
+| BR-012 | 10 Orchestration Laws (L1–L10) enforced at runtime | Must | 19/30 | S4, S6 | BG-004, BG-006 |
+| BR-013 | Error self-healing (E1–E4) with classification and recovery protocols | Should | 24/30 | S4 | BG-004 |
+| BR-014 | Debate mechanism via Mailbox (append-only log) for team variant | Should | 22/30 | S2 | BG-008 |
+| BR-022 | Language compliance (L6): responses in user's language, code/files always in English | Should | 27/30 | S1, S2 | BG-006 |
+
+**Acceptance Criteria (BR-012)**: Given the orchestrator is operating, when any action occurs, then all 10 laws are observed: L1 (single truth), L2 (requirement integrity), L3 (explicit loading), L4 (deep embodiment), L5 (sequential execution), L6 (language compliance), L7 (recursive delegation), L8 (stateful handoff), L9 (constraint propagation), L10 (deliverable integrity).
+
+---
+
+## Non-Functional Requirements
+
+| NFR ID | Category | Requirement | Target | Evidence |
+|--------|----------|-------------|--------|----------|
+| NFR-001 | Performance | CLI installation completes within 5 minutes for all platforms | ≤5 min end-to-end | `cli/install.js` — file copy operations only, no network calls |
+| NFR-002 | Portability | Framework operates on macOS, Linux, and Windows with Node.js 18+ | 3 OS families supported | `cli/install.js` uses `os.homedir()` and `path.join()` for cross-platform paths |
+| NFR-003 | Dependency | Zero production dependencies | 0 entries in `dependencies` | `package.json` — only `devDependencies` present |
+| NFR-004 | Maintainability | Agent and command files follow standard templates | AGENT-TEMPLATE.md, command file conventions | `AGENT-TEMPLATE.md`, `commands/*.md` |
+| NFR-005 | Extensibility | New agent addable in ≤2 hours using template | Follow AGENT-TEMPLATE.md | Templates and directory conventions documented |
+| NFR-006 | Compatibility | Framework files loadable by all 5 supported AI tool runtimes | 5/5 platforms load entry points correctly | Platform entry point files tested per platform |
+| NFR-007 | Idempotency | Install and uninstall operations are idempotent | Re-running install/uninstall produces same result | `cli/install.js` overwrites existing files |
+| NFR-008 | Internationalization | AI responses match user's language; all generated files in English | L6 compliance | `rules/CORE.md` — L6 law definition |
+| NFR-009 | Resilience | Error recovery covers 4 classification levels (E1–E4) | All error types have defined recovery | `rules/ERRORS.md` |
+| NFR-010 | Scalability | Matrix skills scalable to additional domains without architecture change | Add new YAML file to `matrix-skills/` | `matrix-skills/_index.yaml` — declarative domain registry |
+
+---
+
+## Traceability Matrix
+
+| Goal | Requirements | Features | Workflows | KPI |
+|------|-------------|----------|-----------|-----|
+| BG-001 | BR-001, BR-023 | BF-001, BF-023 | BW-001, BW-002 | Install success ≥99%; zero per-project config |
+| BG-002 | BR-001, BR-002, BR-005, BR-007 | BF-001, BF-002, BF-005, BF-007 | BW-001, BW-003, BW-008 | 5/5 platforms; ≥80% team adoption |
+| BG-003 | BR-003, BR-006, BR-008, BR-016, BR-019 | BF-003, BF-006, BF-008, BF-016, BF-019 | BW-003, BW-005, BW-011 | ≥70% time reduction (unvalidated) |
+| BG-004 | BR-004, BR-005, BR-012, BR-013, BR-014, BR-021 | BF-004, BF-005, BF-012, BF-013, BF-014, BF-021 | BW-004, BW-008, BW-010 | ≥70% bug reduction (unvalidated) |
+| BG-005 | BR-003, BR-008, BR-011, BR-016 | BF-003, BF-008, BF-011, BF-016 | BW-003, BW-005, BW-011 | ≤85% token reduction (unvalidated) |
+| BG-006 | BR-003, BR-006, BR-007, BR-015, BR-022 | BF-003, BF-006, BF-007, BF-015, BF-022 | BW-003 | 14 commands × 4 variants |
+| BG-007 | BR-008, BR-009, BR-010 | BF-008, BF-009, BF-010 | BW-005, BW-006, BW-007 | HSOL fitness ≥0.8; auto-injection |
+| BG-008 | BR-005, BR-014 | BF-005, BF-014 | BW-008 | Golden Triangle active; ≤3 debate rounds |
+| BG-009 | BR-009, BR-010 | BF-009, BF-010 | BW-006, BW-007 | Trust lifecycle; ≥50 community skills/year |
+| BG-010 | BR-004, BR-006, BR-017 | BF-004, BF-006, BF-017 | BW-004, BW-009, BW-012 | New agent in ≤2 hours; /docs produces all folders |
+
+---
+
+## Evidence Sources
+
+| Source | Path | Used For |
+|--------|------|----------|
+| Structured Business Pack | `reports/business-analysis/structured-business-pack.md` | Requirements (BR-001–BR-023), INVEST scores, acceptance criteria, stakeholder mapping, traceability matrix |
+| Package manifest | `package.json` | Dependency count (NFR-003), platform scripts, version |
+| Core Rules | `rules/CORE.md` | Orchestration laws (BR-012), tiered execution (BR-011), command routing (BR-006) |
+| HSOL Assessment | `documents/HSOL-ASSESSMENT.md` | Skill resolution rules (BR-008), trust progression (BR-010) |
+| Features documentation | `documents/knowledge-overview/03-features.md` | Feature evidence, platform table |
+| Agent template | `AGENT-TEMPLATE.md` | Extensibility evidence (NFR-005) |
+| Agents directory | `agents/*.md` | Agent count (BR-004), team count (BR-005) |
+| Commands directory | `commands/*.md`, `commands/*/` | Command count (BR-006), variant structure (BR-007) |
+| Matrix Skills | `matrix-skills/*.yaml`, `matrix-skills/_index.yaml` | Skill count (BR-008), domain coverage |
+| Error rules | `rules/ERRORS.md` | Error classification (BR-013, NFR-009) |
+| Teams rules | `rules/TEAMS.md` | Golden Triangle protocol (BR-005, BR-014) |