agents-united 1.0.0 → 1.2.0

package/registry/workflows/workflow-explain.md

@@ -1,15 +1,60 @@
-# Workflow: Explain
+---
+name: "Architectural Explanation & Technical Walkthrough"
+description: "Workflow for explaining complex codebase architectures, technical concepts, design patterns, and code implementations clearly."
+bundle: "deep-research"
+estimatedDuration: "20-40m"
+---
 
-Multi-phase procedural workflow for Explain.
+# Workflow: Architectural Explanation & Technical Walkthrough
+
+## Overview & Scope
+The Explain workflow creates clear technical explanations. It structures walkthroughs using progressive disclosure (High-level summary -> Diagram -> Code inspection -> Edge cases) tailored to audience experience.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- Target codebase files or technical concept
+- Target audience experience profile (Beginner, Intermediate, Senior Engineer)
+- Explanation document template
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- Analyze target code module to understand core mechanisms and data flows.
+- Identify key concepts requiring explanation and potential points of confusion.
+- Determine appropriate depth level based on audience profile.
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Construct high-level summary overview of the component or architecture.
+- Draw system interaction diagram illustrating data flow between modules.
+- Provide step-by-step code walkthrough with line-by-line commentary.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Review explanation for clarity, technical accuracy, and tone.
+- Add FAQ section covering common edge cases and troubleshooting tips.
+- Publish Technical Explanation Document.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `node dist/cli.js doctor` | Doctor health check confirms explanation document structure |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `npm run typecheck` | Code snippets inside explanation compile cleanly |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: Explanation tailored appropriately to target audience technical level.
+- **Validation Checkpoint 2**: Code commentary verified against actual implementation logic.
+- **Automated Rollback Protocol**: Clarify ambiguous sections if peer review identifies inaccurate commentary.

package/registry/workflows/workflow-frontend-audit.md

