@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-features/03-feature-specifications.md

@@ -0,0 +1,511 @@
+# Agent Assistant — Feature Specifications
+
+> **Purpose**: Per-feature specifications with acceptance criteria (Given/When/Then), technical surface, and dependency details
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## Specification Format
+
+Each feature specification includes:
+- **BF-ID**: Unique feature identifier
+- **Description**: What it does and why
+- **Acceptance Criteria**: Given/When/Then scenarios
+- **Technical Surface**: Files and modules involved
+- **Dependencies**: Hard and soft dependencies on other features
+
+---
+
+## Must Have Features
+
+### BF-001 — One-Time Global Installation
+
+**Description**: CLI installs framework files into the AI tool's global config directory. One installation per platform, zero per-project configuration.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Node.js >=18 and npm are available | User runs `npm run install:all` | All 5 platform directories are populated with agents, commands, rules, skills, matrix-skills |
+| AC-2 | User has Cursor installed | User runs `npm run install:cursor` | `~/.cursor/skills/agent-assistant/` contains all framework files |
+| AC-3 | Framework is already installed | User opens a new project in Cursor | Agent-assistant is available without any project-level setup |
+| AC-4 | One platform fails | User runs `install --all` | Other platforms install successfully; failed platform reports error |
+
+**Technical Surface**:
+- `cli/install.js` — Installer logic, platform path configs, template variable replacement
+- `package.json` — npm scripts (`install:cursor`, `install:copilot`, `install:claude`, `install:codex`, `install:antigravity`, `install:all`)
+
+**Dependencies**: Node.js >=18, npm (external)
+
+---
+
+### BF-002 — Multi-Platform Support (5 Platforms)
+
+**Description**: Same agent definitions, commands, and skills work identically across Cursor, Copilot, Claude Code, Codex, and Antigravity/Gemini.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Framework installed on all 5 platforms | User issues `/cook:fast` on each platform | Same agent delegation pattern executes on each |
+| AC-2 | Source files use `{TOOL}` placeholder | CLI runs installation | Placeholders are replaced with platform-specific values |
+| AC-3 | Platform entry file exists (CURSOR.md, etc.) | AI tool starts a session | CORE.md is loaded via the platform's discovery mechanism |
+
+**Technical Surface**:
+- `cli/install.js` — `TOOLS` configuration object with platform paths
+- `code-assistants/cursor-assistant/`, `code-assistants/copilot-assistant/`, `code-assistants/claude-assistant/`, `code-assistants/codex-assistant/`, `code-assistants/antigravity-assistant/`
+- `CURSOR.md`, `COPILOT.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`
+
+**Dependencies**: BF-001 (installation mechanism)
+
+---
+
+### BF-003 — Orchestrator Pattern
+
+**Description**: AI assumes Orchestrator role — delegates to specialists, never implements directly. Enforced by mandatory boot sequence in CORE.md.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Session started with CORE.md loaded | User asks "implement a REST API" | Orchestrator delegates to backend-engineer; does not write code itself |
+| AC-2 | CORE.md loaded | Orchestrator is about to execute code | Self-check fires and delegation occurs instead |
+| AC-3 | Platform entry file loaded | Session begins | CORE.md is loaded before any other action via mandatory boot sequence |
+
+**Technical Surface**:
+- `rules/CORE.md` — Identity section, self-check protocol, prohibition statements
+- Platform entry files — Mandatory boot sequence that loads CORE.md
+
+**Dependencies**: CORE.md available in platform install directory
+
+---
+
+### BF-004 — 21 Specialist Agents
+
+**Description**: Each agent is a Markdown file with defined profile, directive, protocol, and constraints. HSOL injects skills based on the agent's profile.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Agent file exists with profile section | Orchestrator delegates a task | Agent's profile, directive, and constraints are applied |
+| AC-2 | Agent has cognitive anchor block | Agent executes a multi-step task | Role identity is maintained across all steps |
+| AC-3 | 21 agent files in `agents/` | Installation completes | All 21 agents are available for delegation |
+| AC-4 | Agent defines skill profile | HSOL resolves skills | Skills matching the profile's domains are injected |
+
+**Technical Surface**:
+- `agents/*.md` — 21 agent definition files
+- `AGENT-TEMPLATE.md` — Template format for agent creation
+- `agents/teams/` — 17 team directories with 51 team-specific agent files
+
+**Dependencies**: BF-003 (Orchestrator must exist to delegate)
+
+---
+
+### BF-005 — 14 Structured Commands
+
+**Description**: Workflow definitions that orchestrate agent collaboration across phases. Each command specifies routing, phases, agents, and exit criteria.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | 14 command files in `commands/` | User issues any of the 14 commands | Correct command file is loaded and routing logic executes |
+| AC-2 | Command has variant subdirectory | User specifies `:hard` variant | Variant-specific workflow (phases, agents, gates) is applied |
+| AC-3 | Rules pre-flight completes | Command execution begins | CORE.md laws are active before any phase runs |
+
+**Technical Surface**:
+- `commands/*.md` — 14 command files (ask, auto, brainstorm, code, cook, debug, deploy, design, docs, fix, plan, report, review, test)
+- `commands/*/` — Variant subdirectories per command
+
+**Dependencies**: BF-003 (Orchestrator routes commands), BF-004 (agents execute phases)
+
+---
+
+### BF-006 — 3 Variant Strategies
+
+**Description**: `:fast` (2–3 agents), `:hard` (5–8 agents + gates), `:team` (adversarial Golden Triangle).
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | `/cook` command issued | User specifies `:fast` | 2–3 agents execute with basic quality gates |
+| AC-2 | `/cook` command issued | User specifies `:hard` | 5–8 agents execute with test, review, and security gates |
+| AC-3 | `/cook` command issued | User specifies `:team` | Golden Triangle team (Tech Lead + Executor + Reviewer) with debate |
+
+**Technical Surface**:
+- `commands/cook/fast.md`, `commands/cook/hard.md`, `commands/cook/team.md`
+- Pattern replicated for each command supporting variants
+
+**Dependencies**: BF-005 (command router)
+
+---
+
+### BF-007 — Matrix Skill Discovery (HSOL)
+
+**Description**: Automatic skill resolution based on agent profile. 1,430+ skills across 19 domains. Fitness scoring: semantic 35%, specificity 25%, trust 20%, freshness 10%, success 10%.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Agent has profile with backend domain | HSOL resolves skills | Backend-relevant skills from `matrix-skills/backend.yaml` are injected |
+| AC-2 | 19 domain YAML files exist | HSOL resolution runs | All domains are searchable; `_index.yaml` is the entry point |
+| AC-3 | Fitness score computed | Score >= 0.8 | Skill is included in the resolved set |
+| AC-4 | Fitness score computed | Score < 0.8 in `:hard`/`:team` | Dynamic discovery (BF-013) may trigger |
+
+**Technical Surface**:
+- `rules/SKILLS.md` — Resolution algorithm, fitness scoring, thresholds
+- `matrix-skills/_index.yaml` — Master index of domains and inheritance
+- `matrix-skills/*.yaml` — 19 domain registry files
+- `skills/` — 1,430+ skill module directories
+
+**Dependencies**: BF-004 (agent profiles provide input to HSOL)
+
+---
+
+### BF-008 — Tiered Execution
+
+**Description**: TIER 1 uses `runSubagent` for isolated parallel execution. TIER 2 falls back to in-context embodiment. TIER 1 is mandatory when available.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Platform supports `runSubagent` (Claude Code) | Orchestrator delegates to 3 agents | 3 sub-agents execute in parallel |
+| AC-2 | Platform lacks `runSubagent` (some Copilot modes) | Orchestrator delegates | TIER 2 embodiment used; agents execute sequentially in-context |
+| AC-3 | TIER 1 is available | Orchestrator selects execution tier | TIER 1 is selected (TIER 2 forbidden when TIER 1 available) |
+
+**Technical Surface**:
+- `rules/CORE.md` — Tiered Execution section
+- `rules/AGENTS.md` — Agent execution protocol
+
+**Dependencies**: BF-003 (Orchestrator manages execution tier selection)
+
+---
+
+### BF-009 — 10 Orchestration Laws
+
+**Description**: Formal governance — L1 (Single Truth), L2 (Requirement Integrity), L3 (Phase Completion), L4 (Agent Specialization), L5 (Transparent Delegation), L6 (No Silent Failures), L7 (Skill Authority), L8 (Output Verification), L9 (Context Preservation), L10 (Minimal Intervention).
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | CORE.md loaded | Orchestrator operates | All 10 laws are actively enforced |
+| AC-2 | An error occurs during execution | Error is encountered | Law L6 ensures error is surfaced (no silent failure) |
+| AC-3 | Agent handoff occurs | Context transfers between agents | Law L9 ensures context is preserved |
+| AC-4 | Orchestrator receives implementation task | Self-check runs | Law L10 triggers delegation instead of direct implementation |
+
+**Technical Surface**:
+- `rules/CORE.md` — Laws section (all 10 laws)
+
+**Dependencies**: BF-003 (laws govern the Orchestrator)
+
+---
+
+### BF-010 — Cognitive Anchoring
+
+**Description**: Structured identity block in every agent file that reinforces role, expertise, and boundaries at execution start.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Agent file has cognitive anchor block | Agent begins execution | Identity section is processed before task execution |
+| AC-2 | Long session with many agent switches | Agent re-activated after other agents | Cognitive anchor refreshes role identity; no drift |
+| AC-3 | New agent created from template | Developer follows AGENT-TEMPLATE.md | Cognitive anchor block is included in the new agent |
+
+**Technical Surface**:
+- `agents/*.md` — Cognitive anchor block in each file
+- `AGENT-TEMPLATE.md` — Template with anchor block structure
+
+**Dependencies**: BF-004 (agent file format)
+
+---
+
+## Should Have Features
+
+### BF-011 — 17 Domain Teams (Golden Triangle)
+
+**Description**: Adversarial collaboration — Tech Lead + Executor + Reviewer per team. 17 teams covering backend through report domains.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | `:team` variant invoked | `/cook:team` executed | Golden Triangle protocol activates with 3 agents |
+| AC-2 | Team selected | Execution begins | Tech Lead decomposes, Executor builds, Reviewer challenges |
+| AC-3 | Reviewer finds issues | Review submitted | Executor must defend or fix before acceptance |
+| AC-4 | 17 team directories exist | Installation complete | All teams are available for `:team` variant |
+
+**Technical Surface**:
+- `rules/TEAMS.md` — Full protocol (530+ lines)
+- `agents/teams/*/` — 17 directories × 3 files (techlead.md, executor.md, reviewer.md)
+- `rules/PHASES.md`, `rules/AGENTS.md` — Team execution support
+
+**Dependencies**: BF-006 (`:team` variant), BF-004 (agents)
+
+---
+
+### BF-012 — Error Self-Healing (E1–E4)
+
+**Description**: Classified recovery — E1 auto-retry, E2 fallback, E3 user pause, E4 halt with diagnostics.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | E1 warning occurs | Error classified | Auto-retry with adjusted parameters |
+| AC-2 | E2 recoverable error occurs | TIER 1 fails | TIER 2 fallback activates |
+| AC-3 | E3 blocking error occurs | Missing user input | Execution pauses; user prompted for clarification |
+| AC-4 | E4 critical error occurs | Unrecoverable state | Execution halts; full diagnostic report generated |
+
+**Technical Surface**:
+- `rules/ERRORS.md` — Error classification, recovery protocols
+
+**Dependencies**: None (standalone rules file)
+
+---
+
+### BF-013 — Dynamic Skill Discovery
+
+**Description**: When fitness < 0.8 in `:hard`/`:team`, `find-skills` discovers community skills. Tracked in `_dynamic.yaml`.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | HSOL fitness < 0.8 for a domain | `:hard` variant executes | Dynamic discovery triggers and searches for community skills |
+| AC-2 | Community skill found | Skill registered | Entry added to `matrix-skills/_dynamic.yaml` with NEW trust status |
+| AC-3 | Network unavailable | Dynamic discovery triggers | Graceful degradation — uses best available bundled skill |
+
+**Technical Surface**:
+- `rules/SKILLS.md` — Dynamic discovery section
+- `matrix-skills/_dynamic.yaml` — Dynamic skill manifest
+
+**Dependencies**: BF-007 (HSOL fitness scoring active)
+
+---
+
+### BF-014 — Trust Progression Lifecycle
+
+**Description**: NEW → EVALUATING → VALIDATED → PROMOTED lifecycle for dynamically discovered skills.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Skill registered as NEW | First successful execution | Status advances to EVALUATING |
+| AC-2 | Skill in EVALUATING state | Consistent success across multiple uses | Status advances to VALIDATED |
+| AC-3 | Skill VALIDATED | Trust score meets threshold | Status advances to PROMOTED; skill ranks alongside core skills |
+| AC-4 | Skill fails validation | Poor outcomes | Status remains or reverts; skill does not advance |
+
+**Technical Surface**:
+- `rules/SKILLS.md` — Trust lifecycle section
+- `matrix-skills/_dynamic.yaml` — Status tracking per skill
+
+**Dependencies**: BF-013 (skills must be discovered first)
+
+---
+
+### BF-015 — Documentation Generation (/docs)
+
+**Description**: Auto-generates structured docs: Core (5 folders), Business (4+ folders), Audit (4 folders). Uses scouter, business-analyst, and docs-manager agents.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Project has source code | User runs `/docs` | Scouter discovers project structure; docs-manager generates documentation |
+| AC-2 | `/docs` targets business pack | Business subfolder specified | Business-analyst extracts goals, requirements, features from project |
+| AC-3 | Documentation exists | User runs `/docs` again | Existing docs are updated, not overwritten |
+
+**Technical Surface**:
+- `commands/docs.md` — Main routing
+- `commands/docs/*.md` — Variants
+- `agents/docs-manager.md`, `agents/scouter.md`, `agents/business-analyst.md`
+
+**Dependencies**: BF-004 (scouter, BA, docs-manager agents), BF-005 (`/docs` command)
+
+---
+
+### BF-016 — Debate Mechanism (Mailbox)
+
+**Description**: Append-only mailbox for team communication. Message types: TASK_ASSIGNMENT, SUBMISSION, REVIEW, DEFENSE, ARBITRATION, DECISION. Max 3 rounds.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | `:team` variant executing | Reviewer submits critique | Message appended to `./reports/{topic}/MAILBOX-{date}.md` |
+| AC-2 | 3 debate rounds completed | No consensus reached | Tech Lead issues binding ARBITRATION decision |
+| AC-3 | Executor defends | Defense is accepted | DECISION logged; execution proceeds |
+| AC-4 | Mailbox file exists | All messages appended | Full debate trail is preserved and auditable |
+
+**Technical Surface**:
+- `rules/TEAMS.md` — Mailbox protocol, message types, round limits
+
+**Dependencies**: BF-011 (teams must be active)
+
+---
+
+### BF-017 — Natural Language Command Detection
+
+**Description**: Maps plain language intent to commands. "implement" → `/cook`, "fix" → `/fix`, "plan" → `/plan`.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | User says "build a login page" | Orchestrator parses intent | Routes to `/cook` or `/code` command |
+| AC-2 | User says "fix this bug" | Orchestrator parses intent | Routes to `/fix` command |
+| AC-3 | User says "review my code" | Orchestrator parses intent | Routes to `/review` command |
+| AC-4 | Ambiguous intent | Orchestrator cannot classify | Asks user to clarify or defaults to `/ask` |
+
+**Technical Surface**:
+- `rules/CORE.md` — Command routing section, natural language mapping table
+
+**Dependencies**: BF-005 (commands must exist to route to)
+
+---
+
+### BF-018 — Language Compliance (L6)
+
+**Description**: Responses in user's language. Code, comments, generated files always in English.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | User writes in Portuguese | Orchestrator responds | Response is in Portuguese |
+| AC-2 | Agent generates code | Code produced | Comments and variable names are in English |
+| AC-3 | `/docs` generates files | Files created | All file content is in English regardless of user language |
+
+**Technical Surface**:
+- `rules/CORE.md` — Law L6, language compliance section
+
+**Dependencies**: None (CORE.md law)
+
+---
+
+## Could Have Features
+
+### BF-019 — Deployment Workflows (/deploy)
+
+**Description**: 4 deployment variants — check, preview, production, rollback.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | User runs `/deploy:check` | Pre-deployment validation | Environment, config, and dependencies validated |
+| AC-2 | User runs `/deploy:preview` | Staging deploy | Application deployed to preview/staging environment |
+| AC-3 | User runs `/deploy:production` | Production release | Application deployed to production with configured safeguards |
+| AC-4 | User runs `/deploy:rollback` | Revert needed | Previous stable version restored |
+
+**Technical Surface**:
+- `commands/deploy.md`, `commands/deploy/*.md`
+- `agents/devops-engineer.md`
+
+**Dependencies**: BF-004 (devops-engineer agent)
+
+---
+
+### BF-020 — Autonomous Execution (/auto)
+
+**Description**: Self-routing execution — tech-lead classifies task and selects command/variant without user pauses.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | User issues `/auto` with task description | Tech-lead classifies | Correct command and variant selected automatically |
+| AC-2 | Classification complete | Execution begins | Full workflow runs without phase-boundary pauses |
+| AC-3 | Task is ambiguous | Classification uncertain | Falls back to user prompt for clarification |
+
+**Technical Surface**:
+- `commands/auto.md`
+- `agents/tech-lead.md`
+
+**Dependencies**: BF-004 (tech-lead), BF-005 (all commands available for routing)
+
+---
+
+### BF-021 — Reporting System (/report)
+
+**Description**: Generates status reports, sprint summaries, and analysis. Reporter + scouter agents.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | User runs `/report` | Report generated | Report reflects current project state |
+| AC-2 | Previous report exists | User runs `/report` again | Report is updated, not duplicated |
+| AC-3 | Template specified | Report generation | Output follows template structure |
+
+**Technical Surface**:
+- `commands/report.md`, `commands/report/*.md`
+- `agents/reporter.md`, `agents/scouter.md`
+
+**Dependencies**: BF-004 (reporter, scouter agents)
+
+---
+
+### BF-022 — Plan Short-Circuit
+
+**Description**: Skip research/scout/brainstorm phases when existing plan is referenced.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | User says "follow the plan" and PLAN-*.md exists | `/code:hard` executes | Phases 1–3 skipped; execution starts at context optimization |
+| AC-2 | User references `@PLAN-feature.md` | Plan file found | Plan content loaded; research skipped |
+| AC-3 | User says "follow plan" but no PLAN-*.md exists | Detection runs | No short-circuit; normal phase sequence executes |
+
+**Technical Surface**:
+- `commands/code.md` — Detection routing
+- `commands/code/hard.md`, `commands/code/team.md` — Skip logic section
+
+**Dependencies**: BF-005 (`/code` command)
+
+---
+
+### BF-023 — CLI List Command
+
+**Description**: Show installed platforms, versions, and status via CLI.
+
+**Acceptance Criteria**:
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-1 | Framework installed on 3 of 5 platforms | User runs CLI list | 3 platforms show as installed; 2 show as not installed |
+| AC-2 | No platforms installed | User runs CLI list | All platforms show as not installed |
+
+**Technical Surface**:
+- `cli/install.js` — Planned addition
+
+**Dependencies**: BF-001 (CLI exists)
+
+**Status**: NOT YET IMPLEMENTED
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Structured Business Pack | [../../reports/business-analysis/structured-business-pack.md](../../reports/business-analysis/structured-business-pack.md) |
+| Knowledge overview — features | [../knowledge-overview/03-features.md](../knowledge-overview/03-features.md) |
+| CORE rules | [../../rules/CORE.md](../../rules/CORE.md) |
+| SKILLS rules | [../../rules/SKILLS.md](../../rules/SKILLS.md) |
+| TEAMS rules | [../../rules/TEAMS.md](../../rules/TEAMS.md) |
+| ERRORS rules | [../../rules/ERRORS.md](../../rules/ERRORS.md) |
+| AGENTS rules | [../../rules/AGENTS.md](../../rules/AGENTS.md) |
+| CLI installer | [../../cli/install.js](../../cli/install.js) |
+| Commands | [../../commands/](../../commands/) |
+| Agent definitions | [../../agents/](../../agents/) |