██████╗████████╗██╗  ██╗
  ██╔════╝╚══██╔══╝╚██╗██╔╝
  ██║        ██║    ╚███╔╝
  ██║        ██║    ██╔██╗
  ╚██████╗   ██║   ██╔╝ ██╗
   ╚═════╝   ╚═╝   ╚═╝  ╚═╝

Intelligent workflow orchestration for Claude Code

npx ctx-cc

What is CTX?

CTX transforms Claude Code from a single AI assistant into a full development agency. One installer wires 25 specialized agents, 7 auto-discovered skills, and 3 deterministic enforcement hooks directly into Claude Code's native extension points — no runtime daemon, no wrapper, no proxy.

Three verticals out of the box:

| Vertical | Coverage | |----------|----------| | Software Development | Phase-based lifecycle, autonomous execution, persistent debug, review gates | | Agency-Grade Design | Figma MCP-first workflow, W3C DTCG tokens, pixel-perfect QA, WCAG 2.2 AA | | Machine Learning | Experiment tracking, model registry, conformal prediction, drift detection |

Key value propositions:

• Phase-based lifecycle — init → plan → execute → verify → complete with state tracked in .ctx/STATE.json
• Autonomous execution with review gates — three-stage review: spec compliance, code quality, and optional cross-model adversarial review via OpenAI Codex
• Figma MCP-first design workflow — tokens sync from Figma, visual QA measures pixels numerically
• ML experiment-driven development — hypothesis tracking, XGBoost+MAPIE patterns, KS drift, Digital Twin workflows
• Zero dependencies — installs into Claude Code's native extension points; nothing runs outside Claude

Quick Start

npx ctx-cc              # Install globally (~/.claude)
npx ctx-cc --project    # Install for current project only (.claude/)
npx ctx-cc --force      # Overwrite existing installation

Then inside Claude Code:

/ctx              Smart router — reads state, does the right thing
/ctx:help         Full command reference
/ctx:init         Initialize project (PRD + STATE + config)

Architecture

CTX uses a thin installer / fat Claude Code architecture. The CLI's only job is to copy files into the right directories. All orchestration happens inside Claude Code via the Agent tool.

~/.claude/
├── agents/       25 subagents     (invoked via Agent tool)
├── skills/       7 skills         (auto-discovered by Claude from descriptions)
├── commands/     26 slash commands (/ctx:*)
├── hooks/        3 hook scripts   (deterministic enforcement)
└── settings.json hooks registered

Key decisions:

• The CLI is installer-only. It does not run, proxy, or wrap Claude Code.
• Agents are Markdown files with native frontmatter (model, maxTurns, description). Claude reads these directly.
• Skills are auto-invoked by Claude Code when task descriptions match the skill's WHEN: triggers — no commands needed.
• Hooks are separate .js scripts registered in settings.json. They run deterministically on every tool call.
• plugin.json enables marketplace distribution.

Agents (25)

Software Development (21)

Planning

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-planner | opus | 25 | Atomic plans (2–3 tasks), maps tasks to acceptance criteria | | ctx-researcher | opus | 25 | ArguSeek web research + semantic code search before planning | | ctx-criteria-suggester | sonnet | 25 | Auto-generates acceptance criteria before implementation | | ctx-parallelizer | haiku | 15 | Identifies tasks that can run concurrently, saves total time | | ctx-predictor | haiku | 15 | Analyzes patterns and suggests next features |

Execution

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-executor | sonnet | 50 | Implements tasks with git-native commits per completed task | | ctx-debugger | sonnet | 75 | Persistent debug loop: observe → hypothesize → test → verify |

Review

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-reviewer | sonnet | 25 | Pre-commit review: type errors, imports, security, empty catches | | ctx-auditor | haiku | 15 | Background audit trail and compliance traceability | | ctx-verifier | haiku | 15 | Three-level verification: exists, substantive, wired |

Mapping

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-mapper | haiku | 15 | Token-optimized repository map (REPO-MAP.md) | | ctx-arch-mapper | haiku | 15 | Architecture patterns, data flow, module structure | | ctx-tech-mapper | haiku | 15 | Languages, frameworks, dependencies | | ctx-quality-mapper | haiku | 15 | Test coverage, lint status, type safety | | ctx-concerns-mapper | haiku | 15 | Security vulnerabilities, tech debt, performance risks |