@@ -0,0 +1,49 @@
+---
+name: "Frontend Performance & Accessibility Audit"
+description: "Workflow for measuring Core Web Vitals (LCP, INP, CLS), client bundle sizes, WCAG accessibility, and responsive layout fidelity."
+bundle: "frontend-engineering"
+estimatedDuration: "15-30m"
+---
+
+# Workflow: Frontend Performance & Accessibility Audit
+
+## Overview & Scope
+The Frontend Audit workflow evaluates web applications against Core Web Vitals thresholds (Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift), accessibility standards, and JavaScript bundle sizes.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Bundle & Asset Size Analysis]
+    P1 --> InputCheck{"Bundle Analysis Complete?"}
+    InputCheck -->|No| Abort1[Generate Bundle Stats]
+    InputCheck -->|Yes| P2[Phase 2: Core Web Vitals & Runtime Profiling]
+    P2 --> Gate1{"Verification Gate: CWV Within Targets?"}
+    Gate1 -->|Fail| P2Opt[Apply Code Splitting & Asset Optimizations]
+    P2Opt --> P2
+    Gate1 -->|Pass| P3[Phase 3: Accessibility & Screen Reader Audit]
+    P3 --> Done([Frontend Audit Signed Off])
+```
+
+## Required Tool Inputs & Context
+- Production build bundle stats or Lighthouse test runner
+- Target performance budgets (e.g. initial JS < 150KB gzip)
+- Web application URL or local preview server
+
+## Phase 1: Bundle & Asset Size Analysis
+- Analyze Webpack / Vite / Next.js bundle visualizer output.
+- Identify duplicate dependencies or un-tree-shaken libraries.
+
+## Phase 2: Core Web Vitals & Runtime Profiling
+- Measure Largest Contentful Paint (LCP < 2.5s), Cumulative Layout Shift (CLS < 0.1), and Interaction to Next Paint (INP < 200ms).
+- Apply lazy loading, dynamic imports, and font optimization.
+
+## Phase 3: Accessibility & Screen Reader Audit
+- Run automated axe-core / Lighthouse a11y audit to verify WCAG 2.1 AA compliance.
+- Confirm keyboard tab navigation and modal focus trapping.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Bundle analysis complete | Bundle size measurement | Main bundle under 150KB gzipped |
+| Phase 2 -> Phase 3 | Performance metrics gathered | Lighthouse / Web Vitals audit | Performance score >= 90 |
+| Phase 3 -> Completion | Accessibility verified | A11y axe-core scan | 0 critical/serious accessibility violations |

package/registry/workflows/workflow-git.md

@@ -1,15 +1,60 @@
-# Workflow: Git
+---
+name: "Git Version Control & Branch Strategy"
+description: "Workflow for managing git feature branches, atomic commit formatting, rebase workflow, PR preparation, and merge readiness."
+bundle: "software-engineering"
+estimatedDuration: "10-20m"
+---
 
-Multi-phase procedural workflow for Git.
+# Workflow: Git Version Control & Branch Strategy
+
+## Overview & Scope
+The Git workflow establishes best practices for version control operations. It covers branch creation, atomic Conventional Commits, interactive rebasing, merge conflict resolution, and pull request preparation.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- Git CLI tool
+- Conventional Commit naming convention guidelines
+- Target base branch (`main` / `dev`)
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- Inspect `git status` to verify current working directory state.
+- Fetch latest remote branches (`git fetch origin`) and check rebase status against base branch.
+- Review pending uncommitted changes and organize them into logical, atomic change sets.
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Stage changes incrementally (`git add -p`) and craft conventional commit messages (`feat:`, `fix:`, `docs:`).
+- Perform interactive rebase onto target base branch (`git rebase origin/main`) to maintain linear history.
+- Resolve any merge conflicts cleanly, running tests after each resolved conflict.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Verify git commit history hygiene (no fixup commits, clean messages).
+- Push feature branch to remote origin (`git push -u origin feature-branch`).
+- Prepare PR description linking related issues, summarizing changes, and listing verification commands.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `git status` | Working tree is clean with no unstaged changes or untracked files |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `git log -n 5 --oneline` | Commit history is linear and messages adhere to Conventional Commits |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: Branch rebased onto current remote base branch without remaining conflict markers.
+- **Validation Checkpoint 2**: Remote feature branch synchronized and PR ready for review.
+- **Automated Rollback Protocol**: Use `git rebase --abort` to cancel rebase if conflicts become unmanageable, returning to pre-rebase state.

package/registry/workflows/workflow-grill.md

@@ -0,0 +1,51 @@
+---
+name: "Socratic Alignment & Domain Grilling"
+description: "Interactive orchestration workflow for Socratic requirements grilling, ubiquitous language definition in CONTEXT.md, and ADR creation."
+bundle: "software-engineering"
+estimatedDuration: "15-30m"
+---
+
+# Workflow: Socratic Alignment & Domain Grilling
+
+## Overview & Scope
+The Socratic Alignment & Domain Grilling workflow aligns developers and orchestrators on problem scope, edge cases, and non-goals. It invokes the `grill-with-docs`, `grill-me`, and `domain-modeling` skills to build a shared vocabulary in `CONTEXT.md` and record decisions in ADRs (`docs/adr/`).
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Socratic Alignment Interview]
+    P1 --> Gate1{"User Intent & Scope Explicit?"}
+    Gate1 -->|No| P1
+    Gate1 -->|Yes| P2[Phase 2: Ubiquitous Language & CONTEXT.md Sync]
+    P2 --> P3[Phase 3: ADR Generation & Hand-off]
+    P3 --> Done([Workflow Complete])
+```
+
+## Required Tool Inputs & Context
+- Project root with `CONTEXT.md` (or authorization to create `CONTEXT.md`).
+- Feature request or architectural proposal details.
+
+## Phase 1: Socratic Alignment Interview
+- Execute `/grill-with-docs` or `/grill-me` skill runbook.
+- Interrogate assumptions, data flows, edge cases, failure states, and performance constraints.
+- Collect explicit user decisions on every trade-off.
+
+## Phase 2: Ubiquitous Language & CONTEXT.md Sync
+- Extract candidate domain terms from the interview.
+- Update `CONTEXT.md` with definitions for new domain entities and rules.
+
+## Phase 3: ADR Generation & Hand-off
+- Document chosen architectural strategy in `docs/adr/ADR-XXXX-<title>.md`.
+- Summarize agreed scope and hand off to technical specification (`workflow-spec.md`) or implementation (`workflow-implement.md`).
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Grilling questions answered | User approval | All ambiguities resolved |
+| Phase 2 -> Phase 3 | Terms extracted | `CONTEXT.md` check | `CONTEXT.md` contains defined terms |
+| Phase 3 -> Completion | ADR formatted | `docs/adr/*.md` exists | ADR saved cleanly |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: All questions answered before drafting ADR.
+- **Validation Checkpoint 2**: `CONTEXT.md` contains valid domain definitions.
+- **Rollback Protocol**: Revert draft ADR files if grilling reveals invalid assumptions.

package/registry/workflows/workflow-implement.md

