chore(#771): convert agent color: hex/magenta values to documented named colors (#823)

* chore(#771): convert agent color: hex/magenta values to documented named colors Claude Code's sub-agent `color:` field documents only 8 named colors (red, blue, green, yellow, purple, orange, pink, cyan). Twelve agent files used hex values and two used the undocumented `magenta`; convert each to the nearest documented named color so the intended per-agent TUI color differentiation is spec-compliant. - agents/*.md: 14 color values hex/magenta -> nearest named color - scripts/research-profiles.cjs: update the 3 generated research-agent profiles (source of truth) so gen-research-agents stays in sync - docs/AGENTS.md: update documented colors; add missing Color rows for gsd-nyquist-auditor, gsd-project-researcher, gsd-phase-researcher - tests/agent-frontmatter.test.cjs: add regression guard asserting every agent color: is in the documented named-color set Closes #771 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#771): add changeset Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-07 18:50:50 -04:00
parent 1373f9bfb4
commit 3aed02822d
18 changed files with 61 additions and 30 deletions
--- a/.changeset/771-agent-named-colors.md
+++ b/.changeset/771-agent-named-colors.md
@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 823
+---
+Agent `color:` frontmatter now uses Claude Code's documented named colors (`red`/`blue`/`green`/`yellow`/`purple`/`orange`/`pink`/`cyan`) instead of hex values or the undocumented `magenta`, so the intended per-agent TUI color differentiation renders reliably across the Claude Code runtime. Display-only metadata; no behavior change. (#771)
--- a/agents/gsd-ai-researcher.md
+++ b/agents/gsd-ai-researcher.md
@@ -2,7 +2,7 @@
 name: gsd-ai-researcher
 description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
-color: "#34D399"
+color: green
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-code-fixer.md
+++ b/agents/gsd-code-fixer.md
@@ -2,7 +2,7 @@
 name: gsd-code-fixer
 description: Applies fixes to code review findings from REVIEW.md. Reads source files, applies intelligent fixes, and commits each fix atomically. Spawned by /gsd:code-review --fix.
 tools: Read, Edit, Write, Bash, Grep, Glob
-color: "#10B981"
+color: green
 # hooks:
 #   - before_write
 ---
--- a/agents/gsd-code-reviewer.md
+++ b/agents/gsd-code-reviewer.md
@@ -2,7 +2,7 @@
 name: gsd-code-reviewer
 description: Reviews source files for bugs, security issues, and code quality problems. Produces structured REVIEW.md with severity-classified findings. Spawned by /gsd:code-review.
 tools: Read, Write, Bash, Grep, Glob
-color: "#F59E0B"
+color: orange
 # hooks:
 #   - before_write
 ---
--- a/agents/gsd-domain-researcher.md
+++ b/agents/gsd-domain-researcher.md
@@ -2,7 +2,7 @@
 name: gsd-domain-researcher
 description: Researches the business domain and real-world application context of the AI system being built. Surfaces domain expert evaluation criteria, industry-specific failure modes, regulatory context, and what "good" looks like for practitioners in this field — before the eval-planner turns it into measurable rubrics. Spawned by /gsd:ai-integration-phase orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
-color: "#A78BFA"
+color: purple
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-eval-auditor.md
+++ b/agents/gsd-eval-auditor.md
@@ -2,7 +2,7 @@
 name: gsd-eval-auditor
 description: Retroactive audit of an implemented AI phase's evaluation coverage. Checks implementation against the AI-SPEC.md evaluation plan. Scores each eval dimension as COVERED/PARTIAL/MISSING. Produces a scored EVAL-REVIEW.md with findings, gaps, and remediation guidance. Spawned by /gsd:eval-review orchestrator.
 tools: Read, Write, Bash, Grep, Glob
-color: "#EF4444"
+color: red
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-eval-planner.md
+++ b/agents/gsd-eval-planner.md
@@ -2,7 +2,7 @@
 name: gsd-eval-planner
 description: Designs a structured evaluation strategy for an AI phase. Identifies critical failure modes, selects eval dimensions with rubrics, recommends tooling, and specifies the reference dataset. Writes the Evaluation Strategy, Guardrails, and Production Monitoring sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
-color: "#F59E0B"
+color: orange
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-framework-selector.md
+++ b/agents/gsd-framework-selector.md
@@ -2,7 +2,7 @@
 name: gsd-framework-selector
 description: Presents an interactive decision matrix to surface the right AI/LLM framework for the user's specific use case. Produces a scored recommendation with rationale. Spawned by /gsd:ai-integration-phase and /gsd-select-framework orchestrators.
 tools: Read, Bash, Grep, Glob, WebSearch, AskUserQuestion
-color: "#38BDF8"
+color: cyan
 ---

 <role>
--- a/agents/gsd-nyquist-auditor.md
+++ b/agents/gsd-nyquist-auditor.md
@@ -8,7 +8,7 @@ tools:
  - Bash
  - Glob
  - Grep
-color: "#8B5CF6"
+color: purple
 ---

 <role>
--- a/agents/gsd-pattern-mapper.md
+++ b/agents/gsd-pattern-mapper.md
@@ -2,7 +2,7 @@
 name: gsd-pattern-mapper
 description: Analyzes codebase for existing patterns and produces PATTERNS.md mapping new files to closest analogs. Read-only codebase analysis spawned by /gsd:plan-phase orchestrator before planning.
 tools: Read, Bash, Glob, Grep, Write
-color: magenta
+color: purple
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-security-auditor.md
+++ b/agents/gsd-security-auditor.md
@@ -8,7 +8,7 @@ tools:
  - Bash
  - Glob
  - Grep
-color: "#EF4444"
+color: red
 ---

 <role>
--- a/agents/gsd-ui-auditor.md
+++ b/agents/gsd-ui-auditor.md
@@ -2,7 +2,7 @@
 name: gsd-ui-auditor
 description: Retroactive 6-pillar visual audit of implemented frontend code. Produces scored UI-REVIEW.md. Spawned by /gsd:ui-review orchestrator.
 tools: Read, Write, Bash, Grep, Glob
-color: "#F472B6"
+color: pink
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-ui-checker.md
+++ b/agents/gsd-ui-checker.md
@@ -2,7 +2,7 @@
 name: gsd-ui-checker
 description: Validates UI-SPEC.md design contracts against 6 quality dimensions. Produces BLOCK/FLAG/PASS verdicts. Spawned by /gsd:ui-phase orchestrator.
 tools: Read, Bash, Glob, Grep
-color: "#22D3EE"
+color: cyan
 ---

 <role>
--- a/agents/gsd-ui-researcher.md
+++ b/agents/gsd-ui-researcher.md
@@ -2,7 +2,7 @@
 name: gsd-ui-researcher
 description: Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
-color: "#E879F9"
+color: purple
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
--- a/agents/gsd-user-profiler.md
+++ b/agents/gsd-user-profiler.md
@@ -2,7 +2,7 @@
 name: gsd-user-profiler
 description: Analyzes extracted session messages across 8 behavioral dimensions to produce a scored developer profile with confidence levels and evidence. Spawned by profile orchestration workflows.
 tools: Read
-color: magenta
+color: purple
 ---

 <role>
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -42,6 +42,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |
 | **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
 | **Model (balanced)** | Sonnet |
+| **Color** | Cyan |
 | **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |

 **Capabilities:**
@@ -61,6 +62,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | **Parallelism** | 4 instances (same focus areas as project researcher) |
 | **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
 | **Model (balanced)** | Sonnet |
+| **Color** | Cyan |
 | **Produces** | `{phase}-RESEARCH.md` |

 **Capabilities:**
@@ -80,7 +82,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | **Parallelism** | Single instance |
 | **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#E879F9` (fuchsia) |
+| **Color** | Purple |
 | **Produces** | `{phase}-UI-SPEC.md` |

 **Capabilities:**
@@ -268,7 +270,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | **Parallelism** | Single instance |
 | **Tools** | Read, Bash, Glob, Grep |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#22D3EE` (cyan) |
+| **Color** | Cyan |
 | **Produces** | BLOCK/FLAG/PASS verdict |

 ---
@@ -306,6 +308,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | **Parallelism** | Single instance |
 | **Tools** | Read, Write, Edit, Bash, Grep, Glob |
 | **Model (balanced)** | Sonnet |
+| **Color** | Purple |
 | **Produces** | Test files, updated `VALIDATION.md` |

 **Key behaviors:**
@@ -325,7 +328,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 | **Parallelism** | Single instance |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#F472B6` (pink) |
+| **Color** | Pink |
 | **Produces** | `{phase}-UI-REVIEW.md` with scores |

 **6 Audit Pillars (scored 1-4):**
@@ -401,7 +404,7 @@ runs its default whole-repo scan.
 | **Parallelism** | Single instance |
 | **Tools** | Read |
 | **Model (balanced)** | Sonnet |
-| **Color** | Magenta |
+| **Color** | Purple |
 | **Produces** | `USER-PROFILE.md`, `CLAUDE.md` profile section |

 **Behavioral Dimensions:**
@@ -467,7 +470,7 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 | **Parallelism** | Single instance |
 | **Tools** | Read, Write, Edit, Bash, Glob, Grep |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#EF4444` (red) |
+| **Color** | Red |
 | **Produces** | `{phase}-SECURITY.md` |

 **Key behaviors:**
@@ -493,7 +496,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance |
 | **Tools** | Read, Bash, Glob, Grep, Write |
 | **Model (balanced)** | Sonnet |
-| **Color** | Magenta |
+| **Color** | Purple |
 | **Produces** | `PATTERNS.md` in the phase directory |

 **Key behaviors:**
@@ -533,7 +536,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Typically single instance per review scope |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#F59E0B` (amber) |
+| **Color** | Orange |
 | **Produces** | `REVIEW.md` in the phase directory |

 **Key behaviors:**
@@ -553,7 +556,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance |
 | **Tools** | Read, Edit, Write, Bash, Grep, Glob |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#10B981` (emerald) |
+| **Color** | Green |
 | **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix |

 **Key behaviors:**
@@ -573,7 +576,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) |
 | **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#34D399` (green) |
+| **Color** | Green |
 | **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) |

 **Key behaviors:**
