Skip to content

ambtaylor/cue

Repository files navigation

Cue — AI Operating System for Cursor

A portable control-plane for Cursor: specialized agents, enforced engineering gates, shared standards, and hub-resident project state (docs/projects/) so app repos stay thin. Languages: React (default), Python, Angular, plus Cue for hub/meta work and DaC for diagrams-as-code.

Canonical path rules: docs/_ai_system/standards/control-plane-paths.md


Recent Changes

Date Change Scope
2026-04-13 MCP hard-stop policy: sequentialthinking failures now abort with a visible error instead of silently falling back to inline reasoning. Supervisor runs a pre-dispatch health probe before spawning engineering subagents. .cursorrules, cue-supervisor.mdc, cue-engineering.mdc
2026-04-13 MCP config fix: Resolved spawn npx ENOENT and env: node: No such file or directory for NVM-managed Node by using absolute paths and explicit PATH in ~/.cursor/mcp.json. ~/.cursor/mcp.json (user-level)
2026-04-08 React rule gaps and review enforcement symmetry closed. .cursorrules, agents, standards
2026-04-06 Dependency mapper integration with architectural boundary enforcement via depmap-toolkit. Skills, standards, engineering workflow
2026-04-04 Excalidraw DaC agent track with routing, protocol, and style standard. Agents, routing table, standards
2026-04-02 Orchestrator runs in main chat (not as subagent) for reliable Task spawning. .cursorrules, cue-supervisor.mdc, agent-orchestrator.md

Orchestration Flow (How /o Works)

The /o (alias /orchestrate) shortcut runs the full engineering pipeline. The Orchestrator runs in the main chat (not as a subagent) and spawns each phase as a direct Task subagent. This eliminates unreliable nested Task spawning.

You: /o "Create user dashboard"
  |
  v
SUPERVISOR (main chat)
  |  detects /o
  |  resolves envelope (repo, branch, project, language, plan)
  |  loads Orchestrator rules (agent-orchestrator.md)
  |
  v
ORCHESTRATOR (main chat — takes over)
  |
  |  Phase 1: Spec
  |  +---> Task(generalPurpose) --> reads spec-{lang}.md --> creates plan
  |  <--- structured result
  |
  |  FOR EACH MILESTONE M[i]:
  |  |
  |  |  Phase 2: Code(M[i])
  |  |  +---> Task(generalPurpose) --> reads code-{lang}.md --> implements
  |  |  <--- structured result
  |  |
  |  |  Phase 3: Review(M[i])
  |  |  +---> Task(generalPurpose) --> reads review-{lang}.md --> 5-pass audit
  |  |  <--- structured result
  |  |       |
  |  |       +-- REJECT? --> Remediation loop (max 3 cycles) --> re-Review
  |  |
  |  |  Phase 4: QA L1(M[i])  [skip for CUE]
  |  |  +---> Task(generalPurpose) --> reads qa-{lang}.md --> baseline checks
  |  |  <--- structured result
  |  |
  |  |  Phase 5: QA L2(M[i])  [skip for CUE]
  |  |  +---> Task(generalPurpose) --> reads qa-resilience-{lang}.md
  |  |  <--- structured result
  |  |
  |  |  milestone_commit() --> save context to memory
  |  |  milestone_lookup() --> load context for M[i+1]
  |  |
  |  NEXT MILESTONE (carry deferred items forward)
  |
  v
COMPLETE (all milestones done, all deferred items resolved)

Auto-Chain Rules

  • Default: Phases and milestones chain automatically with no user interaction
  • --pause: The only way to stop between phases for user inspection (must be explicitly passed)
  • Circuit breaker: 3 consecutive failures on the same milestone stops the loop
  • Blocking error: Missing dependencies, plan not found, etc. stops the chain

Output Constraints (Per Phase)

Phase May Edit May NOT Edit
Spec Plan files at docs/projects/{PROJECT}/plans/active/ Agent files, standards, profiles, rules, source code
Code Source files, agent files, standards, profiles, rules per plan Plan structure (marking tasks done is OK)
Review Review report; Verification Contract Result column Source files, agent files, standards
QA QA result output only Any files

What Cue Does