@@ -1,15 +1,61 @@
-# Workflow: Implement
+---
+name: "Implement Feature or Fix"
+description: "End-to-end procedural workflow for code implementation, refactoring, and feature execution with TDD validation and regression checks."
+bundle: "software-engineering"
+estimatedDuration: "30-60m"
+---
 
-Multi-phase procedural workflow for Implement.
+# Workflow: Implement Feature or Fix
+
+## Overview & Scope
+The Implement workflow guides developers and autonomous agents through a rigorous implementation process. It enforces Test-Driven Development (TDD) principles, incremental code modifications, and strict phase verification gates to ensure code quality and zero regressions.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- Target file paths & module interfaces
+- Feature requirements or issue specification document
+- Test suite execution command (`npm test`)
+- Linter & static type-checker (`npm run typecheck`, `npm run lint`)
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- Analyze the feature specification or issue report to understand functional goals and constraints.
+- Inspect existing codebase state, git branch status, and relevant module dependencies.
+- Identify target test files and code components that will be affected by the implementation.
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Write red unit tests covering expected new functionality or bug reproduction.
+- Implement minimum viable code changes required to transition tests from failing to passing (green state).
+- Refactor implementation for readability, performance, and style consistency while maintaining passing tests.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Run the full project test suite to verify no regressions were introduced in existing functionality.
+- Execute static type checking (`tsc --noEmit`) and linter checks to ensure compliance with codebase standards.
+- Summarize implementation details, updated files, and test results for reviewer handoff.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `npm run typecheck` | 0 type errors across all project files |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `npm test` | 100% of unit and integration tests passing cleanly |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: Red-Green-Refactor test cycle verified before staging changes.
+- **Validation Checkpoint 2**: Static type checking and linting pass without errors or warnings.
+- **Automated Rollback Protocol**: Execute `git checkout -- .` or `git reset --hard HEAD` to revert incomplete or failing edits if verification fails.

package/registry/workflows/workflow-incident-triage.md

