@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/business/business-features/02-prioritization-moscow.md

@@ -0,0 +1,148 @@
+# Agent Assistant — MoSCoW Prioritization
+
+> **Purpose**: MoSCoW classification of all 23 features with rationale, dependency analysis, and priority justification
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-business skill
+
+---
+
+## MoSCoW Summary
+
+| Priority | Count | Features | Rationale |
+|----------|-------|----------|-----------|
+| **Must Have** | 10 | BF-001–BF-010 | Core framework — without these, the product has no value proposition |
+| **Should Have** | 8 | BF-011–BF-018 | Significant quality and ecosystem enhancements — differentiate from basic prompt engineering |
+| **Could Have** | 5 | BF-019–BF-023 | Convenience and automation — valuable but not required for core workflows |
+| **Won't Have** | 0 | — | No features deferred from v1.3.0 scope |
+
+---
+
+## Must Have (10) — Core Framework
+
+These features are non-negotiable. Without any one of them, the framework cannot deliver its primary value proposition of structured multi-agent orchestration.
+
+| BF-ID | Feature | Rationale | Dependencies | Delivered |
+|-------|---------|-----------|-------------|-----------|
+| BF-001 | One-Time Global Installation | Entry point to the framework. Without installation, nothing works. Zero-config is the fundamental UX promise. | Node.js >=18, npm | v1.0.0 |
+| BF-002 | Multi-Platform Support (5) | Platform coverage is a stated product goal (BG-002). Single-platform would limit addressable market to one tool's users. | BF-001 (CLI platform config) | v1.0.0–v1.2.0 |
+| BF-003 | Orchestrator Pattern | The defining architectural decision. If the AI implements directly, there is no orchestration — just a chatbot with extra prompts. | CORE.md loaded at boot | v1.0.0 |
+| BF-004 | 21 Specialist Agents | Agents are the execution workforce. Without specialists, the Orchestrator has nobody to delegate to. Agent profiles drive HSOL skill injection. | BF-003 (pattern requires agents) | v1.0.0 |
+| BF-005 | 14 Structured Commands | Commands are the user interface to the framework. Without commands, users have no structured entry point to workflows. | BF-003 (Orchestrator routes), BF-004 (agents execute) | v1.0.0 |
+| BF-006 | 4 Variant Strategies | Variants enable right-sizing — without them, every task gets the same treatment regardless of complexity. `:fast` vs `:hard` is a core efficiency mechanism. | BF-005 (command router logic) | v1.0.0–v1.0.4 |
+| BF-007 | Matrix Skill Discovery (HSOL) | Skill injection is the knowledge layer. Without HSOL, agents operate on generic training data only, losing the 85% token savings and domain-specific quality. | BF-004 (agent profiles), matrix YAML files | v1.0.0 (v1.1.0 rewrite) |
+| BF-008 | Tiered Execution | Platform capability varies. Without tiered execution, the framework either fails on limited platforms or under-utilizes capable ones. | BF-003 (Orchestrator delegates) | v1.0.0 |
+| BF-009 | 10 Orchestration Laws | Laws prevent the Orchestrator from drifting into anti-patterns (silent failures, scope creep, direct implementation). Without governance, quality is inconsistent. | BF-003 (laws govern Orchestrator) | v1.0.0 |
+| BF-010 | Cognitive Anchoring | Prevents role drift in AI agents during long sessions. Without anchoring, agents gradually lose their specialist identity and produce generic output. | BF-004 (agent file format) | v1.0.0 |
+
+### Must Have Dependency Chain
+
+```
+BF-001 (Install) → BF-002 (Platforms)
+BF-001 (Install) → BF-003 (Orchestrator) → BF-009 (Laws)
+BF-003 (Orchestrator) → BF-004 (Agents) → BF-010 (Anchoring)
+BF-003 (Orchestrator) → BF-005 (Commands) → BF-006 (Variants)
+BF-003 (Orchestrator) → BF-008 (Tiered Execution)
+BF-004 (Agents) → BF-007 (HSOL)
+```
+
+**Critical path**: BF-001 → BF-003 → BF-004 → BF-007. If any link in this chain is missing, the core value proposition collapses.
+
+---
+
+## Should Have (8) — Quality & Ecosystem
+
+These features significantly enhance quality, reliability, and extensibility. The framework functions without them, but key differentiators (adversarial quality, self-healing, ecosystem growth) are lost.
+
+| BF-ID | Feature | Rationale | Dependencies | Delivered |
+|-------|---------|-----------|-------------|-----------|
+| BF-011 | 17 Domain Teams | Adversarial collaboration (BG-008) is a key quality differentiator — but single-agent execution still works. Teams are an upgrade, not a requirement. | BF-006 (`:team` variant), `rules/TEAMS.md` | v1.2.0 |
+| BF-012 | Error Self-Healing (E1–E4) | Silent failures degrade trust. Classified recovery is important but the framework can operate (with degraded UX) without it. | `rules/ERRORS.md` | v1.0.0 |
+| BF-013 | Dynamic Skill Discovery | Extends skills beyond bundled 1,430. Important for niche domains but the core skill set covers most use cases. | `find-skills` CLI, network access | v1.3.0 |
+| BF-014 | Trust Progression Lifecycle | Quality gate for dynamic skills. Without it, community skills could degrade output quality. Important but only relevant when BF-013 is active. | BF-013 (dynamic discovery active) | v1.3.0 |
+| BF-015 | Documentation Generation | Auto-docs save significant effort (BG-010) but developers can write docs manually. High value, not existential. | BF-004 (scouter, BA, docs-manager agents) | v1.0.0 |
+| BF-016 | Debate Mechanism (Mailbox) | Traceable inter-agent communication is valuable for audit and quality but teams can function with implicit communication. | BF-011 (teams active), `rules/TEAMS.md` | v1.2.0 |
+| BF-017 | Natural Language Command Detection | Lowers learning curve by mapping plain language to commands. Useful but users can learn the 14 command names directly. | CORE.md routing logic | v1.0.0 |
+| BF-018 | Language Compliance (L6) | International accessibility. English-only users are unaffected. Important for global adoption but not blocking for English-speaking markets. | CORE.md Law L6 | v1.0.0 |
+
+### Should Have Dependency Analysis
+
+| Feature | Hard Dependencies | Soft Dependencies |
+|---------|-------------------|-------------------|
+| BF-011 | BF-006 (`:team` variant exists) | BF-016 (mailbox enhances teams) |
+| BF-012 | None (standalone rules file) | BF-008 (tiered execution generates errors) |
+| BF-013 | BF-007 (HSOL active, fitness score available) | Network access |
+| BF-014 | BF-013 (skills must be discoverable) | BF-007 (trust integrates with fitness scoring) |
+| BF-015 | BF-004 (scouter, BA, docs-manager agents) | BF-005 (`/docs` command) |
+| BF-016 | BF-011 (teams must exist) | — |
+| BF-017 | BF-005 (commands must exist to route to) | — |
+| BF-018 | None (CORE.md law) | — |
+
+---
+
+## Could Have (5) — Convenience & Automation
+
+These features improve user experience and automation but are not required for the primary use cases. They can be deferred or delivered incrementally.
+
+| BF-ID | Feature | Rationale | Dependencies | Delivered |
+|-------|---------|-----------|-------------|-----------|
+| BF-019 | Deployment Workflows | Deployment is valuable but many teams have existing CI/CD pipelines. Agent-assisted deployment is additive, not essential. | BF-004 (devops-engineer agent) | v1.2.0 |
+| BF-020 | Autonomous Execution | Hands-off execution is powerful but users generally want visibility into AI decisions. Higher risk without human checkpoints. | BF-004 (tech-lead agent), BF-005 (command classification) | v1.0.4 |
+| BF-021 | Reporting System | Automated reports save time but are not part of the core build→test→review loop. Additive value. | BF-004 (reporter, scouter agents) | v1.0.3 |
+| BF-022 | Plan Short-Circuit | Optimization for plan-driven workflows. Saves tokens and time but non-critical — redundant research is wasteful, not blocking. | BF-005 (`/code` command), existing `PLAN-*.md` | v1.0.4 |
+| BF-023 | CLI List Command | Diagnostic convenience. Users can check installation status manually by inspecting directories. | BF-001 (CLI exists) | NOT YET |
+
+### Could Have Dependency Analysis
+
+| Feature | Hard Dependencies | Soft Dependencies |
+|---------|-------------------|-------------------|
+| BF-019 | BF-004 (devops-engineer agent) | BF-006 (`:team` variant for deploy) |
+| BF-020 | BF-004 (tech-lead), BF-005 (commands) | All commands (auto routes to them) |
+| BF-021 | BF-004 (reporter, scouter) | BF-005 (`/report` command) |
+| BF-022 | BF-005 (`/code` command) | Existing plan files |
+| BF-023 | BF-001 (CLI) | — |
+
+---
+
+## Priority Justification Matrix
+
+| BF-ID | Without It... | MoSCoW |
+|-------|---------------|--------|
+| BF-001 | Framework cannot be installed | Must |
+| BF-002 | Limited to one platform | Must |
+| BF-003 | No orchestration — just a chatbot | Must |
+| BF-004 | Nothing to delegate to | Must |
+| BF-005 | No structured entry point | Must |
+| BF-006 | Every task gets same treatment | Must |
+| BF-007 | Agents lack domain knowledge | Must |
+| BF-008 | Fails on limited platforms OR wastes capable ones | Must |
+| BF-009 | Orchestrator behavior is unpredictable | Must |
+| BF-010 | Agents drift roles in long sessions | Must |
+| BF-011 | No adversarial review — single-agent quality only | Should |
+| BF-012 | Silent failures degrade trust | Should |
+| BF-013 | Limited to bundled skills only | Should |
+| BF-014 | Community skills could degrade quality | Should |
+| BF-015 | Manual documentation effort | Should |
+| BF-016 | Team communication is implicit, not auditable | Should |
+| BF-017 | Users must memorize commands | Should |
+| BF-018 | English-only interface | Should |
+| BF-019 | Teams use existing CI/CD | Could |
+| BF-020 | Users guide execution manually | Could |
+| BF-021 | Reports written manually | Could |
+| BF-022 | Redundant research when plans exist | Could |
+| BF-023 | Check install status manually | Could |
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Structured Business Pack (MoSCoW table) | [../../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) |
+| PRD — goals and scope | [../business-prd/02-problem-goals-and-scope.md](../business-prd/02-problem-goals-and-scope.md) |
+| CHANGELOG | [../../CHANGELOG.md](../../CHANGELOG.md) |
+| CORE rules | [../../rules/CORE.md](../../rules/CORE.md) |
+| TEAMS rules | [../../rules/TEAMS.md](../../rules/TEAMS.md) |
+| SKILLS rules | [../../rules/SKILLS.md](../../rules/SKILLS.md) |
+| ERRORS rules | [../../rules/ERRORS.md](../../rules/ERRORS.md) |

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

@@ -0,0 +1,512 @@
+# 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 — 4 Variant Strategies
+
+**Description**: `:fast` (2–3 agents), `:hard` (5–8 agents + gates), `:focus` (clean execution), `: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 `:focus` | Context optimization runs; clean focused output produced |
+| AC-4 | `/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/focus.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`/`:focus` | 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`/`:focus`, `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/focus.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/) |