ctx-cc 3.5.0 → 4.1.0

package/commands/ctx.md

@@ -120,29 +120,29 @@ Call Task 4 times in a SINGLE message with these parameters:
 
 ```
 Task 1:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: TECH. Analyze technology stack. Write to .ctx/codebase/TECH.md with languages, frameworks, dependencies, build tools, versions."
+  subagent_type: "ctx-tech-mapper"
+  prompt: "Analyze technology stack. Write to .ctx/codebase/TECH.md with languages, frameworks, dependencies, build tools, versions."
   model: "haiku"
   run_in_background: true
   description: "Map tech stack"
 
 Task 2:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: ARCH. Analyze architecture. Write to .ctx/codebase/ARCH.md with patterns, layers, modules, entry points, data flow."
+  subagent_type: "ctx-arch-mapper"
+  prompt: "Analyze architecture. Write to .ctx/codebase/ARCH.md with patterns, layers, modules, entry points, data flow."
   model: "haiku"
   run_in_background: true
   description: "Map architecture"
 
 Task 3:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: QUALITY. Analyze code quality. Write to .ctx/codebase/QUALITY.md with test coverage, linting, type safety, documentation, code smells."
+  subagent_type: "ctx-quality-mapper"
+  prompt: "Analyze code quality. Write to .ctx/codebase/QUALITY.md with test coverage, linting, type safety, documentation, code smells."
   model: "haiku"
   run_in_background: true
   description: "Map quality"
 
 Task 4:
-  subagent_type: "gsd-codebase-mapper"
-  prompt: "Focus area: CONCERNS. Analyze risks and concerns. Write to .ctx/codebase/CONCERNS.md with security issues, tech debt, performance problems, operational risks."
+  subagent_type: "ctx-concerns-mapper"
+  prompt: "Analyze risks and concerns. Write to .ctx/codebase/CONCERNS.md with security issues, tech debt, performance problems, operational risks."
   model: "haiku"
   run_in_background: true
   description: "Map concerns"
@@ -264,7 +264,7 @@ If .ctx/codebase/ doesn't exist, run quick mapping first.
 **Spawn debugger agent:**
 ```
 Task:
-  subagent_type: "debugger"
+  subagent_type: "ctx-debugger"
   prompt: "Investigate this issue: [user's problem]. Use scientific method: reproduce, isolate, fix, verify. The codebase analysis is in .ctx/codebase/. Write debug session to .ctx/debug/SESSION-[timestamp].md"
   description: "Debug issue"
 ```
@@ -283,7 +283,7 @@ Task:
 **Spawn QA agent:**
 ```
 Task:
