aiwg 2026.3.0 → 2026.3.2

package/CLAUDE.md

@@ -39,7 +39,7 @@ src/                         # CLI and MCP server implementation
 test/                        # Test suites and fixtures
 tools/                       # Build and deployment scripts
 docs/                        # Documentation
-├── cli-reference.md         # All 42 CLI commands
+├── cli-reference.md         # All 44 CLI commands
 ├── extensions/              # Extension system docs
 │   ├── overview.md
 │   ├── creating-extensions.md
@@ -128,7 +128,7 @@ aiwg new my-project    # Scaffold new project
 aiwg help              # Show all commands
 aiwg doctor            # Check installation health
 
-# See @docs/cli-reference.md for all 42 commands
+# See @docs/cli-reference.md for all 47 commands
 ```
 
 ## Project Artifacts (.aiwg/)
@@ -177,9 +177,9 @@ AIWG uses a unified extension system for all extension types:
 - `@docs/extensions/creating-extensions.md` - Build custom extensions
 - `@docs/extensions/extension-types.md` - Complete type reference
 - `@src/extensions/types.ts` - TypeScript type definitions
-- `@src/extensions/commands/definitions.ts` - All 42 command definitions
+- `@src/extensions/commands/definitions.ts` - All 47 command definitions
 
-## CLI Commands (42 Total)
+## CLI Commands (47 Total)
 
 **See `@docs/cli-reference.md` for complete documentation.**
 
@@ -197,10 +197,12 @@ AIWG uses a unified extension system for all extension types:
 | **Utility** (3) | prefill-cards, contribute-start, validate-metadata |
 | **Plugin** (5) | install-plugin, uninstall-plugin, plugin-status, package-plugin, package-all-plugins |
 | **Scaffolding** (7) | add-agent, add-command, add-skill, add-template, scaffold-addon, scaffold-extension, scaffold-framework |
-| **Ralph** (4) | ralph, ralph-status, ralph-abort, ralph-resume |
+| **Ralph** (7) | ralph, ralph-status, ralph-abort, ralph-resume, ralph-external, ralph-memory, ralph-config |
 | **Metrics** (3) | cost-report, cost-history, metrics-tokens |
 | **Documentation** (1) | doc-sync |
 | **SDLC Orchestration** (1) | sdlc-accelerate |
+| **Code Analysis** (1) | cleanup-audit |
+| **Index** (1) | index (build, query, deps, stats) |
 | **Reproducibility** (4) | execution-mode, snapshot, checkpoint, reproducibility-validate |
 
 ### Quick Reference
@@ -242,6 +244,9 @@ aiwg ralph "Fix all tests" --completion "npm test passes"
 aiwg ralph-status            # Show loop status
 aiwg ralph-abort             # Stop loop
 aiwg ralph-resume            # Resume paused loop
+aiwg ralph-external "task"   # Crash-resilient external loop
+aiwg ralph-memory list       # Show debug memory entries
+aiwg ralph-config show       # Show Ralph configuration
 
 # Metrics
 aiwg cost-report             # Show cost report for session
@@ -258,6 +263,13 @@ aiwg sdlc-accelerate "Project description"  # Idea to construction-ready
 aiwg sdlc-accelerate --from-codebase .      # From existing code
 aiwg sdlc-accelerate --resume               # Resume pipeline
 
+# Artifact index
+aiwg index build                         # Build/rebuild artifact index
+aiwg index build --force --verbose       # Full rebuild with progress
+aiwg index query "authentication" --json # Search artifacts
+aiwg index deps .aiwg/requirements/UC-001.md --json  # Show dependencies
+aiwg index stats --json                  # Index statistics
+
 # Reproducibility
 aiwg execution-mode          # Show/set execution mode
 aiwg snapshot                # Create execution snapshot
@@ -351,6 +363,11 @@ aiwg validate-metadata
 
 # Check installation health
 aiwg doctor
+
+# Test local framework changes (see docs/development/dev-testing.md)
+aiwg --use-dev         # Point CLI at this repo
+aiwg use all           # Deploy from local source
+aiwg --use-stable      # Switch back to npm package
 ```
 
 ## Support

package/agentic/code/addons/color-palette/README.md