@@ -0,0 +1,49 @@
+---
+name: "Production Incident Response & Triage"
+description: "Workflow for responding to production alerts, triaging telemetry metrics, executing runbooks, and publishing blameless post-mortems."
+bundle: "sysops-sre"
+estimatedDuration: "15-45m"
+---
+
+# Workflow: Production Incident Response & Triage
+
+## Overview & Scope
+The Incident Response workflow guides SRE and SysOps engineers through structured triage, root-cause investigation, emergency mitigation, and post-mortem reporting during production incidents.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Alert Triggered]) --> P1[Phase 1: Severity Classification & Telemetry Triage]
+    P1 --> TriageCheck{"Severity Level Determined?"}
+    TriageCheck -->|P1 Critical| P2[Phase 2: Emergency Mitigation & Rerouting]
+    TriageCheck -->|P2/P3 Degraded| P2
+    P2 --> Gate1{"Verification Gate: Service Restored?"}
+    Gate1 -->|No| Escalation[Escalate & Execute DR Failover]
+    Escalation --> P2
+    Gate1 -->|Yes| P3[Phase 3: Post-Mortem & Preventative Action]
+    P3 --> Done([Incident Resolved & Documented])
+```
+
+## Required Tool Inputs & Context
+- Triggering alert payload or error metric log trace
+- System architecture diagram and service dependencies
+- Prometheus / Grafana telemetry metrics and incident runbook
+
+## Phase 1: Severity Classification & Telemetry Triage
+- Correlate triggering alert with RED metrics (Rate, Errors, Duration).
+- Classify incident severity (P1 Critical Outage, P2 High Impact, P3 Moderate Degraded State).
+
+## Phase 2: Emergency Mitigation & Rerouting
+- Execute runbook mitigation steps (pod scaling, traffic drain, service restart, cache flush).
+- Monitor p99 latency and error rates to confirm service stabilization.
+
+## Phase 3: Post-Mortem & Preventative Action
+- Draft Blameless Post-Mortem covering timeline, root cause, impact metrics, and action items.
+- File preventative engineering tickets to prevent incident recurrence.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Incident severity classified | Log analysis & alert payload audit | Impacted microservices identified |
+| Phase 2 -> Phase 3 | Mitigation steps applied | Telemetry HTTP 5xx error rate audit | Error rate drops below 0.1% SLO threshold |
+| Phase 3 -> Completion | Service health verified | Post-mortem markdown audit | Post-mortem document includes action items and owner assignments |

package/registry/workflows/workflow-interaction-design--design-interaction.md

@@ -1,15 +1,60 @@
-# Workflow: Interaction Design  Design Interaction
+---
+name: "Micro-Interaction & Transition Design"
+description: "Workflow for designing component state transitions, micro-animations, timing curves, and interactive UI behavior specs."
+bundle: "product-design"
+estimatedDuration: "30-45m"
+---
 
-Multi-phase procedural workflow for Interaction Design  Design Interaction.
+# Workflow: Micro-Interaction & Transition Design
+
+## Overview & Scope
+This workflow defines micro-interactions and UI motion specs. It standardizes transition durations, easing curves, visual feedback states, and accessibility fallbacks for motion sensitivities.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- UI component visual designs
+- Design system motion guidelines (durations, easing curves)
+- Accessibility reduced motion specification (`prefers-reduced-motion`)
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- Identify interactive UI triggers (hover, active press, toggle, modal open, page transition).
+- Review target motion principles (expressive vs functional animation).
+- Establish duration thresholds (150ms micro-interactions, 300ms layout transitions).
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Define animation properties (scale, opacity, transform, background-color).
+- Select cubic-bezier easing curves (ease-in-out, standard spring curves).
+- Design reduced-motion alternatives for users with motion sensitivity settings.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Verify motion performance (60fps hardware acceleration, GPU-promoted layers).
+- Document interaction spec with timing values and CSS/Framer Motion code snippets.
+- Export interaction tokens (`duration-fast`, `ease-out-back`).
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `npm test` | Interaction suite verifies prefers-reduced-motion fallbacks for all motion specs |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `npm run build` | Motion animation CSS/JS tokens build cleanly |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: All transition durations fall within standard 100ms-300ms usability window.
+- **Validation Checkpoint 2**: Explicit reduced-motion fallback defined for every animated component.
+- **Automated Rollback Protocol**: Simplify animation curves and remove heavy transforms if frame rate drops below 60fps.

package/registry/workflows/workflow-interaction-design--error-flow.md

@@ -1,15 +1,60 @@
-# Workflow: Interaction Design  Error Flow
+---
+name: "Error UX & Fault Recovery Flow Design"
+description: "Workflow for mapping error states, validation feedback, network failure fallbacks, and user recovery paths across UI components."
+bundle: "product-design"
+estimatedDuration: "30-45m"
+---
 
-Multi-phase procedural workflow for Interaction Design  Error Flow.
+# Workflow: Error UX & Fault Recovery Flow Design
+
+## Overview & Scope
+The Error Flow workflow ensures resilient UI design during system failures. It maps validation errors, network offline states, API exceptions, and user recovery mechanisms with clear human-centric UX.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- User interaction flows & form specifications
+- API error payload schemas and HTTP status codes
+- Error copy guidelines
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- Enumerate all potential failure modes (field validation failure, session timeout, network offline, 500 server error).
+- Audit existing error message copy for clarity and tone.
+- Define focus management strategy when error state triggers.
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Design inline error messages, toast alerts, empty state illustrations, and modal error dialogs.
+- Map explicit recovery paths for the user (Retry CTA, Re-authenticate link, Customer support fallback).
+- Draft clear, empathetic error copy explaining what happened and how to fix it.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Review error flows against accessibility guidelines (ARIA live regions `aria-live="polite"`).
+- Verify focus is placed on broken form inputs or alert headers upon error submission.
+- Publish Error UX Specification Matrix.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `npm test` | Error flow tests verify accessibility ARIA live attributes on error containers |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `npm run typecheck` | Error payload interfaces compile cleanly |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: Every failure mode has an explicit UI design and recovery CTA.
+- **Validation Checkpoint 2**: Zero technical error jargon in user-facing message copy.
+- **Automated Rollback Protocol**: Revise error messages and recovery paths if usability checks reveal confusing copy.

package/registry/workflows/workflow-interaction-design--map-states.md

@@ -1,15 +1,60 @@
-# Workflow: Interaction Design  Map States
+---
+name: "Component State Matrix Mapping"
+description: "Workflow for systematically mapping and documenting all UI component states (default, hover, focus, active, disabled, loading, error)."
+bundle: "product-design"
+estimatedDuration: "20-35m"
+---
 
-Multi-phase procedural workflow for Interaction Design  Map States.
+# Workflow: Component State Matrix Mapping
+
+## Overview & Scope
+This workflow guarantees complete UI component state coverage. It maps the 7 fundamental component states, ensuring consistent visual and keyboard behavior across the application.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- Component visual designs & design tokens
+- Accessibility focus ring guidelines (contrast >= 3:1)
+- Component state checklist
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- List target components requiring state mapping (buttons, text inputs, checkboxes, dropdowns, toggles).
+- Identify visual property changes for each state transition (background, border, shadow, opacity).
+- Verify keyboard focus styling rules.
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Document visual design specs for all 7 standard states: Default, Hover, Focus-Visible, Active (Pressed), Disabled, Loading, Error.
+- Define state transition rules and visual indicators (spinner for loading, greyed out for disabled).
+- Verify focus ring meets WCAG 2.1 visible focus requirements.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Audit component state matrix for missing state specs.
+- Export state matrix specifications to design system component docs.
+- Publish Component State Checklist.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `npm test` | State matrix test verifies 100% state coverage for all cataloged components |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `npm run build` | Component CSS state classes build without compilation errors |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: All 7 component states explicitly specified for every cataloged component.
+- **Validation Checkpoint 2**: Focus-visible state ring has >= 3:1 contrast ratio against adjacent surfaces.
+- **Automated Rollback Protocol**: Add missing state specifications before releasing component to component library.

package/registry/workflows/workflow-marketing-audit.md

@@ -1,15 +1,60 @@
-# Workflow: Marketing Audit
+---
+name: "Growth & Marketing Funnel Audit"
+description: "Comprehensive workflow for auditing acquisition channels, conversion funnels, landing page performance, and analytics tracking."
+bundle: "growth-marketing"
+estimatedDuration: "45-80m"
+---
 
-Multi-phase procedural workflow for Marketing Audit.
+# Workflow: Growth & Marketing Funnel Audit
+
+## Overview & Scope
+This workflow conducts end-to-end marketing audits. It inspects acquisition channels, conversion funnel drop-off metrics, landing page technical SEO, page speed, and analytics event tracking.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Start Workflow]) --> P1[Phase 1: Context & Reconnaissance]
+    P1 --> InputCheck{"Prerequisites & Tools Valid?"}
+    InputCheck -->|No| Abort1[Abort & Request Inputs]
+    InputCheck -->|Yes| P2[Phase 2: Execution & Orchestration]
+    P2 --> Gate1{"Verification Gate: Automated Checks Pass?"}
+    Gate1 -->|Fail| Rollback[Execute Automated Rollback Protocol]
+    Rollback --> P2
+    Gate1 -->|Pass| P3[Phase 3: Verification & Closure]
+    P3 --> Gate2{"Final Acceptance Gate Passed?"}
+    Gate2 -->|Fail| P3Fix[Remediate Documentation / Artifacts]
+    P3Fix --> P3
+    Gate2 -->|Pass| Done([Workflow Complete & Logged])
+```
+
+## Required Tool Inputs & Context
+- Analytics dataset exports (funnel drop-offs, conversion rates)
+- Landing page URLs & technical SEO audit tools
+- Target funnel stage definitions
 
 ## Phase 1: Context & Reconnaissance