-  subagent_type: "qa-engineer"
+  subagent_type: "ctx-qa"
   prompt: "Run comprehensive QA validation on this codebase. Test user flows, validate accessibility, check for regressions. Write report to .ctx/qa/REPORT-[timestamp].md"
   description: "QA validation"
 ```

package/commands/design.md

@@ -0,0 +1,304 @@
+---
+name: ctx:design
+description: Launch design workflow — brand identity, component design, design system audit, or visual QA. Detects BRAND_KIT.md and routes accordingly. Spawns ctx-designer agent.
+---
+
+<objective>
+Launch the correct design workflow based on what the project needs and what the user wants to build. Detects existing brand foundation, asks targeted questions, and spawns the ctx-designer agent with full context.
+</objective>
+
+<usage>
+```bash
+/ctx:design                          # Interactive — detects context, asks what to build
+/ctx:design "login page"             # Jump straight to component design with a description
+/ctx:design --brand                  # Force brand establishment workflow
+/ctx:design --audit                  # Design system audit
+/ctx:design --visual-qa              # Visual QA on current implementation
+```
+</usage>
+
+<process>
+
+## Step 1: Detect Brand Foundation
+
+```bash
+# Check for BRAND_KIT.md in project root
+ls BRAND_KIT.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
+
+# Check for token files
+ls tokens/ 2>/dev/null && echo "TOKENS_EXIST" || echo "TOKENS_MISSING"
+```
+
+Build context:
+```
+brand_kit_exists = BRAND_KIT.md found
+tokens_exist     = tokens/ directory found with .tokens.json files
+prd_loaded       = .ctx/PRD.json loaded (if present)
+```
+
+## Step 2: Determine Workflow
+
+### If BRAND_KIT.md does NOT exist
+
+Present this message and route to brand:
+
+```
+No BRAND_KIT.md found in this project.
+
+Design work requires a visual foundation first. Without brand tokens,
+components will be inconsistent and require rework later.
+
+Recommended: Run /ctx:brand to establish your visual foundation first.
+This takes 30-60 minutes and produces:
+  - BRAND_KIT.md (colors, typography, spacing, motion)
+  - tokens/ (W3C DTCG format, three-tier architecture)
+  - brand-assets/ (CSS, SCSS, JS, Tailwind exports)
+
+Alternatively, if you have existing brand assets, answer:
+  1. What are your primary brand colors? (hex or oklch)
+  2. What fonts do you use? (or "system default")
+  3. Do you have a Figma file? (share key if yes)
+
+These answers let me create a minimal BRAND_KIT.md and proceed.
+```
+
+If user provides existing brand assets, create minimal BRAND_KIT.md from their answers and continue.
+
+### If BRAND_KIT.md exists
+
+Present workflow choices:
+
+```
+Brand foundation detected: BRAND_KIT.md [version]
+Tokens: [n] token files found
+
+What type of design work?
+
+  A  Component or page design
+     Design a new UI component or full page using brand tokens.
+     → Mood board, 3 options, prototype, implementation
+
+  B  Design system
+     Add tokens, update brand kit, export for a new platform,
+     audit for unused tokens or accessibility violations.
+     → Token management, export, audit
+
+  C  Visual QA
+     Check that implementation matches design specs.
+     → Measurement-driven parity check, a11y audit, responsive matrix
+
+  D  Visual regression
+     Compare current implementation against last baseline screenshots.
+     → Gemini diff analysis, bounding box flagging
+```
+
+## Step 3: Component/Page Design (Choice A)
+
+Ask:
+```
+Describe what you want to design:
+  - Component name and purpose
+  - Where it appears in the product
+  - Any Figma node ID or link? (optional)
+  - Priority states to handle: (default, hover, focus, disabled, loading, error)
+  - Responsive: mobile-only / tablet+ / all breakpoints?
+```
+
+Load story context if available:
+```bash
+# Read current PRD story for context
+cat .ctx/PRD.json | python3 -c "
+import json, sys
+prd = json.load(sys.stdin)
+current = prd.get('metadata', {}).get('currentStory')
+if current:
+    story = next((s for s in prd['stories'] if s['id'] == current), None)
+    if story:
+        print(json.dumps(story, indent=2))
+"
+```
+
+Spawn ctx-designer with component context:
+
+```
+Agent({
+  subagent_type: "ctx-designer",
+  prompt: "
+    Design story: [title from user input or PRD]
+
+    Story type: design
+    Component: [component name]
+    Description: [user description]
+
+    Brand context:
+    - BRAND_KIT.md exists at project root
+    - Token files: tokens/primitive.tokens.json, tokens/semantic.tokens.json, tokens/component.tokens.json
+
+    States required: [list from user]
+    Responsive: [scope from user]
+    Figma node: [if provided]
+
+    Follow the design-workflow in your instructions:
+    1. Pre-flight check (BRAND_KIT.md exists — confirmed)
+    2. Component research
+    3. Mood board — STOP for approval
+    4. 3 design options (A/B/C) — STOP for selection
+    5. Prototype — STOP for approval
+    6. Implement with brand tokens
+    7. Visual QA (all breakpoints)
+    8. Accessibility audit (WCAG 2.2 AA)
+    9. DESIGN_BRIEF.md documentation
+
+    Acceptance criteria from story (if PRD loaded):
+    [acceptance criteria]
+  ",
+  description: "Design [component name]"
+})
+```
+
+## Step 4: Design System Work (Choice B)
+
+Ask:
+```
+What design system task?
+
+  1  Add new tokens — extend the token scale
+  2  Update brand colors or typography
+  3  Export tokens — CSS / SCSS / JS / Tailwind
+  4  Figma sync — pull from or push to Figma variables
+  5  Audit — find unused tokens, missing semantic mappings, contrast violations
+  6  Theme — add or update light/dark theme overrides
+```
+
+Spawn ctx-designer or use ctx-design-system skill directly based on task.
+
+For audit tasks, run:
+```bash
+# Check for unused tokens
+grep -r "var(--" src/ --include="*.tsx" --include="*.css" --include="*.scss" 2>/dev/null | \
+  grep -oP 'var\(--[\w-]+\)' | sort | uniq
+
+# Find any direct primitive color references bypassing semantic layer
+grep -r "color\.gray\|color\.brand" \
+  tokens/component.tokens.json 2>/dev/null
+```
+
+Report findings before spawning agent with fix instructions.
+
+## Step 5: Visual QA (Choice C)
+
+Collect target information:
+```
+What to QA?
+  - Component name (e.g., "Button", "NavBar", "LoginForm")
+  - Figma node ID (for spec extraction) — optional but recommended
+  - App URL path (e.g., "/components/button" or "/login")
+
+QA scope:
+  - All breakpoints (375px / 768px / 1440px)?
+  - Accessibility audit included?
+  - Gemini design analysis included?
+```
+
+Load app URL:
+```bash
+cat .ctx/.env 2>/dev/null | grep APP_URL
+```
+
+Spawn ctx-designer with visual QA mode:
+
+```
+Agent({
+  subagent_type: "ctx-designer",
+  prompt: "
+    Run visual QA for: [component/page]
+
+    Story type: visual-qa
+    Target URL path: [path]
+    Figma node ID: [if provided]
+    App URL: [from .ctx/.env]
+
+    QA scope:
+    - Breakpoints: 375px, 768px, 1440px
+    - Design parity: measurement-driven precision diff
+    - Accessibility: WCAG 2.2 AA automated checks
+    - Gemini analysis: design quality review
+
+    Follow the ctx-visual-qa skill:
+    1. Extract Figma specs (if node ID provided)
+    2. Measure rendered output at each breakpoint
+    3. Generate precision diff tables
+    4. Run accessibility audit
+    5. Run Gemini design analysis
+    6. Write VISUAL_QA_REPORT.md to .ctx/qa/
+
+    Output:
+    - Pass/fail summary per breakpoint
+    - Specific corrections: file, line, property, old value, new value
+  ",
+  description: "Visual QA: [component/page]"
+})
+```
+
+## Step 6: Visual Regression (Choice D)
+
+```
+Agent({
+  subagent_type: "ctx-designer",
+  prompt: "
+    Run visual regression check.
+
+    Story type: visual-regression
+    Baselines: .ctx/qa/baselines/
+    App URL: [from .ctx/.env]
+    Breakpoints: 375px, 768px, 1440px
+
+    Process:
+    1. Take current screenshots at all breakpoints
+    2. For each: compare against baseline using Gemini analyze_design
+    3. Flag any unintended differences with descriptions
+    4. Save new screenshots to .ctx/qa/visual/
+    5. Write regression report to .ctx/qa/REGRESSION_REPORT.md
+
+    Report format: component | breakpoint | diff description | severity (minor/major)
+  ",
+  description: "Visual regression check"
+})
+```
+
+## Step 7: Update STATE.json
+
+After workflow completes, record design activity:
+
+```bash
+python3 -c "
+import json, sys
+from datetime import datetime
+
+with open('.ctx/STATE.json', 'r') as f:
+    state = json.load(f)
+
+state.setdefault('design', {})
+state['design']['lastActivity'] = datetime.utcnow().isoformat() + 'Z'
+state['design']['workflow'] = '$WORKFLOW_TYPE'
+state['design']['brandKitExists'] = True
+
+with open('.ctx/STATE.json', 'w') as f:
+    json.dump(state, f, indent=2)
+"
+```
+
+</process>
+
+<output>
+```
+[CTX DESIGN]
+
+Brand foundation: [FOUND / NOT FOUND]
+Workflow: [brand / component / design-system / visual-qa / regression]
+
+[Spawning ctx-designer...]
+
+[Agent output follows]
+```
+</output>

package/commands/experiment.md

@@ -0,0 +1,251 @@
+---
+name: ctx:experiment
+description: ML experiment workflow — hypothesize, design, run, analyze, iterate. Routes to the right ML agent based on intent.
+args: intent (optional — what you want to do, e.g. "new", "analyze", "review", "status")
+---
+
+<objective>
+Run the ML experiment lifecycle. Detects intent from your message and routes to the appropriate ML specialist. Keeps all work in .ctx/ml/ with full traceability.
+</objective>
+
+<usage>
+```bash
+/ctx:experiment new "depth=8 improves AUC by 2 points"   # Start new experiment with hypothesis
+/ctx:experiment analyze                                    # Run EDA on current dataset
+/ctx:experiment review                                     # Review latest experiment results
+/ctx:experiment pipeline                                   # Build or improve training pipeline
+/ctx:experiment status                                     # Show current experiment status
+/ctx:experiment                                            # Auto-detect from context
+```
+</usage>
+
+<process>
+
+## Step 1: Parse Intent
+
+Check arguments and message content:
+
+| Trigger | Route |
+|---------|-------|
+| "new", "hypothes", quoted string | New experiment flow |
+| "analyz", "eda", "explore", "data" | EDA flow |
+| "review", "results", "evaluate" | Review flow |
+| "pipeline", "train", "build" | Pipeline flow |
+| "status", "log", "list" | Status flow |
+| No clear signal | Read .ctx/ml/ML-STATUS.md and ask |
+
+## Step 2: Initialize ML Directory
+
+Check whether `.ctx/ml/` exists. If not, bootstrap it:
+
+```bash
+mkdir -p .ctx/ml/experiments
+mkdir -p .ctx/ml/analysis/plots
+mkdir -p .ctx/ml/features/transforms
+mkdir -p .ctx/ml/models/configs
+```
+
+Create `.ctx/ml/EXPERIMENT-LOG.md` with empty table header if it does not exist:
+
+```markdown
+# ML Experiment Log
+
+| ID | Hypothesis | Model | Primary Metric | Result | Status |
+|----|-----------|-------|---------------|--------|--------|
+```
+
+Create `.ctx/ml/ML-STATUS.md` with initialized content if it does not exist:
+
+```markdown
+# ML Project Status
+
+**Updated**: {current date}
+**Active Experiment**: none
+
+## Current Focus
+
+No active experiment. Run `/ctx:experiment new "<hypothesis>"` to start.
+
+## Blocking Issues
+
+- none
+```
+
+## Step 3: Route to Agent
+
+### Route: New Experiment
+
+Determine next experiment ID by reading EXPERIMENT-LOG.md and incrementing max ID.
+
+```
+Agent({
+  subagent_type: "ctx-ml-scientist",
+  prompt: |
+    Create a new ML experiment.
+
+    Experiment ID: EXP-{n}
+    Hypothesis: {user's hypothesis string, or ask if not provided}
+
+    1. Write .ctx/ml/experiments/EXP-{n}/HYPOTHESIS.md
+       - Formalize the hypothesis (one sentence: "We believe X will improve Y by Z because W")
+       - Document rationale and expected outcome
+       - Define null hypothesis
+       - Identify risks
+
+    2. Write .ctx/ml/experiments/EXP-{n}/DESIGN.md
+       - Define baseline and treatment
+       - Specify metrics (primary + guard rails)
+       - Define acceptance criteria
+
+    3. Write .ctx/ml/experiments/EXP-{n}/config.yaml
+       - Reproducible configuration
+       - Seed set to 42
+       - Data paths from existing .ctx/ml/ structure
+
+    4. Append row to .ctx/ml/EXPERIMENT-LOG.md with status "draft"
+
+    5. Update .ctx/ml/ML-STATUS.md to set active experiment = EXP-{n}
+
+    Follow the ctx-ml-experiment skill for all formats.
+})
+```
+
+### Route: EDA / Analyze
+
+```
+Agent({
+  subagent_type: "ctx-ml-analyst",
+  prompt: |
+    Run exploratory data analysis.
+
+    1. Identify the dataset (check .ctx/ml/experiments/ for config.yaml data paths,
+       or ask user if not clear)
+
+    2. Write .ctx/ml/analysis/EDA-{dataset_name}.md with:
+       - Shape, dtypes, missing value counts
+       - Distribution summary for numeric features
+       - Class balance for target variable
+       - Top correlations with target
+       - Potential data quality issues
+       - Recommended features to engineer
+
+    3. Save any plots to .ctx/ml/analysis/plots/
+
+    Follow the ctx-ml-experiment skill for file formats.
+})
+```
+
+### Route: Review Results
+
+Read current active experiment from `.ctx/ml/ML-STATUS.md`.
+
+```
+Agent({
+  subagent_type: "ctx-ml-reviewer",
+  prompt: |
+    Review results for {active_experiment}.
+
+    Files to read:
+    - .ctx/ml/experiments/{active_experiment}/HYPOTHESIS.md
+    - .ctx/ml/experiments/{active_experiment}/DESIGN.md
+    - .ctx/ml/experiments/{active_experiment}/RESULTS.md (if exists)
+    - .ctx/ml/experiments/{active_experiment}/artifacts/metrics.json (if exists)
+
+    Review checklist:
+    - [ ] Primary metric vs target
+    - [ ] Guard rail metrics not violated
+    - [ ] Training stability (check train.log for NaN, divergence)
+    - [ ] Calibration error acceptable
+    - [ ] Inference latency within budget
+    - [ ] Feature drift not detected
+
+    Write verdict to RESULTS.md if not already there.
+    Update EXPERIMENT-LOG.md row status: accepted | rejected | inconclusive.
+    Update ML-STATUS.md with outcome and next experiment recommendation.
+
+    Follow the ctx-ml-experiment skill for all formats.
+})
+```
+
+### Route: Pipeline
+
+```
+Agent({
+  subagent_type: "ctx-ml-engineer",
+  prompt: |
+    Build or improve the ML training pipeline.
+
+    Read:
+    - .ctx/ml/features/feature-registry.yaml
+    - .ctx/ml/models/registry.yaml
+    - Active experiment config if available
+
+    Apply the full pipeline architecture from the ctx-ml-pipeline skill:
+    validation → features → training → HPO → evaluation → registry → inference → monitoring
+
+    Required patterns:
+    - Pandera schema validation at ingestion
+    - Deterministic, serializable feature transforms
+    - Conformal prediction via MAPIE
+    - Prediction envelope with lineage
+    - Circuit breaker on inference
+    - KS-based drift detection
+
+    Save all artifacts per the reproducibility requirements in ctx-ml-pipeline skill.
+})
+```
+
+### Route: Status
+
+Read and display current state without spawning an agent:
+
+1. Read `.ctx/ml/ML-STATUS.md`
+2. Read `.ctx/ml/EXPERIMENT-LOG.md` (last 5 rows)
+3. Read `.ctx/ml/models/registry.yaml` (current versions)
+
+Output format:
+
+```
+[ML Status]
+
+Active Experiment: EXP-{n} — {hypothesis title}
+Status: {draft | running | concluded}
+
+Recent Experiments:
+  EXP-{n}   {status}  {primary metric result}
+  EXP-{n-1} {status}  {primary metric result}
+  EXP-{n-2} {status}  {primary metric result}
+
+Production Models:
+  {model-name}: v{n} (AUC {value})
+
+Current Focus:
+  {from ML-STATUS.md}
+
+Run /ctx:experiment new "<hypothesis>" to start the next experiment.
+```
+
+## Step 4: Report Outcome
+
+After agent completes, report:
+
+```
+[Experiment] EXP-{n} — {phase completed}
+
+Files written:
+  .ctx/ml/experiments/EXP-{n}/{file1}
+  .ctx/ml/experiments/EXP-{n}/{file2}
+
+Next action:
+  {what to do next — e.g. "run training", "review results", "promote model"}
+```
+
+</process>
+
+<guardrails>
+- Never run experiments without HYPOTHESIS.md and DESIGN.md existing first.
+- Never update model registry from this command — use /ctx:train for that.
+- If active experiment is running, warn before creating a new one.
+- Status route never spawns agents — it is read-only.
+- All experiment IDs must be sequential and unique — never reuse.
+</guardrails>