ctx-cc 3.4.4 → 4.0.0

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>

package/commands/help.md

@@ -4,18 +4,18 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 3.3 command reference.
+Display the CTX 3.5 command reference.
 
 Output ONLY the reference content below. Do NOT add project-specific analysis.
 </objective>
 
 <reference>
-# CTX 3.3 Command Reference
+# CTX 3.5 Command Reference
 
 **CTX** (Continuous Task eXecution) - Intelligent workflow orchestration for Claude Code.
 
 **Conversational-first.** Just describe what you want - no commands to memorize.
-21 agents. Learning system. Predictive planning. Self-healing. Full system QA.
+21 agents. 5 skills. Deterministic hooks. Agency-grade design. Phase-based lifecycle.
 
 ## Quick Start
 
@@ -25,6 +25,7 @@ Output ONLY the reference content below. Do NOT add project-specific analysis.
 "I want to build a todo app"     → CTX sets up your project
 "Fix the login bug"              → CTX starts debugging
 "Is my app accessible?"          → CTX runs QA
+"Design a landing page"          → CTX launches design workflow
 "What's next?"                   → CTX shows status
 ```
 
@@ -36,7 +37,17 @@ Or use commands directly:
 4. /ctx status         Check progress (read-only)
 ```
 
-## What's New in 3.3
+## What's New in 4.0
+
+- **Native Architecture** - Skills, hooks, agents via Claude Code's extension points
+- **Agency-Grade Design** - Figma MCP, DTCG tokens, pixel-perfect QA, approval gates
+- **Deterministic Hooks** - PreToolUse/PostToolUse/SubagentStop enforcement
+- **Agent Capabilities** - Tool allowlists per agent category (planning/execution/review)
+- **Pipeline Orchestration** - plan→execute→verify via Skills, not external JS
+- **Autonomous Mode** - Process stories with review gates and graceful stop
+- **Plugin Manifest** - Marketplace-ready distribution
+
+## What's in 3.5
 
 - **Learning System** - CTX learns your patterns, decisions, preferences
 - **Predictive Planning** - AI suggests what to build next with ROI scoring
@@ -115,10 +126,24 @@ Or use commands directly:
 | `/ctx debug --status` | Show current session status |
 | `/ctx debug --abort` | Abort current session |
 
+### Design (Agency-Grade Visual Workflow)
+| Command | Purpose |
+|---------|---------|
+| `/ctx design` | Launch design workflow (brand, component, or audit) |
+| `/ctx brand` | Establish brand identity — mood board → 3 options → BRAND_KIT.md |
+| `/ctx visual-qa` | Pixel-perfect visual QA — measurement-driven, not screenshot |
+
+### Machine Learning
+| Command | Purpose |
+|---------|---------|
+| `/ctx experiment` | ML experiment workflow — hypothesize, design, run, analyze, iterate |
+| `/ctx train` | Model training — features, HPO, evaluation, registry |
+| `/ctx ml-status` | ML dashboard — experiments, models, drift alerts |
+
 ### QA (Full System Testing)
 | Command | Purpose |
 |---------|---------|
-| `/ctx qa` | Full system QA - crawl all pages (WCAG 2.1 AA) |
+| `/ctx qa` | Full system QA - crawl all pages (WCAG 2.2 AA) |
 | `/ctx qa --pages` | List discovered pages first |
 | `/ctx qa --section "auth"` | QA specific section only |
 | `/ctx qa --a11y-only` | Accessibility audit only |
@@ -208,7 +233,7 @@ Or use commands directly:
 | balanced | Opus | Sonnet | Haiku | 1x |
 | budget | Sonnet | Sonnet | Haiku | 0.4x |
 
-## 20 Specialized Agents
+## 25 Specialized Agents
 
 | Agent | Purpose |
 |-------|---------|
@@ -232,6 +257,31 @@ Or use commands directly:
 | ctx-auditor | Compliance logging |
 | ctx-learner | Pattern learning |
 | ctx-predictor | Feature prediction |
+| ctx-qa | Full system QA (WCAG 2.2 + visual) |
+| ctx-ml-scientist | Autonomous ML experiments (hypothesis-driven) |
+| ctx-ml-engineer | MLOps pipelines, model registry, drift detection |
+| ctx-ml-analyst | Data analysis, EDA, statistical testing |
+| ctx-ml-reviewer | ML code review, leakage detection, reproducibility |
+
+## 7 Skills (Auto-Discovered)
+
+| Skill | Purpose |
+|-------|---------|
+| ctx-orchestrator | Pipeline execution, lifecycle, autonomous mode |
+| ctx-state | STATE.json management, phase transitions |
+| ctx-review-gate | Two-stage review (spec compliance + code quality) |
+| ctx-design-system | W3C DTCG tokens, Figma sync, theme management |
+| ctx-visual-qa | Pixel-perfect measurement, accessibility audit |
+| ctx-ml-experiment | ML experiment lifecycle, hypothesis tracking |
+| ctx-ml-pipeline | Training pipelines, inference, model registry |
+
+## 3 Hooks (Deterministic)
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| ctx-pre-tool-use.js | PreToolUse | TDD enforcement, capability restrictions |
+| ctx-post-tool-use.js | PostToolUse | Audit logging for file modifications |
+| ctx-subagent-stop.js | SubagentStop | Agent completion tracking in STATE.json |
 
 ## Key Features
 
@@ -304,5 +354,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 3.3 - Learning. Prediction. Self-healing. Voice control.*
+*CTX 3.5 - Learning. Prediction. Self-healing. Voice control.*
 </reference>

package/commands/metrics.md

@@ -4,7 +4,7 @@ description: Metrics dashboard - understand AI productivity impact with stories
 ---
 
 <objective>
-CTX 3.2 Metrics Dashboard - Comprehensive productivity analytics for understanding AI development impact.
+CTX 3.5 Metrics Dashboard - Comprehensive productivity analytics for understanding AI development impact.
 </objective>
 
 <usage>

package/commands/milestone.md

@@ -4,7 +4,7 @@ description: Milestone workflow - list, audit, complete, and start new milestone
 ---
 
 <objective>
-CTX 3.2 Milestone Workflow - Full release management with audit, archive, and git tagging.
+CTX 3.5 Milestone Workflow - Full release management with audit, archive, and git tagging.
 </objective>
 
 <usage>