aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/tasks/execute-checklist.md

@@ -1,141 +1,141 @@
-# Checklist Validation Task
-
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `standalone`
-
-This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
-
-## Available Checklists
-
-If the user asks or does not specify a specific checklist, list the checklists available in `squads/design/checklists/`.
-
-## Local Checklist Catalog (`squads/design/checklists/`)
-
-- `atomic-refactor-checklist.md`
-- `design-fidelity-checklist.md`
-- `design-handoff-checklist.md`
-- `design-team-health-checklist.md`
-- `designops-maturity-checklist.md`
-- `ds-a11y-release-gate-checklist.md`
-- `ds-accessibility-wcag-checklist.md`
-- `ds-component-quality-checklist.md`
-- `ds-migration-readiness-checklist.md`
-- `ds-pattern-audit-checklist.md`
-- `reading-accessibility-checklist.md`
-
-## Instructions
-
-1. **Initial Assessment**
-
-   - If user or the task being run provides a checklist name:
-     - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
-     - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from `squads/design/checklists/`
-   - If no checklist specified:
-     - Ask the user which checklist they want to use
-     - Present the available options from `squads/design/checklists/`
-   - Confirm if they want to work through the checklist:
-     - Section by section (interactive mode - very time consuming)
-     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
-
-2. **Document and Artifact Gathering**
-
-   - Each checklist will specify its required documents/artifacts at the beginning
-   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
-
-3. **Checklist Processing**
-
-   If in interactive mode:
-
-   - Work through each section of the checklist one at a time
-   - For each section:
-     - Review all items in the section following instructions for that section embedded in the checklist
-     - Check each item against the relevant documentation or artifacts as appropriate
-     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
-     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
-
-   If in YOLO mode:
-
-   - Process all sections at once
-   - Create a comprehensive report of all findings
-   - Present the complete analysis to the user
-
-4. **Validation Approach**
-
-   For each checklist item:
-
-   - Read and understand the requirement
-   - Look for evidence in the documentation that satisfies the requirement
-   - Consider both explicit mentions and implicit coverage
-   - Aside from this, follow all checklist llm instructions
-   - Mark items as:
-     - ✅ PASS: Requirement clearly met
-     - ❌ FAIL: Requirement not met or insufficient coverage
-     - ⚠️ PARTIAL: Some aspects covered but needs improvement
-     - N/A: Not applicable to this case
-
-5. **Section Analysis**
-
-   For each section:
-
-   - think step by step to calculate pass rate
-   - Identify common themes in failed items
-   - Provide specific recommendations for improvement
-   - In interactive mode, discuss findings with user
-   - Document any user decisions or explanations
-
-6. **Final Report**
-
-   Prepare a summary that includes:
-
-   - Overall checklist completion status
-   - Pass rates by section
-   - List of failed items with context
-   - Specific recommendations for improvement
-   - Any sections or items marked as N/A with justification
-
-## Checklist Execution Methodology
-
-Each checklist now contains embedded LLM prompts and instructions that will:
-
-1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
-2. **Request specific artifacts** - Clear instructions on what documents/access is needed
-3. **Provide contextual guidance** - Section-specific prompts for better validation
-4. **Generate comprehensive reports** - Final summary with detailed findings
-
-The LLM will:
-
-- Execute the complete checklist validation
-- Present a final report with pass/fail rates and key findings
-- Offer to provide detailed analysis of any section, especially those with warnings or failures
-
-## Failure Handling
-
-- **Multiple checklists match user query:** Present disambiguation list with each checklist's primary purpose, ask user to select by number or refine query
-- **Required documentation artifacts missing or inaccessible:** Flag missing items, proceed with partial validation marking dependent checklist items as BLOCKED, document gaps in final report
-- **Checklist scoring results in ambiguous pass/fail boundary:** Calculate confidence intervals, highlight borderline items, recommend manual review for items within 10% of threshold
-- **User disagrees with automated verdict for specific items:** Document user override with justification, recalculate section scores excluding overridden items, append dissenting analysis to report
-
-## Success Criteria
-
-- [ ] Correct checklist identified and loaded (exact or fuzzy match)
-- [ ] All required documents/artifacts gathered before validation
-- [ ] Every checklist item evaluated with PASS/FAIL/N-A verdict
-- [ ] Non-applicable items include rationale for exclusion
-- [ ] Summary report generated with section-by-section breakdown
-- [ ] Scoring calculated per checklist's scoring system
-- [ ] Critical failures flagged for immediate attention
-
-## Output
-
-- Checklist execution report with section pass rates
-- List of failed/partial items with evidence
-- Remediation list prioritized by severity
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Checklist Validation Task
+
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `standalone`
+
+This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
+
+## Available Checklists
+
+If the user asks or does not specify a specific checklist, list the checklists available in `squads/design/checklists/`.
+
+## Local Checklist Catalog (`squads/design/checklists/`)
+
+- `atomic-refactor-checklist.md`
+- `design-fidelity-checklist.md`
+- `design-handoff-checklist.md`
+- `design-team-health-checklist.md`
+- `designops-maturity-checklist.md`
+- `ds-a11y-release-gate-checklist.md`
+- `ds-accessibility-wcag-checklist.md`
+- `ds-component-quality-checklist.md`
+- `ds-migration-readiness-checklist.md`
+- `ds-pattern-audit-checklist.md`
+- `reading-accessibility-checklist.md`
+
+## Instructions
+
+1. **Initial Assessment**
+
+   - If user or the task being run provides a checklist name:
+     - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
+     - If multiple matches found, ask user to clarify
+     - Load the appropriate checklist from `squads/design/checklists/`
+   - If no checklist specified:
+     - Ask the user which checklist they want to use
+     - Present the available options from `squads/design/checklists/`
+   - Confirm if they want to work through the checklist:
+     - Section by section (interactive mode - very time consuming)
+     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
+
+2. **Document and Artifact Gathering**
+
+   - Each checklist will specify its required documents/artifacts at the beginning
+   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
+
+3. **Checklist Processing**
+
+   If in interactive mode:
+
+   - Work through each section of the checklist one at a time
+   - For each section:
+     - Review all items in the section following instructions for that section embedded in the checklist
+     - Check each item against the relevant documentation or artifacts as appropriate
+     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
+     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
+
+   If in YOLO mode:
+
+   - Process all sections at once
+   - Create a comprehensive report of all findings
+   - Present the complete analysis to the user
+
+4. **Validation Approach**
+
+   For each checklist item:
+
+   - Read and understand the requirement
+   - Look for evidence in the documentation that satisfies the requirement
+   - Consider both explicit mentions and implicit coverage
+   - Aside from this, follow all checklist llm instructions
+   - Mark items as:
+     - ✅ PASS: Requirement clearly met
+     - ❌ FAIL: Requirement not met or insufficient coverage
+     - ⚠️ PARTIAL: Some aspects covered but needs improvement
+     - N/A: Not applicable to this case
+
+5. **Section Analysis**
+
+   For each section:
+
+   - think step by step to calculate pass rate
+   - Identify common themes in failed items
+   - Provide specific recommendations for improvement
+   - In interactive mode, discuss findings with user
+   - Document any user decisions or explanations
+
+6. **Final Report**
+
+   Prepare a summary that includes:
+
+   - Overall checklist completion status
+   - Pass rates by section
+   - List of failed items with context
+   - Specific recommendations for improvement
+   - Any sections or items marked as N/A with justification
+
+## Checklist Execution Methodology
+
+Each checklist now contains embedded LLM prompts and instructions that will:
+
+1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
+2. **Request specific artifacts** - Clear instructions on what documents/access is needed
+3. **Provide contextual guidance** - Section-specific prompts for better validation
+4. **Generate comprehensive reports** - Final summary with detailed findings
+
+The LLM will:
+
+- Execute the complete checklist validation
+- Present a final report with pass/fail rates and key findings
+- Offer to provide detailed analysis of any section, especially those with warnings or failures
+
+## Failure Handling
+
+- **Multiple checklists match user query:** Present disambiguation list with each checklist's primary purpose, ask user to select by number or refine query
+- **Required documentation artifacts missing or inaccessible:** Flag missing items, proceed with partial validation marking dependent checklist items as BLOCKED, document gaps in final report
+- **Checklist scoring results in ambiguous pass/fail boundary:** Calculate confidence intervals, highlight borderline items, recommend manual review for items within 10% of threshold
+- **User disagrees with automated verdict for specific items:** Document user override with justification, recalculate section scores excluding overridden items, append dissenting analysis to report
+
+## Success Criteria
+
+- [ ] Correct checklist identified and loaded (exact or fuzzy match)
+- [ ] All required documents/artifacts gathered before validation
+- [ ] Every checklist item evaluated with PASS/FAIL/N-A verdict
+- [ ] Non-applicable items include rationale for exclusion
+- [ ] Summary report generated with section-by-section breakdown
+- [ ] Scoring calculated per checklist's scoring system
+- [ ] Critical failures flagged for immediate attention
+
+## Output
+
+- Checklist execution report with section pass rates
+- List of failed/partial items with evidence
+- Remediation list prioritized by severity
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/export-design-tokens-dtcg.md