@@ -0,0 +1,81 @@
+# Color Palette Addon
+
+Standalone addon for color palette selection, analysis, and trend research. Helps users explore, evaluate, and select desirable color palettes using color theory fundamentals, current trend research, and cultural context from architecture, film, and design.
+
+## Installation
+
+```bash
+aiwg use color-palette
+```
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `color-palette` | Generate, analyze, compare, export, and suggest palettes |
+| `color-trends` | Research current color trends (Pantone, architecture, film, design) |
+| `color-accessibility` | WCAG accessibility analysis and contrast scoring |
+
+## Usage
+
+```bash
+# Generate a palette from a seed color
+/color-palette generate --seed "#2D5A27" --harmony triadic
+
+# Research current color trends
+/color-palette trends --category film
+
+# Analyze an existing palette
+/color-palette analyze --palette "#1a1a2e,#16213e,#0f3460,#e94560"
+
+# Compare two palettes
+/color-palette compare --a "#1a1a2e,#16213e,#0f3460" --b "#264653,#2a9d8f,#e9c46a"
+
+# Export palette to CSS/Tailwind/design tokens
+/color-palette export --palette "#264653,#2a9d8f,#e9c46a,#f4a261,#e76f51" --format tailwind
+
+# Extract palette from an image
+/color-palette from-image path/to/image.png
+
+# Get suggestions for a project type
+/color-palette suggest --industry healthcare --style modern --accessibility AA
+
+# Check accessibility of a palette
+/color-accessibility --palette "#1a1a2e,#e94560" --standard AA
+```
+
+## Color Theory
+
+The addon supports these harmony models:
+
+| Model | Description |
+|-------|-------------|
+| Complementary | Two colors opposite on the wheel |
+| Analogous | Three adjacent colors on the wheel |
+| Triadic | Three colors equally spaced (120 degrees apart) |
+| Split-complementary | Base + two colors adjacent to its complement |
+| Tetradic | Four colors forming a rectangle on the wheel |
+| Monochromatic | Variations of a single hue (lightness/saturation shifts) |
+
+## Export Formats
+
+- **HEX** — Standard hex codes (`#264653`)
+- **RGB** — RGB values (`rgb(38, 70, 83)`)
+- **HSL** — HSL values (`hsl(195, 37%, 24%)`)
+- **CSS Custom Properties** — `--color-primary: #264653;`
+- **Tailwind Config** — `colors: { primary: '#264653' }`
+- **Design Tokens** — JSON design token format
+
+## Accessibility
+
+Contrast ratios are calculated per WCAG 2.1:
+- **AA Normal Text**: minimum 4.5:1
+- **AA Large Text**: minimum 3:1
+- **AAA Normal Text**: minimum 7:1
+- **AAA Large Text**: minimum 4.5:1
+
+The addon generates a full contrast matrix showing all foreground/background combinations with pass/fail indicators.
+
+## Standalone
+
+This addon works independently of any framework. It does not require SDLC, marketing, or any other framework to be installed.

package/agentic/code/addons/color-palette/manifest.json

@@ -0,0 +1,32 @@
+{
+  "id": "color-palette",
+  "type": "addon",
+  "name": "Color Palette",
+  "version": "1.0.0",
+  "description": "Color palette selection and review tooling with color theory fundamentals, current trend research, and accessibility analysis.",
+  "core": false,
+  "autoInstall": false,
+  "author": "AIWG Contributors",
+  "license": "MIT",
+  "repository": "https://github.com/jmagly/aiwg",
+  "keywords": [
+    "color",
+    "palette",
+    "design",
+    "accessibility",
+    "color-theory",
+    "trends",
+    "wcag"
+  ],
+  "entry": {
+    "rules": "rules/",
+    "skills": "skills/",
+    "templates": "templates/"
+  },
+  "skills": [
+    "color-palette",
+    "color-trends",
+    "color-accessibility"
+  ],
+  "dependencies": []
+}

package/agentic/code/addons/color-palette/rules/color-output-format.md

