@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/business/business-workflows/02-workflow-catalog.md

@@ -0,0 +1,252 @@
+# Agent Assistant — Workflow Catalog
+
+| Field | Value |
+|-------|-------|
+| **Purpose** | Complete catalog of all 12 business workflows with classification metadata |
+| **Parent** | [00-index.md](00-index.md) |
+| **Last Updated** | 2026-03-26 |
+| **Generated By** | docs-business skill |
+
+---
+
+## Catalog Overview
+
+All 12 workflows are classified by complexity (Low / Medium / High) and frequency (Per-Session / Per-Task / On-Demand / Rare). Complexity reflects the number of decision points, branching paths, and actor handoffs. Frequency reflects how often the workflow is triggered in typical framework usage.
+
+---
+
+## Full Catalog
+
+### BW-001 — Framework Installation
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-001 |
+| **Name** | Framework Installation |
+| **Actor** | Framework User |
+| **Trigger** | `agent-assistant install <tool>` or `agent-assistant install --all` |
+| **Outcome** | Framework files copied to `~/.{tool}/skills/agent-assistant/` with placeholder replacement applied |
+| **Exception Handling** | Invalid tool → exit 1; missing Node >=18 → error; directory creation failure → exit |
+| **Complexity** | Low |
+| **Frequency** | Rare (once per environment setup) |
+| **Dependencies** | Node.js >=18, npm, filesystem write access |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-001](03-detailed-workflows.md#bw-001--framework-installation) |
+
+---
+
+### BW-002 — Framework Uninstallation
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-002 |
+| **Name** | Framework Uninstallation |
+| **Actor** | Framework User |
+| **Trigger** | `agent-assistant uninstall <tool>` or `agent-assistant uninstall --all` |
+| **Outcome** | Bundled files removed from target directory; custom user files preserved |
+| **Exception Handling** | Non-existent installation → skip with informational message |
+| **Complexity** | Low |
+| **Frequency** | Rare (environment cleanup) |
+| **Dependencies** | Prior BW-001 execution |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-002](03-detailed-workflows.md#bw-002--framework-uninstallation) |
+
+---
+
+### BW-003 — Command Execution (Standard)
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-003 |
+| **Name** | Command Execution (Standard) |
+| **Actor** | AI Model (Orchestrator) |
+| **Trigger** | User types `/{cmd}`, `/{cmd}:{variant}`, or natural language mapped to a command |
+| **Outcome** | Pre-flight checks → command router → variant resolution → sequential phase execution → agent delegation per phase → exit criteria verification → deliverable to user |
+| **Exception Handling** | Ambiguous requirement → PAUSE + ASK (Law 2); exit criteria not met → halt workflow |
+| **Complexity** | High |
+| **Frequency** | Per-Task (every user request) |
+| **Dependencies** | BW-001 (framework installed), BW-004 (agent delegation), BW-005 (skill resolution) |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-003](03-detailed-workflows.md#bw-003--command-execution-standard) |
+
+---
+
+### BW-004 — Agent Delegation (Tiered)
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-004 |
+| **Name** | Agent Delegation (Tiered) |
+| **Actor** | Orchestrator |
+| **Trigger** | A phase within a command requires specialist work |
+| **Outcome** | Check `runSubagent` availability → TIER 1: spawn isolated sub-agent → TIER 2 fallback: embody agent in shared context → execute phase → verify deliverable against exit criteria |
+| **Exception Handling** | `runSubagent` error → TIER 2 with logged justification |
+| **Complexity** | Medium |
+| **Frequency** | Per-Task (multiple times per command execution) |
+| **Dependencies** | BW-003 (provides phase context), agent definitions in `agents/*.md` |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-004](03-detailed-workflows.md#bw-004--agent-delegation-tiered) |
+
+---
+
+### BW-005 — Skill Resolution (HSOL)
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-005 |
+| **Name** | Skill Resolution (HSOL) |
+| **Actor** | Agent (via Orchestrator) |
+| **Trigger** | An agent assigned to a phase needs domain skills to execute |
+| **Outcome** | Parse agent profile → load domain YAMLs → filter by relevance → fitness scoring (5 weights) → route by threshold band → return sorted skill set |
+| **Exception Handling** | Network timeout → matrix-only fallback; no matching skills → report gap to Orchestrator |
+| **Complexity** | High |
+| **Frequency** | Per-Task (once per agent delegation with skill needs) |
+| **Dependencies** | BW-004 (agent context), `matrix-skills/*.yaml`, `_dynamic.yaml` |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-005](03-detailed-workflows.md#bw-005--skill-resolution-hsol) |
+
+---
+
+### BW-006 — Dynamic Skill Discovery
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-006 |
+| **Name** | Dynamic Skill Discovery |
+| **Actor** | HSOL System |
+| **Trigger** | Fitness score < 0.8 for hard/team command variants |
+| **Outcome** | `npx skills find` → evaluate candidates → check superiority delta (>0.15) → if low-trust + critical: user confirmation → `npx skills add` → register in `_dynamic.yaml` |
+| **Exception Handling** | Timeout (5s) → matrix-only fallback; install failure → rollback + offer matrix skills |
+| **Complexity** | High |
+| **Frequency** | On-Demand (only when matrix skills insufficient) |
+| **Dependencies** | BW-005 (low fitness trigger), npm registry access, `_dynamic.yaml` |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-006](03-detailed-workflows.md#bw-006--dynamic-skill-discovery) |
+
+---
+
+### BW-007 — Trust Progression
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-007 |
+| **Name** | Trust Progression |
+| **Actor** | HSOL System |
+| **Trigger** | A dynamically discovered skill completes execution (success or failure) |
+| **Outcome** | NEW (0.3) → 3 successes → EVALUATING (0.5) → 10 successes → VALIDATED (0.7) → auto-promote if count≥10, rate≥85%, inactive≤30d → PROMOTED (1.0) |
+| **Exception Handling** | Success rate <85% → BLOCKED; inactive >30d → BLOCKED; 90-day inactivity → decay |
+| **Complexity** | Medium |
+| **Frequency** | Per-Task (after each dynamic skill execution) |
+| **Dependencies** | BW-006 (dynamic skill installed), `_dynamic.yaml` (trust state storage) |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-007](03-detailed-workflows.md#bw-007--trust-progression) |
+
+---
+
+### BW-008 — Team Collaboration (Golden Triangle)
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-008 |
+| **Name** | Team Collaboration (Golden Triangle) |
+| **Actor** | Orchestrator + 3 Team Agents (Tech Lead, Executor, Reviewer) |
+| **Trigger** | User invokes a `:team` variant of any command |
+| **Outcome** | Tech Lead decomposes task → TASK_ASSIGNMENT to Mailbox → Executor implements → SUBMISSION → Reviewer critiques → REVIEW (PASS/FAIL) → if FAIL: defend/fix cycle → max 3 rounds → consensus stamp → release |
+| **Exception Handling** | Max 3 rounds reached → Tech Lead arbitrates final; "disagree without proof" → auto-FAIL |
+| **Complexity** | High |
+| **Frequency** | On-Demand (`:team` variant invocations) |
+| **Dependencies** | BW-003 (command routing), `rules/TEAMS.md`, `agents/teams/` |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-008](03-detailed-workflows.md#bw-008--team-collaboration-golden-triangle) |
+
+---
+
+### BW-009 — Documentation Generation
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-009 |
+| **Name** | Documentation Generation |
+| **Actor** | Orchestrator |
+| **Trigger** | `/docs`, `/docs:core`, `/docs:business`, `/docs:audit` |
+| **Outcome** | Sequential generation: core (5 folders) → business (4 folders) → audit (4 folders) |
+| **Exception Handling** | Incomplete generation = FAILED status; each step must complete before the next begins |
+| **Complexity** | Medium |
+| **Frequency** | On-Demand (documentation maintenance cycles) |
+| **Dependencies** | BW-003 (command routing), BW-004 (agent delegation to docs-manager) |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-009](03-detailed-workflows.md#bw-009--documentation-generation) |
+
+---
+
+### BW-010 — Error Recovery (E1–E4)
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-010 |
+| **Name** | Error Recovery (E1–E4) |
+| **Actor** | Orchestrator |
+| **Trigger** | Error occurs during any phase of any workflow |
+| **Outcome** | E1: retry 3× → E1b: chunk into smaller units → E2: alternative approach → E3: save to safe point → E4: rollback → user escalation |
+| **Exception Handling** | All paths terminate in either success or explicit user decision — no silent halts permitted |
+| **Complexity** | High |
+| **Frequency** | On-Demand (only on errors; ideally infrequent) |
+| **Dependencies** | Originating workflow context, `rules/ERRORS.md` |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-010](03-detailed-workflows.md#bw-010--error-recovery-e1e4) |
+
+---
+
+### BW-011 — Plan Short-Circuit
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-011 |
+| **Name** | Plan Short-Circuit |
+| **Actor** | Orchestrator |
+| **Trigger** | User references an existing `PLAN-*.md` file in `/code:hard` or `/code:team` commands |
+| **Outcome** | Detect plan reference → skip research/scout/brainstorm phases → jump to context optimization → implement → test → review |
+| **Exception Handling** | Plan file must exist and be valid; invalid plan → fall back to standard BW-003 flow |
+| **Complexity** | Low |
+| **Frequency** | On-Demand (when users have pre-existing plans) |
+| **Dependencies** | BW-003 (command context), valid `PLAN-*.md` in workspace |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-011](03-detailed-workflows.md#bw-011--plan-short-circuit) |
+
+---
+
+### BW-012 — Platform Integration
+
+| Attribute | Value |
+|-----------|-------|
+| **ID** | BW-012 |
+| **Name** | Platform Integration |
+| **Actor** | Framework Maintainer |
+| **Trigger** | Decision to support a new AI coding assistant platform |
+| **Outcome** | Add to TOOLS config → create install/uninstall scripts → add to CORE.md resolution table → create `code-assistants/` directory → add npm scripts → update README |
+| **Exception Handling** | New platform must follow existing conventions; deviation → design review required |
+| **Complexity** | Medium |
+| **Frequency** | Rare (new platform adoption) |
+| **Dependencies** | Framework architecture knowledge, `cli/install.js` extension points |
+| **Detailed Flow** | [03-detailed-workflows.md#bw-012](03-detailed-workflows.md#bw-012--platform-integration) |
+
+---
+
+## Complexity Distribution
+
+| Complexity | Count | Workflows |
+|------------|-------|-----------|
+| Low | 3 | BW-001, BW-002, BW-011 |
+| Medium | 4 | BW-004, BW-007, BW-009, BW-012 |
+| High | 5 | BW-003, BW-005, BW-006, BW-008, BW-010 |
+
+## Frequency Distribution
+
+| Frequency | Count | Workflows |
+|-----------|-------|-----------|
+| Per-Task | 4 | BW-003, BW-004, BW-005, BW-007 |
+| On-Demand | 5 | BW-006, BW-008, BW-009, BW-010, BW-011 |
+| Rare | 3 | BW-001, BW-002, BW-012 |
+
+---
+
+## Evidence Sources
+
+- `CLAUDE.md` — Command routing, orchestrator behavior
+- `rules/CORE.md` — Orchestration Laws governing all workflows
+- `rules/AGENTS.md` — Tiered agent delegation
+- `rules/SKILLS.md` — HSOL resolution and trust progression
+- `rules/TEAMS.md` — Golden Triangle team protocol
+- `rules/ERRORS.md` — E1–E4 error recovery classification
+- `rules/PHASES.md` — Phase sequencing and exit criteria
+- `cli/install.js` — Install/uninstall implementation
+- `commands/*.md` — Command and variant definitions