aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/tasks/ds-critical-eye-report.md

@@ -1,101 +1,101 @@
-# Critical Eye — Generate Cycle Report
-
-> Task ID: ds-critical-eye-report
-> Agent: Brad Frost (Design System Architect)
-> Version: 1.0.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[ds-critical-eye-decide]` · enables: `[]` · workflow: `critical-eye`
-
-## Description
-
-Compile a comprehensive cycle report summarizing everything that happened in this Critical Eye evaluation cycle. Includes: summary statistics, all scores by category, transitions executed, proposals pending, category health overview, and recommendations for next cycle.
-
-Uses the `critical-eye-cycle-report-tmpl.md` template for consistent formatting across cycles.
-
-## Output Schema
-- **produces:** `outputs/design-system/critical-eye/cycle-{N}/report.md`
-- **format:** Markdown — human-readable report following template
-- **consumed_by:** design-chief (review), team (visibility)
-
-## Prerequisites
-
-- All previous Critical Eye steps completed (inventory, score, compare, decide)
-- Template: `squads/design/templates/critical-eye-cycle-report-tmpl.md`
-
-## Workflow
-
-### Steps
-
-1. **Load All Cycle Data**
-   - Read `inventory.json` — variant counts, new variants, orphans
-   - Read `scored.json` — all scores by variant
-   - Read `rankings.json` — rankings, leaders, comparisons, health
-   - Read `decisions.json` — auto-transitions executed
-   - Read `proposals.json` — pending checkpoint proposals
-   - Read `review-decisions.json` (if exists) — design-chief review results
-   - Check: all required files loaded
-
-2. **Calculate Summary Statistics**
-   - Total variants evaluated
-   - New variants this cycle
-   - Transitions executed: count by type (CANDIDATE→EXPERIMENTAL, EXPERIMENTAL→STABLE, REJECT)
-   - Proposals pending human review
-   - Average score across all variants
-   - Highest score / lowest score (non-REJECT)
-   - Categories evaluated
-   - Categories needing attention (avg < 40)
-   - Check: statistics calculated
-
-3. **Build Category Breakdown**
-   - For each category:
-     - Leader variant + score
-     - All variants with scores (table format)
-     - Transitions that occurred
-     - Health metrics (avg, spread, count)
-     - Recommendation (e.g., "needs more sources", "ready for canonical review", "healthy")
-   - Check: all categories represented
-
-4. **Build Transition Summary**
-   - Table of all transitions executed:
-     | Variant | From | To | Score | Reason |
-   - Separate section for proposals awaiting review:
-     | Variant | Proposed | Score | Requires |
-   - Check: all transitions and proposals listed
-
-5. **Generate Recommendations**
-   - **Immediate actions:** Variants close to thresholds (e.g., score 78 — almost CANONICAL)
-   - **Source gaps:** Variants with breadth = 0 (snowflake) — recommend finding additional sources
-   - **Quality gaps:** Variants with low quality sub-scores — recommend specific improvements
-   - **A11y concerns:** Variants with low (but non-zero) accessibility — recommend remediation
-   - **Next cycle focus:** Categories with most room for improvement
-   - Check: at least 1 recommendation generated
-
-6. **Render Report Using Template**
-   - Load `critical-eye-cycle-report-tmpl.md`
-   - Fill in all sections with computed data
-   - Include timestamp, cycle number, scoring rules version
-   - Check: template sections all populated
-
-7. **Save Report**
-   - Write to `outputs/design-system/critical-eye/cycle-{N}/report.md`
-   - Check: file saved successfully
-
-## Failure Handling
-
-- **Missing cycle data:** Generate partial report with available data, note gaps
-- **Template not found:** Use inline format (degrade gracefully)
-- **No transitions this cycle:** Note "No lifecycle changes this cycle" — not an error
-
-## Success Criteria
-
-- [ ] Report includes summary statistics
-- [ ] All categories covered with scores and rankings
-- [ ] Transition summary complete (executed + proposals)
-- [ ] Recommendations generated for next cycle
-- [ ] Template format followed
-- [ ] Report saved to correct cycle output directory
-
-## Related Checklists
-
-- `squads/design/checklists/ds-critical-eye-review-checklist.md`
+# Critical Eye — Generate Cycle Report
+
+> Task ID: ds-critical-eye-report
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-critical-eye-decide]` · enables: `[]` · workflow: `critical-eye`
+
+## Description
+
+Compile a comprehensive cycle report summarizing everything that happened in this Critical Eye evaluation cycle. Includes: summary statistics, all scores by category, transitions executed, proposals pending, category health overview, and recommendations for next cycle.
+
+Uses the `critical-eye-cycle-report-tmpl.md` template for consistent formatting across cycles.
+
+## Output Schema
+- **produces:** `outputs/design-system/critical-eye/cycle-{N}/report.md`
+- **format:** Markdown — human-readable report following template
+- **consumed_by:** design-chief (review), team (visibility)
+
+## Prerequisites
+
+- All previous Critical Eye steps completed (inventory, score, compare, decide)
+- Template: `squads/design/templates/critical-eye-cycle-report-tmpl.md`
+
+## Workflow
+
+### Steps
+
+1. **Load All Cycle Data**
+   - Read `inventory.json` — variant counts, new variants, orphans
+   - Read `scored.json` — all scores by variant
+   - Read `rankings.json` — rankings, leaders, comparisons, health
+   - Read `decisions.json` — auto-transitions executed
+   - Read `proposals.json` — pending checkpoint proposals
+   - Read `review-decisions.json` (if exists) — design-chief review results
+   - Check: all required files loaded
+
+2. **Calculate Summary Statistics**
+   - Total variants evaluated
+   - New variants this cycle
+   - Transitions executed: count by type (CANDIDATE→EXPERIMENTAL, EXPERIMENTAL→STABLE, REJECT)
+   - Proposals pending human review
+   - Average score across all variants
+   - Highest score / lowest score (non-REJECT)
+   - Categories evaluated
+   - Categories needing attention (avg < 40)
+   - Check: statistics calculated
+
+3. **Build Category Breakdown**
+   - For each category:
+     - Leader variant + score
+     - All variants with scores (table format)
+     - Transitions that occurred
+     - Health metrics (avg, spread, count)
+     - Recommendation (e.g., "needs more sources", "ready for canonical review", "healthy")
+   - Check: all categories represented
+
+4. **Build Transition Summary**
+   - Table of all transitions executed:
+     | Variant | From | To | Score | Reason |
+   - Separate section for proposals awaiting review:
+     | Variant | Proposed | Score | Requires |
+   - Check: all transitions and proposals listed
+
+5. **Generate Recommendations**
+   - **Immediate actions:** Variants close to thresholds (e.g., score 78 — almost CANONICAL)
+   - **Source gaps:** Variants with breadth = 0 (snowflake) — recommend finding additional sources
+   - **Quality gaps:** Variants with low quality sub-scores — recommend specific improvements
+   - **A11y concerns:** Variants with low (but non-zero) accessibility — recommend remediation
+   - **Next cycle focus:** Categories with most room for improvement
+   - Check: at least 1 recommendation generated
+
+6. **Render Report Using Template**
+   - Load `critical-eye-cycle-report-tmpl.md`
+   - Fill in all sections with computed data
+   - Include timestamp, cycle number, scoring rules version
+   - Check: template sections all populated
+
+7. **Save Report**
+   - Write to `outputs/design-system/critical-eye/cycle-{N}/report.md`
+   - Check: file saved successfully
+
+## Failure Handling
+
+- **Missing cycle data:** Generate partial report with available data, note gaps
+- **Template not found:** Use inline format (degrade gracefully)
+- **No transitions this cycle:** Note "No lifecycle changes this cycle" — not an error
+
+## Success Criteria
+
+- [ ] Report includes summary statistics
+- [ ] All categories covered with scores and rankings
+- [ ] Transition summary complete (executed + proposals)
+- [ ] Recommendations generated for next cycle
+- [ ] Template format followed
+- [ ] Report saved to correct cycle output directory
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`

package/pro/squads/design/tasks/ds-critical-eye-score.md

@@ -1,109 +1,109 @@
-# Critical Eye — Score Variants Using 5 Dimensions
-
-> Task ID: ds-critical-eye-score
-> Agent: Brad Frost (Design System Architect)
-> Version: 1.0.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[ds-critical-eye-inventory]` · enables: `[ds-critical-eye-compare]` · workflow: `critical-eye`
-
-## Description
-
-Apply the Critical Eye scoring engine to every variant in the inventory. The engine evaluates 5 dimensions totaling 100 points: Breadth (25), Quality (30), Consistency (20), Maturity (15), Simplicity (10). Includes the absolute blocker: accessibility score = 0 triggers automatic REJECT regardless of total.
-
-Authority: Nathan Curtis/EightShapes, GOV.UK Contribution Criteria, USWDS Lifecycle, Brad Frost — Death to Complexity.
-
-## Output Schema
-- **produces:** `outputs/design-system/critical-eye/cycle-{N}/scored.json`
-- **format:** JSON — each variant with detailed per-dimension scores
-- **consumed_by:** ds-critical-eye-compare
-
-## Prerequisites
-
-- Inventory output from `ds-critical-eye-inventory` available
-- `squads/design/data/critical-eye-scoring-rules.yaml` loaded
-- Component source files accessible for quality evaluation
-- Component metadata JSONs accessible for enrichment
-
-## Workflow
-
-### Steps
-
-1. **Load Inputs**
-   - Read inventory JSON from previous step
-   - Read `critical-eye-scoring-rules.yaml` — full scoring configuration
-   - Check: both files valid and compatible (same cycle number)
-
-2. **Score Breadth (25 pts) — Nathan Curtis Breadth Scale**
-   - For each variant:
-     - Count `variant.sources.length`
-     - Apply rule: 1 source = 0pts (snowflake), 2 = 10pts (discuss), 3 = 15pts (probable), 4 = 20pts (strong), 5+ = 25pts (confirmed)
-   - Check: breadth score assigned to every variant
-
-3. **Score Quality (30 pts) — EightShapes Component QA**
-   - For each variant, evaluate 6 sub-dimensions:
-     - **token_compliance** (5pts): Count hardcoded values in source files (`#hex`, `Npx` except 0px). 0 hardcoded = 5pts, <5 = 3pts, 5-10 = 1pt, >10 = 0pts
-     - **states_coverage** (5pts): Count states implemented vs reference [default, hover, focus, disabled, error, loading]. Prorated: (implemented / 6) * 5
-     - **accessibility** (5pts, BLOCKER): Check WCAG AA contrast, ARIA attributes, keyboard nav, focus-visible. Score 0 = AUTOMATIC REJECT
-     - **responsiveness** (5pts): Check breakpoints coverage (mobile/tablet/desktop). All 3 = 5pts, 2 = 3pts, 1 = 1pt, fixed = 0pts
-     - **composability** (5pts): Evaluate how well it composes with other catalog variants. 3+ canonicals = 5pts, 1-2 = 3pts, requires adaptation = 1pt, incompatible = 0pts
-     - **resilience** (5pts): Test edge cases [empty content, long text, overflow, missing image, RTL]. All = 5pts, 3+ = 3pts, 1-2 = 1pt, none = 0pts
-   - Sum sub-dimensions for quality total
-   - Check: quality.accessibility evaluated — if 0, immediately flag variant for REJECT
-
-4. **Score Consistency (20 pts) — GOV.UK Contribution Criteria**
-   - For each variant, evaluate 3 sub-dimensions:
-     - **naming** (5pts): Check naming conventions (kebab-case, semantic prefixes). 100% = 5pts, minor desvios = 3pts, inconsistent = 0pts
-     - **api_patterns** (5pts): Check CVA + variant pattern + slot pattern usage. Full = 5pts, partial = 3pts, different API = 0pts
-     - **visual_harmony** (10pts): Evaluate visual coherence with DS. Indistinguishable = 10pts, small differences = 7pts, recognizably different = 4pts, conflicts = 0pts
-   - Check: consistency total calculated for all variants
-
-5. **Score Maturity (15 pts) — USWDS Component Lifecycle**
-   - For each variant, evaluate 3 sub-dimensions:
-     - **stability** (5pts): Check lifecycleHistory for breaking changes. No changes in 3+ cycles = 5pts, minor in last = 3pts, major recent = 1pt, new = 0pts
-     - **documentation** (5pts): Check for guidelines + API + examples + do/dont. Full = 5pts, partial = 3pts, JSDoc only = 1pt, none = 0pts
-     - **tests** (5pts): Check for unit + visual regression + a11y tests. All = 5pts, unit only = 3pts, smoke = 1pt, none = 0pts
-   - Check: maturity total calculated
-
-6. **Score Simplicity (10 pts) — Brad Frost Death to Complexity**
-   - For each variant, evaluate 2 sub-dimensions:
-     - **complexity** (5pts): Count LOC of main component file. <50 = 5pts, 50-150 = 3pts, 150-300 = 1pt, >300 = 0pts
-     - **dependencies** (5pts): Count external deps (excluding React + CVA). 0 = 5pts, 1-2 = 3pts, 3-5 = 1pt, 6+ = 0pts
-   - Check: simplicity total calculated
-
-7. **Calculate Total Score**
-   - Sum all 5 dimension totals: breadth + quality + consistency + maturity + simplicity
-   - Maximum possible: 25 + 30 + 20 + 15 + 10 = 100
-   - Check: total is between 0 and 100 for all variants
-
-8. **Apply Accessibility Blocker**
-   - For any variant where `quality.accessibility == 0`:
-     - Override lifecycle to `REJECT`
-     - Flag with `blocker: "accessibility_zero"`
-     - Log: "Variant {id} REJECTED — accessibility score 0 is absolute blocker"
-   - Check: all a11y-zero variants flagged
-
-9. **Generate Scored Output**
-   - Create `scored.json` with each variant's complete score breakdown
-   - Include dimension totals, sub-dimension details, and any blocker flags
-   - Check: output valid JSON, all variants scored
-
-## Failure Handling
-
-- **Inventory not found:** Abort with "Run ds-critical-eye-inventory first."
-- **Source files missing:** Score quality dimensions as 0 with note "source files not found"
-- **Scoring rules invalid:** Abort with YAML parsing error details
-
-## Success Criteria
-
-- [ ] All 5 dimensions scored for every variant
-- [ ] Breadth based on actual source counts
-- [ ] Quality evaluated against real component source code
-- [ ] Accessibility blocker applied (score=0 → REJECT)
-- [ ] Total scores between 0-100
-- [ ] Scored JSON output complete and valid
-- [ ] No dimension left as null after evaluation
-
-## Related Checklists
-
-- `squads/design/checklists/ds-critical-eye-review-checklist.md`
+# Critical Eye — Score Variants Using 5 Dimensions
+
+> Task ID: ds-critical-eye-score
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-critical-eye-inventory]` · enables: `[ds-critical-eye-compare]` · workflow: `critical-eye`
+
+## Description
+
+Apply the Critical Eye scoring engine to every variant in the inventory. The engine evaluates 5 dimensions totaling 100 points: Breadth (25), Quality (30), Consistency (20), Maturity (15), Simplicity (10). Includes the absolute blocker: accessibility score = 0 triggers automatic REJECT regardless of total.
+
+Authority: Nathan Curtis/EightShapes, GOV.UK Contribution Criteria, USWDS Lifecycle, Brad Frost — Death to Complexity.
+
+## Output Schema
+- **produces:** `outputs/design-system/critical-eye/cycle-{N}/scored.json`
+- **format:** JSON — each variant with detailed per-dimension scores
+- **consumed_by:** ds-critical-eye-compare
+
+## Prerequisites
+
+- Inventory output from `ds-critical-eye-inventory` available
+- `squads/design/data/critical-eye-scoring-rules.yaml` loaded
+- Component source files accessible for quality evaluation
+- Component metadata JSONs accessible for enrichment
+
+## Workflow
+
+### Steps
+
+1. **Load Inputs**
+   - Read inventory JSON from previous step
+   - Read `critical-eye-scoring-rules.yaml` — full scoring configuration
+   - Check: both files valid and compatible (same cycle number)
+
+2. **Score Breadth (25 pts) — Nathan Curtis Breadth Scale**
+   - For each variant:
+     - Count `variant.sources.length`
+     - Apply rule: 1 source = 0pts (snowflake), 2 = 10pts (discuss), 3 = 15pts (probable), 4 = 20pts (strong), 5+ = 25pts (confirmed)
+   - Check: breadth score assigned to every variant
+
+3. **Score Quality (30 pts) — EightShapes Component QA**
+   - For each variant, evaluate 6 sub-dimensions:
+     - **token_compliance** (5pts): Count hardcoded values in source files (`#hex`, `Npx` except 0px). 0 hardcoded = 5pts, <5 = 3pts, 5-10 = 1pt, >10 = 0pts
+     - **states_coverage** (5pts): Count states implemented vs reference [default, hover, focus, disabled, error, loading]. Prorated: (implemented / 6) * 5
+     - **accessibility** (5pts, BLOCKER): Check WCAG AA contrast, ARIA attributes, keyboard nav, focus-visible. Score 0 = AUTOMATIC REJECT
+     - **responsiveness** (5pts): Check breakpoints coverage (mobile/tablet/desktop). All 3 = 5pts, 2 = 3pts, 1 = 1pt, fixed = 0pts
+     - **composability** (5pts): Evaluate how well it composes with other catalog variants. 3+ canonicals = 5pts, 1-2 = 3pts, requires adaptation = 1pt, incompatible = 0pts
+     - **resilience** (5pts): Test edge cases [empty content, long text, overflow, missing image, RTL]. All = 5pts, 3+ = 3pts, 1-2 = 1pt, none = 0pts
+   - Sum sub-dimensions for quality total
+   - Check: quality.accessibility evaluated — if 0, immediately flag variant for REJECT
+
+4. **Score Consistency (20 pts) — GOV.UK Contribution Criteria**
+   - For each variant, evaluate 3 sub-dimensions:
+     - **naming** (5pts): Check naming conventions (kebab-case, semantic prefixes). 100% = 5pts, minor desvios = 3pts, inconsistent = 0pts
+     - **api_patterns** (5pts): Check CVA + variant pattern + slot pattern usage. Full = 5pts, partial = 3pts, different API = 0pts
+     - **visual_harmony** (10pts): Evaluate visual coherence with DS. Indistinguishable = 10pts, small differences = 7pts, recognizably different = 4pts, conflicts = 0pts
+   - Check: consistency total calculated for all variants
+
+5. **Score Maturity (15 pts) — USWDS Component Lifecycle**
+   - For each variant, evaluate 3 sub-dimensions:
+     - **stability** (5pts): Check lifecycleHistory for breaking changes. No changes in 3+ cycles = 5pts, minor in last = 3pts, major recent = 1pt, new = 0pts
+     - **documentation** (5pts): Check for guidelines + API + examples + do/dont. Full = 5pts, partial = 3pts, JSDoc only = 1pt, none = 0pts
+     - **tests** (5pts): Check for unit + visual regression + a11y tests. All = 5pts, unit only = 3pts, smoke = 1pt, none = 0pts
+   - Check: maturity total calculated
+
+6. **Score Simplicity (10 pts) — Brad Frost Death to Complexity**
+   - For each variant, evaluate 2 sub-dimensions:
+     - **complexity** (5pts): Count LOC of main component file. <50 = 5pts, 50-150 = 3pts, 150-300 = 1pt, >300 = 0pts
+     - **dependencies** (5pts): Count external deps (excluding React + CVA). 0 = 5pts, 1-2 = 3pts, 3-5 = 1pt, 6+ = 0pts
+   - Check: simplicity total calculated
+
+7. **Calculate Total Score**
+   - Sum all 5 dimension totals: breadth + quality + consistency + maturity + simplicity
+   - Maximum possible: 25 + 30 + 20 + 15 + 10 = 100
+   - Check: total is between 0 and 100 for all variants
+
+8. **Apply Accessibility Blocker**
+   - For any variant where `quality.accessibility == 0`:
+     - Override lifecycle to `REJECT`
+     - Flag with `blocker: "accessibility_zero"`
+     - Log: "Variant {id} REJECTED — accessibility score 0 is absolute blocker"
+   - Check: all a11y-zero variants flagged
+
+9. **Generate Scored Output**
+   - Create `scored.json` with each variant's complete score breakdown
+   - Include dimension totals, sub-dimension details, and any blocker flags
+   - Check: output valid JSON, all variants scored
+
+## Failure Handling
+
+- **Inventory not found:** Abort with "Run ds-critical-eye-inventory first."
+- **Source files missing:** Score quality dimensions as 0 with note "source files not found"
+- **Scoring rules invalid:** Abort with YAML parsing error details
+
+## Success Criteria
+
+- [ ] All 5 dimensions scored for every variant
+- [ ] Breadth based on actual source counts
+- [ ] Quality evaluated against real component source code
+- [ ] Accessibility blocker applied (score=0 → REJECT)
+- [ ] Total scores between 0-100
+- [ ] Scored JSON output complete and valid
+- [ ] No dimension left as null after evaluation
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`

package/pro/squads/design/tasks/ds-designops.md

@@ -1,99 +1,99 @@
-# Setup DesignOps Workflow
-
-> Task ID: brad-ds-designops
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Hybrid`
-> **Human Checkpoint:** Review and approve the operational playbook and metrics dashboard configuration before rollout to the team
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `governance`
-
-## Description
-
-Setup DesignOps workflow for your design system team. Maps current operations, identifies bottlenecks, defines metrics, creates operational playbook, and configures dashboards.
-
-## Prerequisites
-
-- Active design system with at least 1 dedicated team member
-- Understanding of current DS workflow (even if informal)
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - DS team size and roles
-   - Current workflow (how components go from idea to production)
-   - Known bottlenecks or pain points
-   - Tools in use (Figma, Storybook, CI/CD, docs)
-
-### Steps
-
-1. **Map Current Operations**
-   - Document current component lifecycle (request → design → build → test → release)
-   - Identify handoff points between design and development
-   - Map review and approval cycles
-   - Document release process
-   - Check: workflow map has >= 1 stage AND each stage has owner + timeline — abort with "Workflow map incomplete: {N} stages missing owners or timelines"
-
-2. **Identify Bottlenecks**
-   - Design-to-dev handoff delays
-   - Review cycle length
-   - Release cadence gaps
-   - Documentation lag
-   - Consumer adoption barriers
-   - Check: bottleneck count >= 0 AND each has estimated impact (hours/sprint or cost) — log "Found {N} bottlenecks with total estimated impact of {hours} hours/sprint"
-
-3. **Define DesignOps Metrics**
-   - **Adoption rate:** % of product teams using DS components
-   - **Contribution velocity:** Components contributed per sprint/month
-   - **Time-to-component:** Days from request to production release
-   - **Coverage:** % of UI built with DS components vs. custom
-   - **Satisfaction:** Consumer team satisfaction score (survey)
-   - Check: each metric has data source identified AND collection method defined — abort with "Unmeasurable metrics: {list of metrics without data sources}"
-
-4. **Create Operational Playbook**
-   - Component request process
-   - Design review checklist
-   - Code review checklist
-   - Release checklist
-   - Onboarding guide for new DS team members
-   - Check: playbook contains sections for request, design review, code review, release, and onboarding — abort with "Playbook missing lifecycle stages: {list}"
-
-5. **Configure Metrics Dashboard**
-   - Define data sources for each metric
-   - Recommend dashboard tool (GitHub insights, custom, Notion)
-   - Create dashboard template with metric calculations
-   - Define review cadence (weekly/monthly)
-   - Update .state.yaml
-
-## Output
-
-- `designops-playbook.md` — Complete operational playbook
-- `designops-metrics.md` — Metric definitions and targets
-- `dashboard-config.md` — Dashboard setup and data sources
-- `.state.yaml` updated
-
-## Related Checklists
-
-- `squads/design/checklists/designops-maturity-checklist.md`
-- `squads/design/checklists/design-handoff-checklist.md`
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
-
-## Failure Handling
-
-- **Workflow mapping incomplete:** Request stakeholder interviews, document known stages with confidence scores, flag gaps requiring additional discovery, defer playbook creation until >=80% coverage achieved
-- **Metrics lack measurable data sources:** For each unmeasurable metric, propose proxy metrics with available data or recommend instrumentation additions, prioritize metrics by business impact
-- **Bottleneck impact cannot be quantified:** Run time-tracking pilot (1 sprint), instrument handoff points with timestamps, calculate actual vs. theoretical cycle time to establish baseline
-- **Dashboard tool integration fails:** Fallback to spreadsheet-based dashboard template, provide manual update instructions, estimate effort for custom dashboard implementation with available resources
-
-## Success Criteria
-
-- Complete workflow mapped with bottlenecks identified
-- Metrics are defined, measurable, and have targets
-- Playbook covers entire component lifecycle
-- Dashboard can be implemented with available tools
-
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Setup DesignOps Workflow
+
+> Task ID: brad-ds-designops
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Hybrid`
+> **Human Checkpoint:** Review and approve the operational playbook and metrics dashboard configuration before rollout to the team
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `governance`
+
+## Description
+
+Setup DesignOps workflow for your design system team. Maps current operations, identifies bottlenecks, defines metrics, creates operational playbook, and configures dashboards.
+
+## Prerequisites
+
+- Active design system with at least 1 dedicated team member
+- Understanding of current DS workflow (even if informal)
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - DS team size and roles
+   - Current workflow (how components go from idea to production)
+   - Known bottlenecks or pain points
+   - Tools in use (Figma, Storybook, CI/CD, docs)
+
+### Steps
+
+1. **Map Current Operations**
+   - Document current component lifecycle (request → design → build → test → release)
+   - Identify handoff points between design and development
+   - Map review and approval cycles
+   - Document release process
+   - Check: workflow map has >= 1 stage AND each stage has owner + timeline — abort with "Workflow map incomplete: {N} stages missing owners or timelines"
+
+2. **Identify Bottlenecks**
+   - Design-to-dev handoff delays
+   - Review cycle length
+   - Release cadence gaps
+   - Documentation lag
+   - Consumer adoption barriers
+   - Check: bottleneck count >= 0 AND each has estimated impact (hours/sprint or cost) — log "Found {N} bottlenecks with total estimated impact of {hours} hours/sprint"
+
+3. **Define DesignOps Metrics**
+   - **Adoption rate:** % of product teams using DS components
+   - **Contribution velocity:** Components contributed per sprint/month
+   - **Time-to-component:** Days from request to production release
+   - **Coverage:** % of UI built with DS components vs. custom
+   - **Satisfaction:** Consumer team satisfaction score (survey)
+   - Check: each metric has data source identified AND collection method defined — abort with "Unmeasurable metrics: {list of metrics without data sources}"
+
+4. **Create Operational Playbook**
+   - Component request process
+   - Design review checklist
+   - Code review checklist
+   - Release checklist
+   - Onboarding guide for new DS team members
+   - Check: playbook contains sections for request, design review, code review, release, and onboarding — abort with "Playbook missing lifecycle stages: {list}"
+
+5. **Configure Metrics Dashboard**
+   - Define data sources for each metric
+   - Recommend dashboard tool (GitHub insights, custom, Notion)
+   - Create dashboard template with metric calculations
+   - Define review cadence (weekly/monthly)
+   - Update .state.yaml
+
+## Output
+
+- `designops-playbook.md` — Complete operational playbook
+- `designops-metrics.md` — Metric definitions and targets
+- `dashboard-config.md` — Dashboard setup and data sources
+- `.state.yaml` updated
+
+## Related Checklists
+
+- `squads/design/checklists/designops-maturity-checklist.md`
+- `squads/design/checklists/design-handoff-checklist.md`
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+## Failure Handling
+
+- **Workflow mapping incomplete:** Request stakeholder interviews, document known stages with confidence scores, flag gaps requiring additional discovery, defer playbook creation until >=80% coverage achieved
+- **Metrics lack measurable data sources:** For each unmeasurable metric, propose proxy metrics with available data or recommend instrumentation additions, prioritize metrics by business impact
+- **Bottleneck impact cannot be quantified:** Run time-tracking pilot (1 sprint), instrument handoff points with timestamps, calculate actual vs. theoretical cycle time to establish baseline
+- **Dashboard tool integration fails:** Fallback to spreadsheet-based dashboard template, provide manual update instructions, estimate effort for custom dashboard implementation with available resources
+
+## Success Criteria
+
+- Complete workflow mapped with bottlenecks identified
+- Metrics are defined, measurable, and have targets
+- Playbook covers entire component lifecycle
+- Dashboard can be implemented with available tools
+
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.