ctx-cc 3.5.0 → 4.0.0

package/hooks/subagent-stop.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * CTX SubagentStop Hook
+ * Records agent completion in .ctx/STATE.json when a subagent finishes.
+ * Installed to .claude/hooks/ctx-subagent-stop.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const stateFile = path.join(process.cwd(), '.ctx', 'STATE.json');
+
+try {
+  if (!fs.existsSync(stateFile)) process.exit(0);
+
+  const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+  const history = state.agentHistory || [];
+
+  // Mark last incomplete invocation as completed
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (!history[i].completedAt) {
+      history[i].completedAt = new Date().toISOString();
+      break;
+    }
+  }
+
+  state.session = { ...state.session, lastActivity: new Date().toISOString() };
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n');
+} catch {
+  // Non-fatal — don't block on state errors
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "3.5.0",
-  "description": "CTX 3.3 (Continuous Task eXecution) - AI that learns your preferences. Learning system, predictive planning, self-healing deployments (Sentry/LogRocket), voice control for hands-free development.",
+  "version": "4.0.0",
+  "description": "CTX 4.0 — Intelligent workflow orchestration for Claude Code. 21 subagents, 3 skills, deterministic hooks. Phase-based lifecycle with autonomous execution.",
   "keywords": [
     "claude",
     "claude-code",
@@ -29,10 +29,16 @@
     "src/",
     "commands/",
     "agents/",
+    "skills/",
+    "hooks/",
     "references/",
     "templates/",
-    "workflows/"
+    "plugin.json"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "setup": "node bin/ctx.js"
+  },
   "engines": {
     "node": ">=18.0.0"
   },

package/plugin.json

@@ -0,0 +1,45 @@
+{
+  "name": "ctx",
+  "version": "4.0.0",
+  "description": "CTX — Intelligent workflow orchestration for Claude Code. 21 specialized agents, phase-based lifecycle, two-stage review gate, autonomous execution.",
+  "author": "jufjuf",
+  "license": "MIT",
+  "homepage": "https://github.com/jufjuf/CTX",
+  "repository": "https://github.com/jufjuf/CTX",
+  "keywords": [
+    "workflow",
+    "orchestration",
+    "multi-agent",
+    "development",
+    "productivity"
+  ],
+  "components": {
+    "agents": "agents/",
+    "commands": "commands/",
+    "skills": "skills/",
+    "hooks": "hooks/"
+  },
+  "hooks": {
+    "SubagentStop": [
+      {
+        "command": "node .claude/hooks/ctx-subagent-stop.js"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "command": "node .claude/hooks/ctx-pre-tool-use.js"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "command": "node .claude/hooks/ctx-post-tool-use.js"
+      }
+    ]
+  },
+  "settings": {
+    "reviewGate": true,
+    "tddMode": "off",
+    "maxReviewCycles": 3,
+    "maxAutoIterations": 5
+  }
+}

package/skills/ctx-design-system/SKILL.md

@@ -0,0 +1,572 @@
+---
+name: ctx-design-system
+description: |
+  WHEN: Design system creation, design token management, brand kit updates, token export (CSS/SCSS/JS/Tailwind), theme switching, design system audit for unused/missing tokens.
+  WHEN NOT: Individual component design, general coding tasks, non-visual work, functional bug fixes, API work.
+---
+
+# CTX Design System — Token Management & Living Design System
+
+You manage the design system as a living, versioned artifact. Tokens are the single source of truth for all visual decisions. Every color, dimension, duration, and typography value flows from here.
+
+## Token Format: W3C DTCG 2025.10
+
+All tokens follow the W3C Design Token Community Group specification. Every token entry uses:
+
+```json
+{
+  "token-name": {
+    "$type": "color",
+    "$value": "#1a1a2e",
+    "$description": "Purpose of this token in the system",
+    "$extensions": {
+      "ctx-design-system": {
+        "tier": "primitive",
+        "category": "brand",
+        "deprecated": false,
+        "figma-variable-id": "VariableID:123:456"
+      }
+    }
+  }
+}
+```
+
+### Valid $type Values
+
+| Type | $value format | Example |
+|------|--------------|---------|
+| `color` | hex, oklch(), p3() | `"oklch(0.45 0.18 264)"` |
+| `dimension` | px, rem, em | `"16px"` |
+| `duration` | ms, s | `"200ms"` |
+| `fontFamily` | array of strings | `["Inter", "system-ui", "sans-serif"]` |
+| `fontWeight` | number | `500` |
+| `fontSize` | px or rem | `"1rem"` |
+| `lineHeight` | unitless or px | `"1.5"` |
+| `letterSpacing` | em | `"0.02em"` |
+| `shadow` | composite object | see Shadow section |
+| `border` | composite object | see Border section |
+| `typography` | composite object | see Typography section |
+
+### Composite Token Types
+
+**Typography composite:**
+```json
+{
+  "heading-xl": {
+    "$type": "typography",
+    "$value": {
+      "fontFamily": "{font.family.display}",
+      "fontSize": "{font.size.5xl}",
+      "fontWeight": "{font.weight.bold}",
+      "lineHeight": "{font.line-height.tight}",
+      "letterSpacing": "{font.tracking.tight}"
+    }
+  }
+}
+```
+
+**Shadow composite:**
+```json
+{
+  "elevation-md": {
+    "$type": "shadow",
+    "$value": [
+      { "offsetX": "0", "offsetY": "4px", "blur": "6px", "spread": "-1px", "color": "oklch(0 0 0 / 0.10)" },
+      { "offsetX": "0", "offsetY": "2px", "blur": "4px", "spread": "-2px", "color": "oklch(0 0 0 / 0.10)" }
+    ]
+  }
+}
+```
+
+**Border composite:**
+```json
+{
+  "subtle": {
+    "$type": "border",
+    "$value": {
+      "width": "{border.width.1}",
+      "style": "solid",
+      "color": "{color.border.default}"
+    }
+  }
+}
+```
+
+---
+
+## Three-Tier Token Architecture
+
+Tokens flow in one direction: primitive → semantic → component. Never reference a component token from a semantic token. Never reference semantic from primitive.
+
+```
+PRIMITIVE  Raw values, no semantic meaning
+           blue-500, space-4, ms-200, weight-600
+
+    ↓ aliases reference primitives
+
+SEMANTIC   Purposeful names, mode-aware
+           color-text-primary, space-content-gap, duration-transition
+
+    ↓ aliases reference semantic tokens
+
+COMPONENT  Component-scoped tokens
+           button-background, input-border-focus, card-padding
+```
+
+### When to Add a Token
+
+- Add to **primitive** when you need a new raw value not yet in the scale.
+- Add to **semantic** when a primitive is being used for a specific purpose across 2+ components.
+- Add to **component** when a value is unique to a single component and unlikely to be shared.
+
+---
+
+## File Organization
+
+```
+tokens/
+├── primitive.tokens.json    # Raw scale values — no aliases
+├── semantic.tokens.json     # Purpose aliases — references primitives
+├── component.tokens.json    # Component-scoped — references semantic
+└── themes/
+    ├── light.tokens.json    # Light mode overrides (semantic values only)
+    └── dark.tokens.json     # Dark mode overrides (semantic values only)
+```
+
+### tokens/primitive.tokens.json
+
+Complete primitive scale. Groups: `color`, `dimension`, `font`, `duration`, `easing`.
+
+```json
+{
+  "$schema": "https://design-tokens.org/schema.json",
+  "color": {
+    "gray": {
+      "$type": "color",
+      "50":  { "$value": "oklch(0.985 0.002 247)", "$description": "Near white" },
+      "100": { "$value": "oklch(0.965 0.004 247)" },
+      "200": { "$value": "oklch(0.922 0.008 247)" },
+      "300": { "$value": "oklch(0.865 0.014 247)" },
+      "400": { "$value": "oklch(0.780 0.022 247)" },
+      "500": { "$value": "oklch(0.680 0.028 247)" },
+      "600": { "$value": "oklch(0.560 0.030 247)" },
+      "700": { "$value": "oklch(0.440 0.028 247)" },
+      "800": { "$value": "oklch(0.320 0.022 247)" },
+      "900": { "$value": "oklch(0.200 0.014 247)" },
+      "950": { "$value": "oklch(0.130 0.010 247)", "$description": "Near black" }
+    },
+    "brand": {
+      "$type": "color",
+      "50":  { "$value": "oklch(0.970 0.025 264)" },
+      "500": { "$value": "oklch(0.520 0.180 264)", "$description": "Primary brand hue" },
+      "600": { "$value": "oklch(0.450 0.185 264)" },
+      "700": { "$value": "oklch(0.380 0.175 264)" }
+    }
+  },
+  "dimension": {
+    "space": {
+      "$type": "dimension",
+      "0":  { "$value": "0px" },
+      "1":  { "$value": "4px" },
+      "2":  { "$value": "8px" },
+      "3":  { "$value": "12px" },
+      "4":  { "$value": "16px" },
+      "5":  { "$value": "20px" },
+      "6":  { "$value": "24px" },
+      "8":  { "$value": "32px" },
+      "10": { "$value": "40px" },
+      "12": { "$value": "48px" },
+      "16": { "$value": "64px" },
+      "20": { "$value": "80px" },
+      "24": { "$value": "96px" }
+    },
+    "radius": {
+      "$type": "dimension",
+      "none": { "$value": "0px" },
+      "sm":   { "$value": "4px" },
+      "md":   { "$value": "8px" },
+      "lg":   { "$value": "12px" },
+      "xl":   { "$value": "16px" },
+      "full": { "$value": "9999px" }
+    }
+  },
+  "font": {
+    "size": {
+      "$type": "fontSize",
+      "xs":   { "$value": "0.75rem" },
+      "sm":   { "$value": "0.875rem" },
+      "base": { "$value": "1rem" },
+      "lg":   { "$value": "1.125rem" },
+      "xl":   { "$value": "1.25rem" },
+      "2xl":  { "$value": "1.5rem" },
+      "3xl":  { "$value": "1.875rem" },
+      "4xl":  { "$value": "2.25rem" },
+      "5xl":  { "$value": "3rem" }
+    },
+    "weight": {
+      "$type": "fontWeight",
+      "regular": { "$value": 400 },
+      "medium":  { "$value": 500 },
+      "semibold":{ "$value": 600 },
+      "bold":    { "$value": 700 }
+    },
+    "family": {
+      "sans":    { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] },
+      "display": { "$type": "fontFamily", "$value": ["Cal Sans", "Inter", "sans-serif"] },
+      "mono":    { "$type": "fontFamily", "$value": ["JetBrains Mono", "Menlo", "monospace"] }
+    }
+  },
+  "duration": {
+    "$type": "duration",
+    "instant": { "$value": "0ms" },
+    "fast":    { "$value": "100ms" },
+    "normal":  { "$value": "200ms" },
+    "slow":    { "$value": "300ms" },
+    "slower":  { "$value": "500ms" }
+  }
+}
+```
+
+### tokens/semantic.tokens.json
+
+Semantic tokens reference primitives using `{path.to.token}` syntax. Values are objects with `light` and `dark` keys when mode-aware.
+
+```json
+{
+  "$schema": "https://design-tokens.org/schema.json",
+  "color": {
+    "background": {
+      "page":    { "$type": "color", "$value": { "light": "{color.gray.50}",  "dark": "{color.gray.950}" }, "$description": "Root page background" },
+      "surface": { "$type": "color", "$value": { "light": "{color.gray.100}", "dark": "{color.gray.900}" }, "$description": "Card, panel surfaces" },
+      "overlay": { "$type": "color", "$value": { "light": "{color.gray.200}", "dark": "{color.gray.800}" }, "$description": "Overlay, popover background" }
+    },
+    "text": {
+      "primary":   { "$type": "color", "$value": { "light": "{color.gray.900}", "dark": "{color.gray.50}"  } },
+      "secondary":  { "$type": "color", "$value": { "light": "{color.gray.600}", "dark": "{color.gray.400}" } },
+      "disabled":  { "$type": "color", "$value": { "light": "{color.gray.400}", "dark": "{color.gray.600}" } },
+      "on-accent": { "$type": "color", "$value": { "light": "#ffffff",          "dark": "#ffffff"          }, "$description": "Text on accent backgrounds" }
+    },
+    "border": {
+      "default": { "$type": "color", "$value": { "light": "{color.gray.200}", "dark": "{color.gray.700}" } },
+      "strong":  { "$type": "color", "$value": { "light": "{color.gray.400}", "dark": "{color.gray.500}" } }
+    },
+    "interactive": {
+      "default": { "$type": "color", "$value": { "light": "{color.brand.500}", "dark": "{color.brand.600}" }, "$description": "Primary interactive (buttons, links)" },
+      "hover":   { "$type": "color", "$value": { "light": "{color.brand.600}", "dark": "{color.brand.500}" } },
+      "focus":   { "$type": "color", "$value": { "light": "{color.brand.500}", "dark": "{color.brand.500}" }, "$description": "Focus ring color — must achieve 3:1 against background" }
+    }
+  },
+  "space": {
+    "component-gap":  { "$type": "dimension", "$value": "{dimension.space.4}", "$description": "Gap between components within a section" },
+    "section-gap":    { "$type": "dimension", "$value": "{dimension.space.12}", "$description": "Gap between sections" },
+    "content-inset":  { "$type": "dimension", "$value": "{dimension.space.6}", "$description": "Inner padding for cards and panels" }
+  },
+  "transition": {
+    "interactive": {
+      "$type": "duration",
+      "$value": "{duration.normal}",
+      "$description": "Standard duration for hover/focus transitions"
+    }
+  }
+}
+```
+
+### tokens/component.tokens.json
+
+Component tokens reference semantic tokens. Kept minimal — only add when a component deviates from semantic defaults.
+
+```json
+{
+  "$schema": "https://design-tokens.org/schema.json",
+  "button": {
+    "background":      { "$type": "color",     "$value": "{color.interactive.default}" },
+    "background-hover":{ "$type": "color",     "$value": "{color.interactive.hover}" },
+    "text":            { "$type": "color",     "$value": "{color.text.on-accent}" },
+    "min-height":      { "$type": "dimension", "$value": "44px", "$description": "WCAG 2.2 AA touch target — do not reduce" },
+    "min-width":       { "$type": "dimension", "$value": "44px", "$description": "WCAG 2.2 AA touch target — do not reduce" },
+    "padding-x":       { "$type": "dimension", "$value": "{dimension.space.4}" },
+    "padding-y":       { "$type": "dimension", "$value": "{dimension.space.3}" },
+    "radius":          { "$type": "dimension", "$value": "{dimension.radius.md}" }
+  },
+  "input": {
+    "background":      { "$type": "color",     "$value": "{color.background.surface}" },
+    "border":          { "$type": "color",     "$value": "{color.border.default}" },
+    "border-focus":    { "$type": "color",     "$value": "{color.interactive.focus}" },
+    "text":            { "$type": "color",     "$value": "{color.text.primary}" },
+    "min-height":      { "$type": "dimension", "$value": "44px" },
+    "padding-x":       { "$type": "dimension", "$value": "{dimension.space.3}" },
+    "radius":          { "$type": "dimension", "$value": "{dimension.radius.md}" }
+  },
+  "card": {
+    "background": { "$type": "color",     "$value": "{color.background.surface}" },
+    "border":     { "$type": "color",     "$value": "{color.border.default}" },
+    "padding":    { "$type": "dimension", "$value": "{space.content-inset}" },
+    "radius":     { "$type": "dimension", "$value": "{dimension.radius.lg}" }
+  }
+}
+```
+
+### tokens/themes/dark.tokens.json
+
+Theme files override semantic token values for a given mode. Only include tokens that differ from the default (light) mode.
+
+```json
+{
+  "$schema": "https://design-tokens.org/schema.json",
+  "color": {
+    "background": {
+      "page":    { "$type": "color", "$value": "{color.gray.950}" },
+      "surface": { "$type": "color", "$value": "{color.gray.900}" }
+    },
+    "text": {
+      "primary":   { "$type": "color", "$value": "{color.gray.50}" },
+      "secondary":  { "$type": "color", "$value": "{color.gray.400}" }
+    }
+  }
+}
+```
+
+---
+
+## Color Spaces
+
+Use modern color spaces for superior gamut coverage and perceptual uniformity:
+
+**Oklch** — preferred for scales and accessible colors:
+```
+oklch(lightness chroma hue / alpha)
+oklch(0.520 0.180 264)   /* brand blue */
+```
+- Lightness 0–1 (perceptually uniform, use for contrast calculation)
+- Chroma 0–0.4 (0 = gray, higher = more saturated)
+- Hue 0–360 (same as HSL hue)
+
+**Display P3** — for wide-gamut displays (Safari, Chrome on modern hardware):
+```
+color(display-p3 0.18 0.47 0.89)
+```
+
+**CSS fallback pattern:**
+```css
+/* Always provide sRGB fallback first */
+color: rgb(46 120 227);
+color: oklch(0.52 0.18 264);     /* wider gamut where supported */
+color: color(display-p3 0.18 0.47 0.89);  /* widest gamut */
+```
+
+---
+
+## Export Targets
+
+Run the following exports after any token change. Use Style Dictionary or token-transformer.
+
+### CSS Custom Properties
+
+```css
+/* brand-assets/tokens.css */
+:root {
+  /* Primitive */
+  --color-gray-50: oklch(0.985 0.002 247);
+  --color-brand-500: oklch(0.52 0.18 264);
+  --space-4: 16px;
+  --font-size-base: 1rem;
+
+  /* Semantic — light mode defaults */
+  --color-background-page: var(--color-gray-50);
+  --color-text-primary: var(--color-gray-900);
+  --color-interactive-default: var(--color-brand-500);
+}
+
+[data-theme="dark"] {
+  --color-background-page: var(--color-gray-950);
+  --color-text-primary: var(--color-gray-50);
+}
+```
+
+### SCSS Variables
+
+```scss
+/* brand-assets/tokens.scss */
+$color-gray-50: oklch(0.985 0.002 247);
+$color-brand-500: oklch(0.52 0.18 264);
+$color-background-page: var(--color-background-page);
+$space-4: 16px;
+$button-min-height: 44px;
+```
+
+### JS Constants
+
+```js
+/* brand-assets/tokens.js */
+export const tokens = {
+  color: {
+    gray: { 50: 'oklch(0.985 0.002 247)', 900: 'oklch(0.20 0.014 247)' },
+    brand: { 500: 'oklch(0.52 0.18 264)' },
+    background: { page: 'var(--color-background-page)' },
+    text: { primary: 'var(--color-text-primary)' }
+  },
+  space: { 4: '16px', 6: '24px', 8: '32px' },
+  button: { minHeight: '44px' }
+};
+```
+
+### Tailwind Config
+
+```js
+/* brand-assets/tailwind.config.js */
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand:      { 500: 'oklch(0.52 0.18 264)', 600: 'oklch(0.45 0.185 264)' },
+        background: { page: 'var(--color-background-page)', surface: 'var(--color-background-surface)' },
+        text:       { primary: 'var(--color-text-primary)', secondary: 'var(--color-text-secondary)' },
+        border:     { default: 'var(--color-border-default)' },
+        interactive:{ default: 'var(--color-interactive-default)', hover: 'var(--color-interactive-hover)' }
+      },
+      spacing: {
+        'component-gap': 'var(--space-component-gap)',
+        'content-inset': 'var(--space-content-inset)'
+      },
+      borderRadius: {
+        sm: '4px', md: '8px', lg: '12px', xl: '16px'
+      },
+      fontFamily: {
+        sans:    ['Inter', 'system-ui', 'sans-serif'],
+        display: ['Cal Sans', 'Inter', 'sans-serif'],
+        mono:    ['JetBrains Mono', 'Menlo', 'monospace']
+      }
+    }
+  }
+};
+```
+
+---
+
+## Figma Sync
+
+### Read Tokens from Figma Variables
+
+Pull current Figma variable values and reconcile with token files:
+
+```javascript
+// 1. Fetch all Figma variable collections
+const collections = await mcp__figma__get_variable_defs({ fileKey: figmaFileKey });
+
+// 2. For each collection, extract token values
+collections.forEach(collection => {
+  collection.variables.forEach(variable => {
+    const tokenPath = figmaNameToTokenPath(variable.name);
+    const value = variable.resolvedValuesByMode[collection.defaultModeId];
+    // Map to DTCG format and write to appropriate tier file
+  });
+});
+```
+
+### Write Tokens to Figma
+
+After token changes, push updated values back to Figma variables to keep design and code in sync:
+
+```javascript
+// Update a Figma variable value
+await mcp__figma__update_variable({
+  fileKey: figmaFileKey,
+  variableId: token.$extensions['ctx-design-system']['figma-variable-id'],
+  value: resolveTokenValue(token.$value)
+});
+```
+
+### Figma Name → Token Path Mapping
+
+| Figma Variable Name | Token Path |
+|--------------------|-----------|
+| `Color/Gray/500` | `color.gray.500` |
+| `Semantic/Background/Page` | `color.background.page` |
+| `Component/Button/Min Height` | `button.min-height` |
+
+---
+
+## Design System Audit
+
+Run these checks before any token release.
+
+### 1. Unused Token Detection
+
+```bash
+# Find all CSS custom property references in source
+grep -r "var(--" src/ --include="*.tsx" --include="*.css" | \
+  grep -oP 'var\(--[\w-]+\)' | sort | uniq > .ctx/audit/used-tokens.txt
+
+# Compare against token export
+diff .ctx/audit/used-tokens.txt brand-assets/all-tokens.txt
+```
+
+### 2. Missing Semantic Mappings
+
+Verify every primitive token used in components has a semantic alias:
+- If `color.gray.500` appears in `component.tokens.json`, that is a violation — reference `color.text.secondary` instead.
+
+### 3. Accessibility Violations
+
+Check contrast ratios for all text/background token pairs:
+
+```javascript
+function relativeLuminance(oklch) {
+  // Convert oklch → linear sRGB → luminance
+  const rgb = oklchToLinearRGB(oklch);
+  return 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b;
+}
+
+function contrastRatio(l1, l2) {
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// Required: text 4.5:1, UI components 3:1
+const pairs = [
+  { fg: 'color.text.primary', bg: 'color.background.page', required: 4.5 },
+  { fg: 'color.text.secondary', bg: 'color.background.page', required: 4.5 },
+  { fg: 'color.text.on-accent', bg: 'color.interactive.default', required: 4.5 },
+  { fg: 'color.border.default', bg: 'color.background.page', required: 3.0 }
+];
+```
+
+### 4. Audit Report Format
+
+Write to `.ctx/audit/TOKEN_AUDIT.md`:
+
+```markdown
+# Token Audit — [ISO-8601]
+
+## Summary
+- Total tokens: {n}
+- Unused tokens: {n}
+- Missing semantic mappings: {n}
+- Contrast violations: {n}
+
+## Unused Tokens
+| Token | Last Used | Action |
+|-------|-----------|--------|
+| color.gray.150 | never | Remove |
+
+## Contrast Violations
+| Pair | Ratio | Required | Status |
+|------|-------|----------|--------|
+| text.disabled on bg.page | 2.8:1 | 4.5:1 | FAIL |
+
+## Missing Semantic Mappings
+| Primitive | Used In | Should Become |
+|-----------|---------|---------------|
+| color.gray.500 | button.tokens | color.border.strong |
+```
+
+---
+
+## Operational Rules
+
+- Never delete a token that is currently exported and deployed without a deprecation period.
+- Mark deprecated tokens with `"deprecated": true` in `$extensions` before removal.
+- Increment version in BRAND_KIT.md header on every token release.
+- All token changes must pass the audit before export.
+- Theme files may only reference semantic-tier tokens, never primitives.