Knowledge & Coordination

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-discusser | sonnet | 25 | Captures implementation decisions before planning begins | | ctx-learner | haiku | 15 | Observes patterns and decisions, builds project memory | | ctx-handoff | haiku | 15 | Creates HANDOFF.md at context thresholds, zero info loss | | ctx-team-coordinator | haiku | 15 | File locks, parallel work coordination, prevents conflicts |

Design & QA

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-designer | sonnet | 50 | Brand establishment, component design, Figma MCP integration | | ctx-qa | sonnet | 50 | Full system QA: crawls every page, clicks every button |

Machine Learning (4)

| Agent | Model | maxTurns | Purpose | |-------|-------|----------|---------| | ctx-ml-scientist | opus | 75 | Designs experiments, selects models, autonomous hypothesis loop | | ctx-ml-engineer | sonnet | 50 | MLOps pipelines, inference envelope, model registry | | ctx-ml-analyst | sonnet | 50 | EDA, dataset quality scoring, feature analysis | | ctx-ml-reviewer | sonnet | 25 | ML code review: correctness, leakage, statistical validity |

Skills (7)

Skills are auto-discovered. Claude Code reads each skill's WHEN: description and invokes it automatically when the task matches — no slash command needed.

Core

| Skill | Auto-invoked when... | Purpose | |-------|----------------------|---------| | ctx-orchestrator | User asks for pipeline, "ctx next", "ctx auto", or autonomous story execution | Runs the full init → plan → execute → verify → complete lifecycle via the Agent tool | | ctx-state | Any CTX operation needs to read/write .ctx/STATE.json or track phase transitions | Manages persistent state, phase transitions, agent history, and task completion log | | ctx-review-gate | Code implemented, story ready to close | Three-stage review: spec compliance → code quality → optional Codex cross-model adversarial review; blocks on failures, soft-skips on Codex infrastructure issues |

Design

| Skill | Auto-invoked when... | Purpose | |-------|----------------------|---------| | ctx-design-system | Design system creation, token management, brand kit updates, token export | Manages W3C DTCG 2025.10 tokens as single source of truth; exports to CSS/SCSS/JS/Tailwind | | ctx-visual-qa | Visual QA, design parity, pixel-perfect verification, responsive testing, WCAG 2.2 audit | Numerical measurement-driven QA — every delta is a number, every fix is a specific CSS property |

Machine Learning

| Skill | Auto-invoked when... | Purpose | |-------|----------------------|---------| | ctx-ml-experiment | User wants to run ML experiments, track hypotheses, compare models | Hypothesis tracking, model registry, experiment lifecycle | | ctx-ml-pipeline | Production ML deployment, inference, drift monitoring | Inference envelope, circuit breaker, KS drift detection, retraining triggers |

Commands (26)

Smart

| Command | Purpose | |---------|---------| | /ctx | Smart router — reads STATE.json, does the right thing |

Mapping

| Command | Purpose | |---------|---------| | /ctx:map | Build token-optimized repository map (REPO-MAP.md) | | /ctx:map-codebase | Deep parallel analysis: TECH + ARCH + QUALITY + CONCERNS → SUMMARY |

Discussion

| Command | Purpose | |---------|---------| | /ctx:discuss [story] | Capture implementation decisions before planning; locks them in CONTEXT.md |

Configuration

| Command | Purpose | |---------|---------| | /ctx:profile [name] | Switch model profile: quality, balanced (default), budget |

Inspect

| Command | Purpose | |---------|---------| | /ctx:status | Show current state without triggering any action |

Control

| Command | Purpose | |---------|---------| | /ctx:init | Initialize project: PRD.json + STATE.json + config | | /ctx:plan [goal] | Force research + planning phase | | /ctx:verify | Force three-level verification | | /ctx:quick "task" | Quick task bypass (skips full lifecycle) |

Debug

| Command | Purpose | |---------|---------| | /ctx:debug | Start debugging current issue | | /ctx:debug "issue" | Debug specific problem | | /ctx:debug --resume | Resume last debug session | | /ctx:debug --list | List all debug sessions | | /ctx:debug --status | Show current session status |

Design

| Command | Purpose | |---------|---------| | /ctx:brand | Brand establishment: mood board → 3 options → BRAND_KIT.md | | /ctx:design | Component design: research → 3 options → prototype → implement |

QA