@@ -1,97 +1,97 @@
-# Export Design Tokens to W3C DTCG
-
-> Task ID: brad-export-design-tokens-dtcg
-> Agent: Brad (Design System Architect)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Worker`
-> **Dependencies:** depends_on: `[]` · enables: `[ds-token-w3c-extract]` · workflow: `tokens`
-
-## Description
-
-Produce W3C Design Tokens (DTCG v1.0.0 stable) exports from the canonical YAML tokens file. Validates schema compliance, OKLCH color usage, and publishes artifacts for downstream platforms (web, iOS, Android, Flutter). **v4.0: References w3c-dtcg-spec-reference.md for spec compliance. Uses $value, $type, $description format per W3C DTCG v1.0 stable (October 2025).**
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/tokens/dtcg-exports/`
-- **format:** JSON data (W3C DTCG v1.0 multi-platform)
-- **consumed_by:** ds-token-w3c-extract
-
-## Prerequisites
-
-- tokens.yaml generated via *tokenize (core/semantic/component layers present)
-- Node.js ≥ 18 / Python ≥ 3.10 (for validation tools)
-- DTCG CLI or schema validator installed (`npm install -g @designtokens/cli` recommended)
-- Reference: Read data/w3c-dtcg-spec-reference.md for W3C DTCG v1.0 stable format
-
-## Workflow
-
-1. **Load Source Tokens**
-   - Read `tokens.yaml` and confirm metadata (dtcg_spec, color_space)
-   - Ensure layers exist: `core`, `semantic`, `component`
-   - Verify coverage >95% stored in `.state.yaml`
-
-2. **Generate DTCG JSON**
-   - Transform YAML into DTCG JSON structure
-   - Ensure each token includes `$type`, `$value`, optional `$description`
-   - Map references using `{layers.semantic.color.primary}` style
-   - Save as `tokens.dtcg.json`
-
-3. **Produce Platform Bundles (Optional)**
-   - Run Style Dictionary / custom scripts for platform-specific outputs
-   - Targets: web (CSS), Android (XML), iOS (Swift), Flutter (Dart)
-   - Store under `tokens/exports/{platform}/`
-
-4. **Validate**
-   - `dtcg validate tokens.dtcg.json`
-   - Lint OKLCH values (ensure `oklch()` format, fallback to hex flagged)
-   - Confirm references resolve (no missing paths)
-
-5. **Document & Publish**
-   - Update `docs/tokens/README.md` with export details, version, changelog
-   - Attach validator output and coverage metrics
-   - Update `.state.yaml` (tokens.dtcg path, validator status, timestamp)
-
-## Output
-
-- `tokens.dtcg.json` (W3C compliant)
-- Optional platform bundles (CSS, Android XML, Swift, Flutter)
-- Validation report (`tokens/validation/dtcg-report.json`)
-- Updated `.state.yaml` tokens section
-
-## Failure Handling
-
-- **W3C validator fails with schema errors:** Isolate offending tokens, generate compliant subset for immediate use, quarantine invalid tokens to separate file with validation error annotations
-- **Token reference resolution breaks due to circular dependencies:** Detect cycle path, break loop by inlining deepest reference, log resolution strategy and affected tokens in validation report
-- **Platform export tool crashes on unsupported token types:** Skip incompatible token types for that platform, document exclusions in platform-specific README, generate warning manifest listing unsupported features
-- **OKLCH color conversion produces out-of-gamut RGB values:** Clamp to sRGB gamut with perceptual lightness preservation, append fallback hex values as `$extensions`, flag colors requiring manual adjustment
-
-## Success Criteria
-
-- [ ] tokens.dtcg.json passes W3C validator with zero errors
-- [ ] OKLCH color space used; fallbacks documented
-- [ ] References (`$value`) resolve across layers
-- [ ] Platform exports updated (if enabled) and smoke-tested
-- [ ] Documentation + changelog refreshed with version/date
-- [ ] `.state.yaml` reflects dtcg export path and status
-
-## Error Handling
-
-- **Invalid schema**: Capture validator output, fix offending tokens, rerun export
-- **Missing reference**: Trace YAML source, ensure token exists or adjust alias
-- **Unsupported color format**: Convert to OKLCH or fallback with explanation
-- **Platform export failure**: Roll back platform-specific step, flag follow-up action
-
-## Notes
-
-- Keep token versions semantically versioned (e.g., 1.1.0 for new tokens)
-- Coordinate with platform teams before breaking changes (e.g., renaming tokens)
-- Store validation reports alongside artifacts for audit/compliance
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Export Design Tokens to W3C DTCG
+
+> Task ID: brad-export-design-tokens-dtcg
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-token-w3c-extract]` · workflow: `tokens`
+
+## Description
+
+Produce W3C Design Tokens (DTCG v1.0.0 stable) exports from the canonical YAML tokens file. Validates schema compliance, OKLCH color usage, and publishes artifacts for downstream platforms (web, iOS, Android, Flutter). **v4.0: References w3c-dtcg-spec-reference.md for spec compliance. Uses $value, $type, $description format per W3C DTCG v1.0 stable (October 2025).**
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/tokens/dtcg-exports/`
+- **format:** JSON data (W3C DTCG v1.0 multi-platform)
+- **consumed_by:** ds-token-w3c-extract
+
+## Prerequisites
+
+- tokens.yaml generated via *tokenize (core/semantic/component layers present)
+- Node.js ≥ 18 / Python ≥ 3.10 (for validation tools)
+- DTCG CLI or schema validator installed (`npm install -g @designtokens/cli` recommended)
+- Reference: Read data/w3c-dtcg-spec-reference.md for W3C DTCG v1.0 stable format
+
+## Workflow
+
+1. **Load Source Tokens**
+   - Read `tokens.yaml` and confirm metadata (dtcg_spec, color_space)
+   - Ensure layers exist: `core`, `semantic`, `component`
+   - Verify coverage >95% stored in `.state.yaml`
+
+2. **Generate DTCG JSON**
+   - Transform YAML into DTCG JSON structure
+   - Ensure each token includes `$type`, `$value`, optional `$description`
+   - Map references using `{layers.semantic.color.primary}` style
+   - Save as `tokens.dtcg.json`
+
+3. **Produce Platform Bundles (Optional)**
+   - Run Style Dictionary / custom scripts for platform-specific outputs
+   - Targets: web (CSS), Android (XML), iOS (Swift), Flutter (Dart)
+   - Store under `tokens/exports/{platform}/`
+
+4. **Validate**
+   - `dtcg validate tokens.dtcg.json`
+   - Lint OKLCH values (ensure `oklch()` format, fallback to hex flagged)
+   - Confirm references resolve (no missing paths)
+
+5. **Document & Publish**
+   - Update `docs/tokens/README.md` with export details, version, changelog
+   - Attach validator output and coverage metrics
+   - Update `.state.yaml` (tokens.dtcg path, validator status, timestamp)
+
+## Output
+
+- `tokens.dtcg.json` (W3C compliant)
+- Optional platform bundles (CSS, Android XML, Swift, Flutter)
+- Validation report (`tokens/validation/dtcg-report.json`)
+- Updated `.state.yaml` tokens section
+
+## Failure Handling
+
+- **W3C validator fails with schema errors:** Isolate offending tokens, generate compliant subset for immediate use, quarantine invalid tokens to separate file with validation error annotations
+- **Token reference resolution breaks due to circular dependencies:** Detect cycle path, break loop by inlining deepest reference, log resolution strategy and affected tokens in validation report
+- **Platform export tool crashes on unsupported token types:** Skip incompatible token types for that platform, document exclusions in platform-specific README, generate warning manifest listing unsupported features
+- **OKLCH color conversion produces out-of-gamut RGB values:** Clamp to sRGB gamut with perceptual lightness preservation, append fallback hex values as `$extensions`, flag colors requiring manual adjustment
+
+## Success Criteria
+
+- [ ] tokens.dtcg.json passes W3C validator with zero errors
+- [ ] OKLCH color space used; fallbacks documented
+- [ ] References (`$value`) resolve across layers
+- [ ] Platform exports updated (if enabled) and smoke-tested
+- [ ] Documentation + changelog refreshed with version/date
+- [ ] `.state.yaml` reflects dtcg export path and status
+
+## Error Handling
+
+- **Invalid schema**: Capture validator output, fix offending tokens, rerun export
+- **Missing reference**: Trace YAML source, ensure token exists or adjust alias
+- **Unsupported color format**: Convert to OKLCH or fallback with explanation
+- **Platform export failure**: Roll back platform-specific step, flag follow-up action
+
+## Notes
+
+- Keep token versions semantically versioned (e.g., 1.1.0 for new tokens)
+- Coordinate with platform teams before breaking changes (e.g., renaming tokens)
+- Store validation reports alongside artifacts for audit/compliance
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.