@@ -0,0 +1,70 @@
+---
+id: color-output-format
+name: Color Output Format
+enforcement: MEDIUM
+scope: color-palette
+description: Consistent formatting for all color output across the color-palette addon.
+---
+
+# Color Output Format
+
+## Purpose
+
+Ensure all color output from the color-palette addon uses a consistent, readable format that works across terminals and documentation.
+
+## Rules
+
+### 1. Always Show Multiple Representations
+
+When displaying a color, include at minimum:
+- HEX code (6-digit, lowercase, with `#` prefix)
+- Visual swatch (ANSI color block if terminal supports it, or unicode block `██████`)
+- Human-readable name (descriptive, not generic)
+
+**Format**:
+```
+#rrggbb  ██████  Descriptive Name    (H:xxx S:xx% L:xx%)
+```
+
+### 2. HEX Normalization
+
+- Always use 6-digit lowercase HEX: `#2d5a27` not `#2D5A27` or `#2d5a27ff`
+- Expand 3-digit shorthand: `#fff` → `#ffffff`
+- Strip alpha channel for display (note alpha separately if relevant)
+
+### 3. Color Naming
+
+Generate descriptive names, not generic labels:
+- `Forest Green` not `Green`
+- `Desert Gold` not `Yellow`
+- `Steel Blue` not `Blue`
+- `Burgundy Dark` not `Dark Red`
+
+Use color name databases (X11, CSS named colors) as a starting point, then refine for specificity.
+
+### 4. Palette Display Order
+
+When displaying a palette:
+1. Order by intended role (primary → secondary → accent → neutral) if roles are known
+2. Otherwise order by hue (0-360 degrees)
+3. Within same hue, order dark to light
+
+### 5. Contrast Ratio Format
+
+Always display contrast ratios as `X.X:1` with one decimal place:
+- `4.5:1` not `4.51:1` or `4.5`
+- Include pass/fail indicator: `4.5:1 PASS` or `2.3:1 FAIL`
+
+### 6. Accessibility Indicators
+
+Use clear indicators for compliance:
+- `PASS` — meets the specified standard
+- `FAIL` — does not meet the specified standard
+- Specify which standard: `AA`, `AAA`, `AA Large Text`
+
+### 7. No Color-Only Communication
+
+Never convey meaning through color alone in output. Always pair color swatches with:
+- Text labels
+- HEX codes
+- Pass/fail text indicators

package/agentic/code/addons/color-palette/skills/color-accessibility.md