| Command | Purpose | |---------|---------| | /ctx:qa | Full system QA — WCAG 2.1 AA, every page, every interaction | | /ctx:qa --a11y-only | Accessibility audit only | | /ctx:qa --visual-only | Visual regression across mobile/tablet/desktop | | /ctx:qa --resume | Resume interrupted QA session | | /ctx:visual-qa | Measurement-driven design parity check |

ML

| Command | Purpose | |---------|---------| | /ctx:experiment | Start ML experiment loop | | /ctx:train | Trigger training pipeline | | /ctx:ml-status | Show experiment registry and model status |

Session

| Command | Purpose | |---------|---------| | /ctx:pause | Checkpoint state for session resume |

Phase

| Command | Purpose | |---------|---------| | /ctx:phase list | Show all phases and their status | | /ctx:phase add "goal" | Add a new phase | | /ctx:phase next | Complete current phase, advance to next |

Integration

| Command | Purpose | |---------|---------| | /ctx:integrate | Show integration status | | /ctx:integrate linear | Set up Linear sync | | /ctx:integrate jira | Set up Jira sync | | /ctx:integrate github | Set up GitHub Issues sync | | /ctx:integrate --sync | Sync all stories with connected tracker |

Milestone

| Command | Purpose | |---------|---------| | /ctx:milestone | Show current milestone | | /ctx:milestone list | List all milestones | | /ctx:milestone audit | Verify milestone completion | | /ctx:milestone complete | Archive and tag release | | /ctx:milestone new [name] | Start next version | | /ctx:milestone gaps | Generate fix phases for gaps |

Metrics

| Command | Purpose | |---------|---------| | /ctx:metrics | Productivity dashboard | | /ctx:metrics cost | Cost analysis by model/profile | | /ctx:metrics export | Export HTML dashboard |

Learning

| Command | Purpose | |---------|---------| | /ctx:learn | Show what CTX has learned about your project | | /ctx:learn patterns | Show detected code patterns | | /ctx:learn decisions | Show architectural decisions log | | /ctx:predict | Get AI-suggested next features | | /ctx:predict --quick | Quick wins only |

Monitoring

| Command | Purpose | |---------|---------| | /ctx:monitor | Show monitoring status | | /ctx:monitor connect sentry | Connect Sentry error tracking | | /ctx:monitor errors | List recent production errors | | /ctx:monitor auto-fix [id] | Auto-fix error with PR | | /ctx:monitor --watch | Continuous monitoring mode |

Voice

| Command | Purpose | |---------|---------| | /ctx:voice | Start voice input | | /ctx:voice --continuous | Always-listening mode | | /ctx:voice --dictate | Long-form dictation |

Hooks (3)

Hooks are deterministic Node.js scripts registered in settings.json. They run synchronously on every tool call, independent of Claude's reasoning.

| Hook | File | Trigger | Behavior | |------|------|---------|----------| | pre-tool-use | hooks/pre-tool-use.js | Before any tool executes | TDD enforcement + capability restrictions. Exit 2 blocks the tool call. | | post-tool-use | hooks/post-tool-use.js | After any tool executes | Logs file modifications to audit trail in .ctx/audit.log | | subagent-stop | hooks/subagent-stop.js | When a subagent finishes | Records agent completion in .ctx/STATE.json |

Configure hook behavior:

npx ctx-cc config set hooks.tddMode strict    # Block writes without tests
npx ctx-cc config set hooks.tddMode warn      # Warn but allow
npx ctx-cc config set hooks.tddMode off       # Disabled

Design Workflow

CTX implements an agency-grade design process with mandatory approval gates.

Phase 1 — Brand

Research → Mood board → 3 direction options → User picks → BRAND_KIT.md

BRAND_KIT.md becomes the constraint for all subsequent design work. Colors, typography, and spacing flow from tokens only.

Phase 2 — Component Design

Research → 3 options (A/B/C) → User approves direction → Prototype → Implement

Never a single design. Options are always presented before implementation.

Phase 3 — Visual QA Every design change triggers numerical verification:

• Measure rendered values vs design spec (px, rem, hex)
• Report deltas as numbers, not subjective descriptions
• Fixes are specific: change font-size from 14px to 16px

Compliance: WCAG 2.2 AA + EAA 2025. Touch targets, contrast ratios, keyboard navigation, and screen reader labels are all measured.

Key tools: Figma MCP (token sync + component metadata), Gemini design analysis, W3C DTCG 2025.10 token format.

ML Workflow

CTX implements an experiment-driven ML development loop.

Phase 1 — Data Analysis