-- Analyze the user request and existing codebase state.
-- Gather necessary inputs and verify environment readiness.
+- Map full user acquisition funnel (Traffic -> Landing Page -> Signup -> Activation -> Paid Conversion).
+- Extract analytics drop-off metrics across each funnel transition step.
+- Prepare technical SEO and landing page speed scanner tools.
 
 ## Phase 2: Execution & Orchestration
-- Execute core steps with progressive verifications.
-- Delegate sub-tasks to specialized sub-agents.
+- Identify high-drop-off funnel bottlenecks and conversion friction points.
+- Audit landing page technical SEO (meta tags, open graph, structured schema) and Core Web Vitals.
+- Inspect analytics event tracking setup to verify accuracy of conversion logging.
 
 ## Phase 3: Verification & Closure
-- Run verification tests and linting.
-- Document outcome and present summary.
+- Synthesize audit findings into an Impact vs Effort Growth Opportunity Matrix.
+- Create prioritized remediation backlog targeting high-leverage conversion fixes.
+- Publish Growth & Marketing Funnel Audit Report.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Tool inputs verified & environment ready | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Execution steps complete | `npm test` | Funnel analytics script verifies data consistency across conversion stages |
+| Phase 3 -> Completion | Verification complete & artifacts signed off | `npm run build` | Build pipeline validates audit report compilation |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: All acquisition funnel drop-off points quantified with analytics baseline data.
+- **Validation Checkpoint 2**: Technical SEO issues cataloged with actionable remediation fixes.
+- **Automated Rollback Protocol**: Re-verify analytics tracking tags if data anomalies pollute funnel audit calculations.