@@ -0,0 +1,188 @@
+---
+name: color-accessibility
+description: WCAG accessibility analysis for color palettes including contrast ratios, compliance checking, and remediation suggestions. Use when user needs to verify colors meet accessibility standards.
+version: 1.0.0
+---
+
+# Color Accessibility Skill
+
+## Purpose
+
+Analyze color palettes for WCAG 2.1 accessibility compliance. Calculate contrast ratios for all color pairs, identify failing combinations, and suggest fixes to meet AA or AAA standards.
+
+## When This Skill Applies
+
+- User asks "are these colors accessible?"
+- User wants to "check contrast ratios"
+- User needs "WCAG compliance" for a palette
+- User asks about "color accessibility"
+- User wants to ensure colors work for colorblind users
+- User mentions "AA" or "AAA" standards
+
+## Trigger Phrases
+
+| Natural Language | Action |
+|------------------|--------|
+| "Check if these colors are accessible" | Full WCAG analysis |
+| "What's the contrast ratio?" | Calculate specific pair ratio |
+| "Make this palette AA compliant" | Analyze + suggest fixes |
+| "Is this readable?" | Text contrast check |
+| "Color blind friendly?" | Color vision deficiency check |
+| "Fix the accessibility of this palette" | Remediation suggestions |
+
+## Parameters
+
+- `--palette <colors>` — Comma-separated color values to analyze
+- `--foreground <color>` — Specific foreground color (for pair check)
+- `--background <color>` — Specific background color (for pair check)
+- `--standard <level>` — Target standard: A, AA (default), AAA
+- `--fix` — Include remediation suggestions for failing pairs
+- `--matrix` — Show full contrast matrix for all pairs
+
+## Analysis Process
+
+### 1. Parse Colors
+
+Accept colors in any format and normalize to HEX + RGB + HSL:
+- HEX: `#1a1a2e`, `#fff`
+- RGB: `rgb(26, 26, 46)`
+- HSL: `hsl(240, 28%, 14%)`
+- Named: `navy`, `coral`, `forestgreen`
+
+### 2. Calculate Relative Luminance
+
+For each color, calculate relative luminance per WCAG 2.1:
+
+```
+For each channel (R, G, B):
+  sRGB = channel / 255
+  linear = sRGB <= 0.04045
+           ? sRGB / 12.92
+           : ((sRGB + 0.055) / 1.055) ^ 2.4
+
+L = 0.2126 * R_linear + 0.7152 * G_linear + 0.0722 * B_linear
+```
+
+### 3. Calculate Contrast Ratios
+
+For every foreground/background pair:
+
+```
+ratio = (max(L1, L2) + 0.05) / (min(L1, L2) + 0.05)
+```
+
+### 4. Evaluate Against Standards
+
+| Standard | Normal Text (< 18pt) | Large Text (>= 18pt or 14pt bold) | UI Components |
+|----------|---------------------|-----------------------------------|---------------|
+| A | No minimum | No minimum | No minimum |
+| AA | 4.5:1 | 3:1 | 3:1 |
+| AAA | 7:1 | 4.5:1 | 4.5:1 |
+
+### 5. Generate Contrast Matrix
+
+For N colors, generate an N x N matrix:
+
+```
+Contrast Matrix (AA Standard)
+
+           #1a1a2e  #16213e  #0f3460  #e94560  #ffffff
+#1a1a2e      —      1.2:1   1.8:1    5.4:1    14.2:1
+                     FAIL    FAIL     PASS     PASS
+#16213e    1.2:1      —      1.5:1    4.5:1    11.8:1
+           FAIL               FAIL    PASS     PASS
+#0f3460    1.8:1    1.5:1      —      3.0:1     7.9:1
+           FAIL     FAIL              FAIL     PASS
+#e94560    5.4:1    4.5:1    3.0:1      —       2.6:1
+           PASS     PASS     FAIL              FAIL
+#ffffff   14.2:1   11.8:1    7.9:1    2.6:1      —
+           PASS     PASS     PASS     FAIL
+```
+
+### 6. Color Vision Deficiency Check
+
+Simulate how the palette appears under common color vision deficiencies:
+
+| Type | Prevalence | Affected Colors |
+|------|-----------|----------------|
+| Protanopia (no red) | ~1% males | Red-green confusion |
+| Deuteranopia (no green) | ~1% males | Red-green confusion |
+| Tritanopia (no blue) | ~0.003% | Blue-yellow confusion |
+| Achromatopsia (no color) | ~0.003% | All hues lost |
+
+Check that colors remain distinguishable under each simulation. Flag pairs that become indistinguishable.
+
+### 7. Remediation Suggestions
+
+When `--fix` is specified, for each failing pair suggest adjustments:
+
+- Darken the darker color or lighten the lighter color
+- Adjust saturation to increase perceived contrast
+- Suggest the minimum lightness shift needed to pass
+- Provide the adjusted color value
+
+```
+Failing pair: #0f3460 on #e94560 (3.0:1, needs 4.5:1)
+
+Suggestions:
+  Option A: Darken background → #0a2340 (ratio: 4.6:1) PASS
+  Option B: Lighten foreground → #ff6b7f (ratio: 4.5:1) PASS
+  Option C: Use white text instead → #ffffff on #e94560 (2.6:1) FAIL
+            Use white on darkened → #ffffff on #c93050 (4.8:1) PASS
+```
+
+## Output Format
+
+### Summary View (default)
+
+```
+Accessibility Report — AA Standard
+
+Palette: #1a1a2e, #16213e, #0f3460, #e94560, #ffffff
+
+Overall: 6/10 pairs pass AA (60%)
+
+PASSING (6):
+  #1a1a2e on #e94560  — 5.4:1  (AA normal text)
+  #1a1a2e on #ffffff  — 14.2:1 (AAA normal + large)
+  #16213e on #e94560  — 4.5:1  (AA normal text, borderline)
+  #16213e on #ffffff  — 11.8:1 (AAA normal + large)
+  #0f3460 on #ffffff  — 7.9:1  (AAA normal + large)
+  #e94560 on #1a1a2e  — 5.4:1  (AA normal text)
+
+FAILING (4):
+  #1a1a2e on #16213e  — 1.2:1  (needs 4.5:1)
+  #1a1a2e on #0f3460  — 1.8:1  (needs 4.5:1)
+  #16213e on #0f3460  — 1.5:1  (needs 4.5:1)
+  #e94560 on #ffffff  — 2.6:1  (needs 4.5:1)
+
+Recommendations:
+  - Avoid using dark colors on each other for text
+  - #e94560 needs a darker variant for use on white backgrounds
+  - Consider adding a dark text color (#1a1a2e) for light backgrounds
+```
+
+### Pair Check View
+
+```
+Contrast Check
+
+Foreground: #e94560 (Coral Red)
+Background: #1a1a2e (Dark Navy)
+
+Contrast Ratio: 5.4:1
+
+AA Normal Text (4.5:1):  PASS
+AA Large Text  (3.0:1):  PASS
+AAA Normal Text (7.0:1): FAIL (need 7.0:1)
+AAA Large Text (4.5:1):  PASS
+```
+
+## Best Practices
+
+1. **Test text on backgrounds, not just swatches** — A palette can look cohesive but fail for readability
+2. **Check both directions** — Light text on dark AND dark text on light
+3. **Include white and near-black** — Most palettes need a light and dark neutral for text
+4. **Don't rely on color alone** — Use icons, patterns, or labels alongside color for meaning
+5. **Test at actual sizes** — Large text thresholds are different from normal text
+6. **Consider dark mode** — Recalculate for dark mode backgrounds