Load data → EDA → Quality scoring → Feature correlation → Pandera validation schema

Phase 2 — Experiment Loop

Hypothesize → Design experiment → Run → Analyze → Register result → Iterate

All hypotheses and results are tracked in .ctx/ml/experiments/. The model registry stores every trained artifact with metadata.

Phase 3 — Model Evaluation

• Conformal prediction intervals (MAPIE)
• Statistical significance testing
• Calibration curves and reliability diagrams

Phase 4 — Production Pipeline

• Model registry with version pinning
• Inference envelope with latency SLA
• Circuit breaker (auto-disable on error spike)
• KS drift detection with configurable thresholds
• Retraining triggers on drift

Proven patterns: XGBoost + MAPIE conformal prediction, T-learner causal inference, KS drift, Pandera schema validation — from Digital Twin production workflows.

Configuration

npx ctx-cc config list                       # Show all config values
npx ctx-cc config get activeProfile          # Get a specific value
npx ctx-cc config set hooks.tddMode strict   # Set a value

Model profiles:

| Profile | Research | Planning | Execution | Verify | Relative Cost | |---------|----------|----------|-----------|--------|---------------| | quality | opus | opus | opus | sonnet | ~3x | | balanced | opus | opus | sonnet | haiku | 1x (default) | | budget | sonnet | sonnet | sonnet | haiku | ~0.4x |

Switch profiles without reinstalling:

/ctx:profile quality
/ctx:profile balanced
/ctx:profile budget

Phase Lifecycle

init → plan → execute → verify → complete
                ↑          ↓
                ←── (fix failures)

State is persisted in .ctx/STATE.json after every transition. The ctx-state skill manages reads and writes. The ctx-orchestrator skill drives transitions.

| Phase | What happens | |-------|--------------| | init | Research + repo map + PRD validation | | plan | Acceptance criteria + atomic task plan (2–3 tasks) | | execute | Implementation with per-task git commits | | verify | Three-level check: exists → substantive → wired | | complete | Review gate passed, story archived |

If verification fails, state returns to execute automatically. The fix-loop runs until all three verification levels pass.

Plugin Manifest

CTX ships with plugin.json for Claude Code marketplace distribution. Future marketplace installs will use:

/plugin install ctx@my-marketplace

The manifest declares all agents, skills, commands, and hooks so the marketplace can display capabilities, manage versions, and handle updates without reinstalling.

CLI Reference

npx ctx-cc [options]           Install CTX into Claude Code
npx ctx-cc list                List all 25 agents with model/maxTurns
npx ctx-cc skills              Analyze skill descriptions and triggers
npx ctx-cc config list         Show full configuration
npx ctx-cc config get <key>    Get a config value
npx ctx-cc config set <k> <v>  Set a config value
npx ctx-cc --help              Show help

Options:
  --global, -g     Install to ~/.claude (default)
  --project, -p    Install to .claude in current directory
  --force, -f      Overwrite existing installation

Development

git clone https://github.com/jufjuf/CTX.git
cd CTX
npm test    # 154 tests, node:test runner

Project structure:

ctx-cc/
├── agents/          25 agent definitions (.md with frontmatter)
├── skills/          7 skill directories (each contains SKILL.md)
├── commands/        26 slash command definitions (.md)
├── hooks/           3 enforcement hook scripts (.js)
├── src/              5 source modules (.js)
├── test/             9 test files (.test.js)
├── templates/       config.json, PRD.json, state templates
├── bin/ctx.js       CLI entry point (installer only)
├── plugin.json      Marketplace manifest
└── package.json     Zero runtime dependencies

Testing

npm test
# 154 tests, 0 failures, ~1s

Coverage:

| Area | What is tested | |------|----------------| | Agent discovery | Frontmatter parsing, model/maxTurns validation | | State machine | Phase transitions, invalid transition rejection | | Pipelines | Orchestrator flow, review gate stages | | Worktrees | Parallel execution isolation | | Hooks | TDD enforcement, audit logging, subagent tracking | | Capabilities | Restriction rules, exit codes | | Context profiles | Model resolution per profile | | Skills format | SKILL.md structure, description format | | Design compliance | Token format, BRAND_KIT schema | | ML compliance | Experiment schema, pipeline config | | CLI commands | list, skills, config get/set | | Integration | End-to-end install + verify |

License

MIT

GitHub · npm · Issues

CTX 4.0 — 25 agents · 7 skills · 3 hooks · zero dependencies