@@ -592,7 +595,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance |
 | **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#A78BFA` (violet) |
+| **Color** | Purple |
 | **Produces** | Section 1b of `AI-SPEC.md` |

 **Key behaviors:**
@@ -611,7 +614,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance (sequential after domain-researcher) |
 | **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#F59E0B` (amber) |
+| **Color** | Orange |
 | **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) |

 **Required reading:** `gsd-core/references/ai-evals.md` (evaluation framework).
@@ -632,7 +635,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance |
 | **Tools** | Read, Write, Bash, Grep, Glob |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#EF4444` (red) |
+| **Color** | Red |
 | **Produces** | `EVAL-REVIEW.md` with dimension scores, findings, and remediation guidance |

 **Required reading:** `gsd-core/references/ai-evals.md`.
@@ -653,7 +656,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 | **Parallelism** | Single instance (interactive) |
 | **Tools** | Read, Bash, Grep, Glob, WebSearch, AskUserQuestion |
 | **Model (balanced)** | Sonnet |
-| **Color** | `#38BDF8` (sky blue) |
+| **Color** | Cyan |
 | **Produces** | Scored ranked recommendation (structured return to orchestrator) |

 **Required reading:** `gsd-core/references/ai-frameworks.md` (decision matrix).
--- a/scripts/research-profiles.cjs
+++ b/scripts/research-profiles.cjs
@@ -82,7 +82,7 @@ const PROFILES = [
    name: 'gsd-ai-researcher',
    description:
      'Researches a chosen AI framework\'s official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.',
-    color: '"#34D399"',
+    color: 'green',
    tools:
      'Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*',
    requiredIncludes: [
@@ -99,7 +99,7 @@ const PROFILES = [
    name: 'gsd-domain-researcher',
    description:
      'Researches the business domain and real-world application context of the AI system being built. Surfaces domain expert evaluation criteria, industry-specific failure modes, regulatory context, and what "good" looks like for practitioners in this field — before the eval-planner turns it into measurable rubrics. Spawned by /gsd:ai-integration-phase orchestrator.',
-    color: '"#A78BFA"',
+    color: 'purple',
    tools:
      'Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*',
    requiredIncludes: [
@@ -115,7 +115,7 @@ const PROFILES = [
    name: 'gsd-ui-researcher',
    description:
      'Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.',
-    color: '"#E879F9"',
+    color: 'purple',
    tools:
      'Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
    requiredIncludes: [
--- a/tests/agent-frontmatter.test.cjs
+++ b/tests/agent-frontmatter.test.cjs
@@ -232,6 +232,29 @@ describe('AGENT: required frontmatter fields', () => {
  }
 });

+// ─── Color Value Validation ──────────────────────────────────────────────────
+
+const VALID_AGENT_COLORS = new Set(['red', 'blue', 'green', 'yellow', 'purple', 'orange', 'pink', 'cyan']);
+
+describe('COLOR: color frontmatter must be a documented named color', () => {
+  for (const agent of ALL_AGENTS) {
+    test(`${agent} color: is a documented named color`, () => {
+      const content = fs.readFileSync(path.join(AGENTS_DIR, agent + '.md'), 'utf-8');
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      const frontmatter = fmMatch ? fmMatch[1] : '';
+      const colorMatch = frontmatter.match(/^color:\s*(.+)$/m);
+      assert.ok(colorMatch, `${agent} missing color: field in frontmatter`);
+      const rawValue = colorMatch[1].trim();
+      // Strip surrounding quotes (single or double) before validating
+      const colorValue = rawValue.replace(/^["']|["']$/g, '');
+      assert.ok(
+        VALID_AGENT_COLORS.has(colorValue),
+        `${agent} has invalid color: "${colorValue}" — must be one of: ${[...VALID_AGENT_COLORS].join(', ')}`
+      );
+    });
+  }
+});
+
 // ─── CLAUDE.md Compliance ───────────────────────────────────────────────────

 describe('CLAUDEMD: CLAUDE.md compliance enforcement', () => {