Cue gives Cursor a structured engineering process. Instead of a single AI that tries to do everything in one shot, Cue routes your request through specialized agents — each with strict protocols, mandatory reasoning gates, and quality checks — then hands off between phases using structured payloads.

  +-------+     +-----------+     +-------------+     +-----------+
  |  You  | --> | Supervisor| --> | Orchestrator| --> | Subagents |
  +-------+     +-----------+     | (main chat) |     | (Tasks)   |
                   |              +-------------+     +-----------+
                   |                 |                   |
                   |  /o (R/P/A)    +-> Spec --> Code --> Review --> QA
                   |                                      |
                   +-- /spec, /code  --> Direct Agent      |
                   +-- /docs, /jira  --> Ops Agent         |
                   +-- /dac ...      --> DaC Agent         |
                   +-- /test, /sec   --> Test/Sec Agent    |

System Architecture — Hub Control Plane

Cue's hub repo is the control plane for AI-assisted engineering: routing, agent protocols, standards, registry, vault layout, and canonical project artifacts under docs/projects/{project}/.

+----------------------------------------------------------+
|  CUE HUB — Control Plane                                 |
|                                                          |
|  .cursorrules + .cursor/rules/*.mdc   Supervisor & gates |
|  docs/_ai_system/agents/              Protocols          |
|  .cursor/agents/*.md                  Task subagents     |
|  docs/_ai_system/standards/           Standards          |
|  docs/projects/{project}/             Plans, knowledge   |
|  .cursor/skills/ + registry/          Toolkits           |
|  docs/architecture/                   DaC                |
|  lib/cue_vault/ + scripts/            Vault library      |
+----------------------------------------------------------+
          |
          | multi-root workspace
          v
+----------------------------------------------------------+
|  APP REPO — Minimal Spoke                                |
|                                                          |
|  .cue/version.json          --> hub root                 |
|  .cursor/rules/project-profile.mdc                       |
|  docs/_ai_system/standards/project-profile.md            |
|  .cue/vault/ (optional)                                  |
|  .jira/ (optional)                                       |
+----------------------------------------------------------+

Hub vs Spoke

The app repo is not a second home for Cue. Nothing from the hub is copied into the spoke for day-to-day work. Cursor loads the hub folder from the multi-root workspace; agents resolve paths on the hub per control-plane-paths.md.

Spoke (app repo) Hub (this repo)
.cue/version.json → hub root Agents, .cursorrules, .cursor/rules, .cursor/agents, standards, toolkits, registry
.cursor/rules/project-profile.mdc docs/projects/{project}/ — plans, knowledge, rules, profile
docs/_ai_system/standards/project-profile.md Hub-shared knowledge: docs/_ai_system/knowledge/
Optional .cue/vault/, .jira/ Hub vault tiers, hub meta plans

How Cue Leverages Cursor

  Cursor Built-in Feature         How Cue Uses It
  ========================        ==============================
  Plan Mode                  -->  Architectural thinking phase
                                  (output feeds into /spec)

  .cursor/rules/*.mdc        -->  Targeted behavioral rules
                                  (load per glob pattern)

  .cursor/agents/*.md         -->  Orchestrator + phase subagents
                                  (spec, code, review, qa)

  MCP Servers                 -->  sequential-thinking MCP
                                  (mandatory reasoning gate)

  .cursor/skills/             -->  Service toolkits + MCP tools
                                  (External CRM, ML platform, DaC, memory, ...)

Plan Mode Integration

Cursor's built-in Plan Mode is Cue's thinking phase. Switch to Plan Mode for open-ended design discussion. When the design is ready, switch to Agent Mode and run /spec to formalize:

Plan Mode (design exploration) --> /spec (plan) --> /code --> /review --> QA

Glob-Activated Rules (.mdc)

Instead of loading every rule on every request, Cue uses Cursor's .mdc file format with glob-based activation:

Rule File Activates On What It Does
cue-supervisor.mdc Always Thin router — shortcuts, language detection
cue-engineering.mdc Always Scope analysis, decomposition, build gates
cue-vault-intake.mdc Always Credential intake protocol
cue-author.mdc Always Cue system authoring agent
cue-react-coding.mdc **/*.tsx, **/*.jsx React state management, file thresholds
cue-react-performance.mdc **/*.tsx, **/*.jsx Render optimization, memory safety
cue-python-coding.mdc **/*.py Type hints, FastAPI, pytest
cue-python-performance.mdc **/*.py Profiling, async, memory hot paths
cue-angular-coding.mdc **/*.component.ts Angular patterns, change detection
cue-angular-performance.mdc **/*.component.ts OnPush, lazy loading, bundle size
cue-design-principles.mdc **/*.tsx, **/*.css Portal architecture, no modals
cue-ux-behavior.mdc **/*.tsx Empty states, progressive disclosure
cue-module-architecture.mdc **/*.tsx Component registry, design-system layout
cue-no-standalone-scripts.mdc scripts/test_*.py Deprecation guard — use toolkit MCP tools

MCP: Mandatory Structured Reasoning (Hard Stop on Failure)

Cue requires the sequential-thinking MCP server, auto-configured during /install. Every agent activation begins with a structured reasoning call before any output — no complexity threshold, no self-exemption.

Hard Stop Policy: If the MCP server is unavailable, agents must abort and surface the error to the user. Silent fallback to inline reasoning is explicitly forbidden. The Supervisor also runs a pre-dispatch health probe before spawning any /spec, /code, /review, or /sec subagent — catching MCP failures before work begins.


Full Engineering Lifecycle

  Plan Mode           /spec             /code             /review
  (optional)          (Architect)       (Builder)         (Auditor)
  +---------+     +------------+    +------------+    +------------+
  | Design  | --> | Create     | -> | Test-first | -> | 5-pass     |
  | explore |     | plan,      |    | increments,|    | audit:     |
  |         |     | complexity,|    | build      |    | arch, UX,  |
  +---------+     | milestones |    | verify     |    | spec-test, |
                  +------------+    +------------+    | trace, obs |
                                                      +------------+
                                                           |
                                              +------------+------------+
                                              v                         v
                                        +----------+            +------------+
                                        | QA L1    |            | Security   |
                                        | baseline |            | SAST/SCA   |
                                        +----------+            +------------+
                                              |
                                              v
                                        +----------+
                                        | QA L2    |
                                        | resilien.|
                                        +----------+

Context Isolation

Each phase runs in its own Task subagent (or its own chat session in manual mode). Handoffs are thin pointers to the plan — the Verification Contract in the plan is the source of truth for evidence.

App work plans live on the hub: <hubRoot>/docs/projects/{project}/plans/active/

Manual vs Orchestrated

Mode Commands What Happens
Manual /spec -> /code -> /review -> /sec (separate chats) You control each phase transition
Orchestrated /o "Create user dashboard" Auto-chains Spec -> Code -> Review -> QA L1 -> QA L2

Manual mode:

Step Command When
0 Switch to Plan Mode Larger features needing design exploration
1 /spec "Create user dashboard" Starting any new feature
2 /code user-dashboard After Spec completes and plan exists
3 /review user-dashboard After Code completes with build proof
4 /sec user-dashboard Before deploy (security gate)

/o Flags

Flag Effect
--pause Stop between phases for user inspection
--python / --angular / --cue Set language context
--project [name] Target a specific project
--spec / --code / --review Start at a specific phase

Memory Bridge

The Orchestrator uses a SQLite-based memory system (.cue/memory/memory.db) to bridge context across milestone boundaries:

Tool Purpose
milestone_commit Save handoff context after each phase
milestone_lookup Load prior context before milestone N+1
troubleshoot_search Recall past fixes when circuit breaker fires
troubleshoot_commit Record new debugging knowledge

Supervisor Routing

Every request passes through the Supervisor — a thin router that detects intent, resolves language, and delegates to the matched agent.

  User Request
       |
       v
  Shortcut Scan (/spec, /o, /dac, /install, ...)
       |
       v
  Language + Flags (--python, --react, --angular, --cue, --project)
       |
       v
  Project Detection --> docs/projects/{name}/
       |
       v
  MCP Health Probe (for /spec, /code, /review, /sec — hard stop if down)
       |
       v
  Classify Category (UI, Backend, Docs, Ops, DaC)
       |
       +---> Engineering (R/P/A) --> Orchestrator (main chat) --> Task subagents
       +---> DaC track            --> /dac spec|code|review|deploy
       +---> Documentation        --> /docs-user, /docs-dev, /roadmap
       +---> Operations           --> /install, /jira, /check, /feedback
       +---> Cue meta             --> /cue-author, --cue agents
       +---> Testing/Security     --> /test, /sec

Every request echoes a Supervisor Decision block so you can verify routing:

SUPERVISOR DECISION:
Project: example-backend
Branch: feature/api-layer
Language: PYTHON
Category: Backend/Service
Via: Orchestrator
Agent: docs/_ai_system/agents/agent-orchestrator.md
Rules Consulted: .cursorrules, cue-supervisor.mdc, project-profile.md

Task Decomposition

Cue prevents "vibe coding" through complexity-driven rigor. The Spec Agent scores every feature on a 0-6 scale, and that score controls how much structure is enforced.

  Feature Request
       |
       v
  Complexity Score (0-6)
  Files x State x Dependencies x Reversibility x Impact
       |
       +-- 0-1 --> Single Task (streamlined plan, Pass 1 review only)
       |
       +-- 2-3 --> Task List (full plan, dependency ordering, all review passes)
       |
       +-- 4-5 --> Milestones + Increments (bailout plan, milestone-per-chat)
       |
       +-- 6   --> Phased Delivery (scope must be reduced or split)

Milestone and Increment Model (Complexity 3+)

  Feature
  +-- Milestone 1: "User can upload a file" (200-600 lines)
  |   +-- Increment 1.1: Define types            (~30 lines)
  |   +-- Increment 1.2: validateFile()           (~50 lines)
  |   +-- Increment 1.3: useFileUpload hook        (~80 lines)
  |   +-- Increment 1.4: FileDropZone UI           (~100 lines)
  |   +-- Increment 1.5: Wire up + E2E verify
  |
  +-- Milestone 2: "Upload shows progress"
  |   +-- (increments...)
  |
  +-- Milestone 3: "Upload handles errors"
      +-- (increments...)

The Increment Execution Loop

READ input --> WRITE test --> IMPLEMENT (~30-100 lines) --> VERIFY output
--> VERIFY integration --> SIZE CHECK --> LOG completion --> ADVANCE

If the same approach fails twice, the retry circuit breaker fires — the agent must stop and invoke structured reasoning before the third attempt.


Structured Reasoning (MCP)

Every Spec, Code, Review, and Security agent activation must begin with a sequentialthinking MCP call before producing any output.

  You: /code my-feature --python
       |
  Supervisor: loads Orchestrator rules
       |
  Orchestrator: spawns Code subagent via Task
       |
  Code Subagent:
       +---> sequentialthinking MCP (mandatory gate)
       |     decompose, identify risks, produce sequence
       |
       +---> Implement + build verify
       |
       +---> Return structured result to Orchestrator

If the MCP server is unavailable, agents hard stop and surface the error — silent fallback is forbidden. The server is auto-configured during /install.


Agents

Engineering Agents (Polyglot)

Agent Role React Python Angular Cue
Spec Architect agent-spec.md agent-spec-python.md agent-spec-angular.md agent-spec-cue.md
Code Builder agent-coding.md agent-coding-python.md agent-coding-angular.md agent-coding-cue.md
Review Auditor agent-review.md agent-review-python.md agent-review-angular.md agent-review-cue.md
Orchestrator Lifecycle Runs in main chat for all languages
DaC Diagrams agent-spec-dac.md ...

QA Agents (Orchestrator-dispatched)

Agent Layer React Python Angular
QA L1 Global baseline qa-react.md qa-python.md qa-angular.md
QA L2 Resilience qa-resilience-react.md qa-resilience-python.md qa-resilience-angular.md

QA agents are auto-dispatched by the Orchestrator after Review passes. L1 checks global baselines. L2 focuses on operational durability. Both skip for CUE language.

Security, Testing, Documentation, Operations

Agent Shortcut Role
Security /sec SAST/SCA gate
Test /test API explore / pytest probes
User Guide /docs-user Technical writing
Dev Doc /docs-dev Architecture docs
Roadmap /roadmap Changelog and releases
Install /install Project onboarding
Update /update Bump hub pointer
Jira /jira Issue tracking
Feedback /feedback System evolution
Cue Author /cue-author Author agents, rules, registry

Language flags: --python, --react, --angular, --cue, --dac (or auto-detected from keywords and project profile).


Service Toolkits

Cue follows a Toolkit-First pattern for external service integrations. All service interactions go through registered MCP tools that resolve credentials via the vault chain.

  Agent --> check skills.yaml --> Toolkit SKILL.md --> MCP Tool --> Vault Chain
                                                          |
                                                   structured response

Registered Toolkits

Toolkit Service Capabilities
crm-toolkit ExternalCRM Knowledge article CRUD, case query, notes
ml-toolkit ML platform Ingest, retrieve, list, prompts
content-platform-toolkit ContentPlatform Article CRUD, LiQL search, tags, images
prompt-store-toolkit PromptStore Prompt push/pull/list
cue-example-app-feedback example-app Feedback comparison, section diff
cue-example-app-e2e example-app E2E read/create pipeline
dac-toolkit DaC (local) Parse/validate DSL, upsert containers/components
dac-discovery-toolkit DaC (local) Scan services, APIs, dependencies
structurizr-toolkit Structurizr Push workspace, render DSL
browser-verify Local Playwright-style browser verification
memory-toolkit Local (SQLite) Milestone handoffs, troubleshooting recall

Core MCP Tools

Tool Purpose
vault_resolve Credential resolution from vault chain
build_verify Run type checker, linter, tests, dev server
health_check Service connectivity verification
cue_system_check Hub/spoke structure, registry, MCP, vault sanity

Review Agent: 5-Pass Audit

Pass Focus Blocks Merge
1A Code architecture, state management, file size thresholds Yes
1B Structural integrity (milestone state machine, I/O contracts) Yes (complexity 3+)
2 UX behavior scorecard (empty states, help panels, tooltips) Yes
3 Spec-test alignment, cross-task regression Yes
4 Cue trace verification (correct agent, correct rules) Yes
5 Observable verification (browser, logs, behavior) Yes (complexity 2+)

File Size Enforcement

Tier Action
Target Ideal range — no action
WARN Evaluate extraction points
REJECT Must decompose before proceeding
HARD STOP Unconditional reject — must split

React Component (.tsx): Target 150-200, WARN 300, REJECT 500, HARD STOP 800


Global Flags

Flag Effect
--trace Waterfall debug logging with section-level tracking
--pause Stop between phases for user inspection (orchestrated mode only)
--no-standards Skip standards loading
--no-jira Skip auto Jira payload generation
--project [name] Set active project
--python / --react / --angular / --cue / --dac Set language context

Shared Config Vault

Per-project credential management with tiered resolution (project -> hub -> shared), interactive installer, health checks, and .env sync.

Resolution Order (highest wins)

  1. Environment variables (.env / shell)
  2. Project vault (.cue/vault/credentials.yaml)
  3. Hub project vault (cue/.cue/vault/{project}/)
  4. Hub shared vault (cue/.cue/vault/shared/)
  5. Global vault (~/.cue/vault/) — legacy fallback

Python Resolver

from cue_vault import FileVaultResolver

vault = FileVaultResolver()
token = vault.get_credential("external_crm.api_token")
model = vault.resolve_model("Claude Sonnet")
env   = vault.hydrate_env(["external_crm", "cx_playground"])

Interactive Setup

python scripts/init-vault.py --interactive    # Guided service picker
python scripts/init-vault.py --verify         # Health-check services
python scripts/init-vault.py --sync           # Re-sync .env from vault

Quick Start

1. Clone Cue

cd ~/your-workspace
git clone https://github.com/your-org/cue.git

2. Install into Your Project

/install my-project

3. Configure Your Project (on the hub)

Define or edit the project slice under docs/projects/{project}/ (profile, plans, knowledge) per control-plane-paths.md.

4. Set Up Vault (Python Projects)

pip install -e ../cue/lib/cue_vault
python ../cue/scripts/init-vault.py --interactive

5. Start Building

/spec "Create user dashboard"               # React (default)
/spec "Create auth service" --python         # Python
/spec "Create data grid" --angular           # Angular
/o "Full feature implementation"             # Orchestrated pipeline

Adding a New Language

  1. Create 3 agent files: agent-spec-[lang].md, agent-coding-[lang].md, agent-review-[lang].md
  2. Create 2 .mdc rules: cue-[lang]-coding.mdc, cue-[lang]-performance.mdc
  3. Create 1 performance standard: performance-[lang].md
  4. Update .cursorrules with --[lang] flag and detection signals
  5. Register in rule_registry.md
  6. Add to install-cue.ts file copy list

Repository Structure

cue/
+-- .cursorrules                  # Supervisor (polyglot router)
+-- .cursor/
|   +-- agents/                   # Task subagent prompts (spec, code, review, qa, orchestrate)
|   +-- rules/                    # Glob-activated .mdc rules
|   +-- mcp.json
|   +-- mcp-server/               # MCP server (core + toolkit discovery)
|   +-- skills/                   # Toolkits (External CRM, ML platform, DaC, Structurizr, example-app, ...)
+-- .cue/
|   +-- version.json
|   +-- vault/
|   +-- memory/memory.db          # Milestone + troubleshooting SQLite (FTS5 + embeddings)
|   +-- registry/skills.yaml
+-- docs/
|   +-- _ai_system/               # Agents, standards, registry, hub-shared knowledge
|   +-- projects/{project}/       # Control plane: per-project plans, knowledge, rules
|   +-- architecture/             # DaC: workspace.dsl, exports, decisions
|   +-- plans/active|archive/     # Hub-only (meta) plans
+-- lib/cue_vault/
+-- scripts/
+-- registry/services.yaml
+-- tests/

License

MIT

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors