@alevental/cccp 0.1.0

package/README.md

@@ -0,0 +1,280 @@
+# CCCP
+
+**Claude Code and Cmux Pipeline Reagent** — deterministic YAML-based pipeline orchestration for workflows built around [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [cmux](https://github.com/manaflow-ai/cmux).
+
+## The problem
+
+Complex multi-stage workflows (SDLC pipelines, research pipelines, content pipelines) rely on Claude as a "file-routing state machine" — dispatching agents, reading evaluations, routing on PASS/FAIL. Over long runs, context degrades: Claude forgets iteration counts, skips sub-stages, misreads evaluations, or loses routing logic.
+
+## The solution
+
+CCCP moves the state machine into deterministic TypeScript code. It reads YAML pipeline definitions, dispatches agents via `claude -p` (each with fresh context), parses evaluations with regex, and routes without interpretation. A cmux split-pane dashboard shows live progress. Human approval gates are handled via an MCP server.
+
+- Uses Max subscription — no API keys needed
+- Each agent gets a fresh context window
+- Evaluation routing is regex, not interpretation
+- State persists to disk — resume after crashes
+- Works with any project, any agents, any workflow
+
+## Install
+
+```bash
+git clone <repo-url> && cd cccp
+npm install
+npm link  # makes `cccp` available globally
+```
+
+## Quick start
+
+Scaffold a project:
+
+```bash
+cd my-project
+cccp init
+```
+
+This creates:
+
+```
+cccp.yaml             # project config (agent paths, MCP profiles)
+pipelines/example.yaml # example pipeline
+agents/                # example agent definitions
+```
+
+Preview what the pipeline will do:
+
+```bash
+cccp run -f pipelines/example.yaml -p my-project --dry-run
+```
+
+Run it for real:
+
+```bash
+cccp run -f pipelines/example.yaml -p my-project
+```
+
+## Pipeline YAML
+
+Pipelines are sequences of typed stages:
+
+```yaml
+name: my-pipeline
+description: What this pipeline does.
+
+stages:
+  # Simple agent dispatch
+  - name: research
+    type: agent
+    agent: researcher
+    output: "{artifact_dir}/research.md"
+
+  # Plan-Generate-Evaluate with retry loop
+  - name: design
+    type: pge
+    task: "Design the system architecture."
+    inputs:
+      - "{artifact_dir}/research.md"
+    planner:
+      agent: architect
+      operation: task-planning
+    generator:
+      agent: architect
+      operation: design        # optional sub-operation
+      mcp_profile: base        # optional MCP server profile
+    evaluator:
+      agent: reviewer
+    contract:
+      deliverable: "{artifact_dir}/design.md"
+      guidance: "System must be modular with documented data flow."
+      max_iterations: 3
+    on_fail: stop              # stop | skip | human_gate
+
+  # Human approval gate
+  - name: approval
+    type: human_gate
+    prompt: "Review the design. Approve to proceed."
+    artifacts:
+      - "{artifact_dir}/design.md"
+```
+
+### Stage types
+
+| Type | What it does |
+|------|-------------|
+| `agent` | Dispatch one agent, collect output |
+| `pge` | Dispatch planner -> evaluator writes contract -> dispatch generator -> dispatch evaluator -> parse `### Overall: PASS/FAIL` -> retry generator/evaluator on FAIL up to `max_iterations` |
+| `human_gate` | Block until approved via MCP tool call or state file edit |
+
+### Variables
+
+Built-in variables available in all string fields:
+
+| Variable | Value |
+|----------|-------|
+| `{project}` | Project name from `--project` |
+| `{project_dir}` | Project directory |
+| `{artifact_dir}` | Resolved artifact output directory |
+| `{pipeline_name}` | Pipeline name |
+| `{iteration}` | Current PGE iteration (1-based) |
+
+## Agents
+
+CCCP ships no agents — you bring your own. Agents are markdown files that become the `--system-prompt-file` for `claude -p`.
+
+**Flat file agent** (`agents/implementer.md`):
+```markdown
+---
+name: implementer
+description: Implements code changes.
+---
+
+# Implementer Agent
+
+Your instructions here...
+```
+
+**Directory agent with operations** (`agents/architect/`):
+```
+agents/architect/
+  agent.md              # base instructions (always included)
+  health-assessment.md  # operation: health-assessment
+  plan-authoring.md     # operation: plan-authoring
+```
+
+Reference an operation in the pipeline:
+```yaml
+generator:
+  agent: architect
+  operation: plan-authoring
+```
+
+### Agent search paths
+
+CCCP searches for agents in order (first match wins):
+
+1. `agents/` relative to the pipeline YAML file
+2. `<project>/.claude/agents/`
+3. `<project>/agents/`
+4. Paths listed in `cccp.yaml` → `agent_paths`
+
+## Project config (`cccp.yaml`)
+
+Place at your project root:
+
+```yaml
+agent_paths:
+  - ./agents
+  - ./vendor/shared-agents
+
+mcp_profiles:
+  base:
+    servers:
+      qmd:
+        command: qmd
+        args: [serve, --stdio]
+  design:
+    extends: base
+    servers:
+      figma:
+        command: npx
+        args: [-y, figma-console-mcp]
+
+artifact_dir: docs/projects/{project}/{pipeline_name}
+default_mcp_profile: base
+```
+
+MCP profiles use `extends` for inheritance. Each agent gets only the servers its profile specifies via `--strict-mcp-config`.
+
+## Evaluation format
+
+Evaluator agents must produce files containing this line:
+
+```markdown
+### Overall: PASS
+```
+
+or
+
+```markdown
+### Overall: FAIL
+```
+
+CCCP reads only this line. Everything else in the evaluation (criterion tables, iteration guidance) is for the generator agent on retry.
+
+## CLI reference
+
+```
+cccp run -f <pipeline.yaml> -p <project> [options]
+  --dry-run              Show what would execute without running agents
+  --headless             Auto-approve all human gates
+  -d, --project-dir      Project directory (default: cwd)
+  -a, --artifact-dir     Override artifact output directory
+  -v, --var key=value    Set pipeline variables (repeatable)
+
+cccp resume -p <project> -r <run-id-prefix> [--headless]
+  Resume an interrupted pipeline from the last incomplete stage
+
+cccp dashboard -r <run-id-prefix>
+  Launch the TUI dashboard to monitor a running pipeline
+
+cccp gate-server
+  Start the MCP server for pipeline gate interaction
+
+cccp init [--dir <path>]
+  Scaffold cccp.yaml, example pipeline, and example agents
+```
+
+## Gate interaction
+
+When a pipeline hits a `human_gate` stage, it writes a pending gate to the SQLite state database (`.cccp/cccp.db`) and waits.
+
+**Option 1: MCP server** — Register the gate server in your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cccp-gate": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/cccp/src/cli.ts", "gate-server"]
+    }
+  }
+}
+```
+
+Then from Claude Code: call `pipeline_status` to see what's pending, `pipeline_gate_respond` to approve/reject.
+
+**Option 2: Headless** — `cccp run --headless` auto-approves all gates.
+
+## State & resume
+
+Pipeline state is persisted to a SQLite database at `{projectDir}/.cccp/cccp.db` after every transition (stage start, planner dispatch, contract dispatch, generator dispatch, evaluator dispatch, routing decision). If a run is interrupted:
+
+```bash
+cccp resume -p my-project -r <run-id-prefix>
+```
+
+Completed stages are skipped. PGE stages resume at the correct iteration and sub-step.
+
+## cmux integration
+
+When running inside a [cmux](https://github.com/manaflow-ai/cmux) workspace (`CMUX_WORKSPACE_ID` is set), CCCP automatically:
+
+- Updates the sidebar status pill with current stage
+- Sets the progress bar
+- Sends desktop notifications for gates and pipeline completion
+- Can open the dashboard in a cmux split pane
+
+Without cmux, CCCP falls back to plain terminal output.
+
+## Development
+
+```bash
+npm test           # run all tests (143 tests)
+npm run typecheck  # tsc --noEmit
+npm run test:watch # watch mode
+npm run build      # compile TypeScript to dist/
+```
+
+## License
+
+MIT

package/dist/activity-bus.d.ts

@@ -0,0 +1,9 @@
+import { EventEmitter } from "node:events";
+/**
+ * Module-level singleton event bus for passing agent activity updates
+ * from the runner to the TUI dashboard within the same process.
+ *
+ * The runner publishes: activityBus.emit("activity", agentActivity)
+ * The dashboard subscribes: activityBus.on("activity", handler)
+ */
+export declare const activityBus: EventEmitter<[never]>;

package/dist/activity-bus.js

@@ -0,0 +1,10 @@
+import { EventEmitter } from "node:events";
+/**
+ * Module-level singleton event bus for passing agent activity updates
+ * from the runner to the TUI dashboard within the same process.
+ *
+ * The runner publishes: activityBus.emit("activity", agentActivity)
+ * The dashboard subscribes: activityBus.on("activity", handler)
+ */
+export const activityBus = new EventEmitter();
+//# sourceMappingURL=activity-bus.js.map

package/dist/activity-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-bus.js","sourceRoot":"","sources":["../src/activity-bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,YAAY,EAAE,CAAC"}

package/dist/agent-resolver.d.ts

@@ -0,0 +1,29 @@
+export interface ResolvedAgent {
+    /** Absolute path to the agent's main markdown file. */
+    agentPath: string;
+    /** Absolute path to the operation file (if applicable). */
+    operationPath?: string;
+    /** Whether this is a directory-style agent. */
+    isDirectory: boolean;
+}
+/**
+ * Resolve an agent name to file path(s) by searching configured directories.
+ *
+ * Search order (first match wins):
+ * 1. Each directory in `searchPaths`, in order
+ *
+ * For each search directory, tries:
+ * - `<dir>/<agent>.md` — flat-file agent
+ * - `<dir>/<agent>/agent.md` — directory-style agent
+ *
+ * If an `operation` is specified and the agent is directory-style:
+ * - Also resolves `<dir>/<agent>/<operation>.md`
+ *
+ * If the agent name already ends in `.md` or contains a path separator,
+ * it's treated as a direct path (absolute or relative to projectDir).
+ */
+export declare function resolveAgent(agentName: string, searchPaths: string[], operation?: string, projectDir?: string): Promise<ResolvedAgent>;
+/**
+ * List all available operations for a directory-style agent.
+ */
+export declare function listOperations(agentName: string, searchPaths: string[]): Promise<string[]>;

package/dist/agent-resolver.js

@@ -0,0 +1,122 @@
+import { access, readdir } from "node:fs/promises";
+import { resolve, join, basename, dirname } from "node:path";
+// ---------------------------------------------------------------------------
+// Resolution logic
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an agent name to file path(s) by searching configured directories.
+ *
+ * Search order (first match wins):
+ * 1. Each directory in `searchPaths`, in order
+ *
+ * For each search directory, tries:
+ * - `<dir>/<agent>.md` — flat-file agent
+ * - `<dir>/<agent>/agent.md` — directory-style agent
+ *
+ * If an `operation` is specified and the agent is directory-style:
+ * - Also resolves `<dir>/<agent>/<operation>.md`
+ *
+ * If the agent name already ends in `.md` or contains a path separator,
+ * it's treated as a direct path (absolute or relative to projectDir).
+ */
+export async function resolveAgent(agentName, searchPaths, operation, projectDir) {
+    // Direct path — skip search if agent looks like a path.
+    if (agentName.includes("/") || agentName.endsWith(".md")) {
+        return resolveDirectPath(agentName, operation, projectDir);
+    }
+    // Search configured paths.
+    for (const searchDir of searchPaths) {
+        // Try flat file: <dir>/<agent>.md
+        const flatPath = join(searchDir, `${agentName}.md`);
+        if (await fileExists(flatPath)) {
+            if (operation) {
+                // Flat file agents don't have operations — check if there's a
+                // sibling directory with the operation file.
+                const opPath = join(searchDir, agentName, `${operation}.md`);
+                if (await fileExists(opPath)) {
+                    // There's actually a directory-style agent alongside the flat file.
+                    const dirAgentPath = join(searchDir, agentName, "agent.md");
+                    if (await fileExists(dirAgentPath)) {
+                        return {
+                            agentPath: dirAgentPath,
+                            operationPath: opPath,
+                            isDirectory: true,
+                        };
+                    }
+                }
+                throw new Error(`Agent "${agentName}" is a flat file and does not support operation "${operation}"`);
+            }
+            return { agentPath: flatPath, isDirectory: false };
+        }
+        // Try directory: <dir>/<agent>/agent.md
+        const dirAgentPath = join(searchDir, agentName, "agent.md");
+        if (await fileExists(dirAgentPath)) {
+            let operationPath;
+            if (operation) {
+                operationPath = join(searchDir, agentName, `${operation}.md`);
+                if (!(await fileExists(operationPath))) {
+                    throw new Error(`Operation "${operation}" not found for agent "${agentName}" at: ${operationPath}`);
+                }
+            }
+            return {
+                agentPath: dirAgentPath,
+                operationPath,
+                isDirectory: true,
+            };
+        }
+    }
+    const searched = searchPaths.map((p) => `  - ${p}`).join("\n");
+    throw new Error(`Agent "${agentName}" not found. Searched:\n${searched}`);
+}
+/**
+ * List all available operations for a directory-style agent.
+ */
+export async function listOperations(agentName, searchPaths) {
+    for (const searchDir of searchPaths) {
+        const agentDir = join(searchDir, agentName);
+        try {
+            const entries = await readdir(agentDir);
+            return entries
+                .filter((e) => e.endsWith(".md") && e !== "agent.md")
+                .map((e) => e.replace(/\.md$/, ""));
+        }
+        catch {
+            continue;
+        }
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function resolveDirectPath(agentPath, operation, projectDir) {
+    const absPath = projectDir
+        ? resolve(projectDir, agentPath)
+        : resolve(agentPath);
+    if (!(await fileExists(absPath))) {
+        throw new Error(`Agent file not found: ${absPath}`);
+    }
+    // Check if it's a directory-style agent (path ends with agent.md).
+    const isDir = basename(absPath) === "agent.md";
+    let operationPath;
+    if (operation) {
+        if (!isDir) {
+            throw new Error(`Agent at "${absPath}" is a flat file and does not support operation "${operation}"`);
+        }
+        operationPath = resolve(dirname(absPath), `${operation}.md`);
+        if (!(await fileExists(operationPath))) {
+            throw new Error(`Operation "${operation}" not found at: ${operationPath}`);
+        }
+    }
+    return { agentPath: absPath, operationPath, isDirectory: isDir };
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=agent-resolver.js.map

package/dist/agent-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-resolver.js","sourceRoot":"","sources":["../src/agent-resolver.ts"],"names":[],"mappings":"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"}

package/dist/agent.d.ts

@@ -0,0 +1,39 @@
+import type { AgentResult } from "./types.js";
+export interface DispatchOptions {
+    /** The user prompt (task context) passed via -p. */
+    userPrompt: string;
+    /** Path to the system prompt file (agent markdown). */
+    systemPromptFile: string;
+    /** Path to MCP config JSON file, if any. */
+    mcpConfigFile?: string;
+    /** Explicit list of allowed tools. */
+    allowedTools?: string[];
+    /** Expected output file path (to check existence after). */
+    expectedOutput?: string;
+    /** Working directory for the subprocess. */
+    cwd: string;
+    /** If true, print the command instead of running it. */
+    dryRun?: boolean;
+    /** Agent name (for stream logging). */
+    agentName?: string;
+    /** Directory for stream log files (.stream.jsonl). */
+    streamLogDir?: string;
+    /** Callback for stream activity updates. */
+    onActivity?: (activity: import("./stream/stream.js").AgentActivity) => void;
+    /** Claude config directory (CLAUDE_CONFIG_DIR). */
+    claudeConfigDir?: string;
+    /** Permission mode for the agent subprocess (default: bypassPermissions). */
+    permissionMode?: string;
+    /** Suppress agent stderr (when TUI dashboard is rendering). */
+    quiet?: boolean;
+}
+/**
+ * Dispatch an agent by spawning `claude` as a child process.
+ *
+ * Agents inherit the project's CLAUDE.md, hooks, and auth context.
+ * The agent's markdown definition is appended via --append-system-prompt-file.
+ *
+ * Returns an AgentResult with exit code, output existence check, and duration.
+ * In dry-run mode, prints the command and returns a synthetic success result.
+ */
+export declare function dispatchAgent(opts: DispatchOptions): Promise<AgentResult>;

package/dist/agent.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { StreamParser } from "./stream/stream.js";
+// ---------------------------------------------------------------------------
+// Build the claude CLI argument list
+// ---------------------------------------------------------------------------
+function buildArgs(opts) {
+    const args = [
+        "-p",
+        opts.userPrompt,
+        "--append-system-prompt-file",
+        opts.systemPromptFile,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+    ];
+    if (opts.mcpConfigFile) {
+        args.push("--mcp-config", opts.mcpConfigFile);
+        args.push("--strict-mcp-config");
+    }
+    if (opts.allowedTools?.length) {
+        args.push("--allowedTools", opts.allowedTools.join(","));
+    }
+    // Permission mode — default to bypassPermissions for pipeline agents.
+    const mode = opts.permissionMode ?? "bypassPermissions";
+    args.push("--permission-mode", mode);
+    return args;
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+/**
+ * Dispatch an agent by spawning `claude` as a child process.
+ *
+ * Agents inherit the project's CLAUDE.md, hooks, and auth context.
+ * The agent's markdown definition is appended via --append-system-prompt-file.
+ *
+ * Returns an AgentResult with exit code, output existence check, and duration.
+ * In dry-run mode, prints the command and returns a synthetic success result.
+ */
+export async function dispatchAgent(opts) {
+    const args = buildArgs(opts);
+    if (opts.dryRun) {
+        console.log("\n[dry-run] Would execute:");
+        console.log(`  claude ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`);
+        console.log(`  cwd: ${opts.cwd}`);
+        if (opts.claudeConfigDir) {
+            console.log(`  CLAUDE_CONFIG_DIR: ${opts.claudeConfigDir}`);
+        }
+        if (opts.expectedOutput) {
+            console.log(`  expected output: ${opts.expectedOutput}`);
+        }
+        return {
+            exitCode: 0,
+            outputPath: opts.expectedOutput,
+            outputExists: false,
+            durationMs: 0,
+        };
+    }
+    const start = Date.now();
+    const agentName = opts.agentName ?? "agent";
+    // Set up stream parser for event processing and logging.
+    const parser = new StreamParser(agentName);
+    if (opts.streamLogDir) {
+        const logPath = `${opts.streamLogDir}/${agentName}.stream.jsonl`;
+        await parser.startLog(logPath);
+    }
+    if (opts.onActivity) {
+        parser.on("activity", opts.onActivity);
+    }
+    // Build environment — inherit parent env, set CLAUDE_CONFIG_DIR if configured.
+    const env = { ...process.env };
+    if (opts.claudeConfigDir) {
+        env.CLAUDE_CONFIG_DIR = opts.claudeConfigDir;
+    }
+    const exitCode = await new Promise((resolve, reject) => {
+        const child = spawn("claude", args, {
+            cwd: opts.cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Feed stdout through stream parser.
+        child.stdout.on("data", (chunk) => {
+            parser.feed(chunk.toString());
+        });
+        // Stderr goes to parent stderr (unless TUI is active).
+        if (!opts.quiet) {
+            child.stderr.pipe(process.stderr);
+        }
+        child.on("error", (err) => {
+            parser.flush();
+            reject(new Error(`Failed to spawn claude: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            parser.flush();
+            resolve(code ?? 1);
+        });
+    });
+    const durationMs = Date.now() - start;
+    let outputExists = false;
+    if (opts.expectedOutput) {
+        try {
+            await access(opts.expectedOutput);
+            outputExists = true;
+        }
+        catch {
+            outputExists = false;
+        }
+    }
+    return {
+        exitCode,
+        outputPath: opts.expectedOutput,
+        outputExists,
+        durationMs,
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/autoresearch.d.ts

@@ -0,0 +1,11 @@
+import type { AutoresearchStage, AutoresearchResult, RunContext, PipelineState } from "./types.js";
+/**
+ * Execute a full Adjust-Execute-Evaluate cycle for an autoresearch stage.
+ *
+ * 1. [iter > 1] Dispatch adjuster → modifies the artifact
+ * 2. Dispatch executor → produces output using current artifact
+ * 3. Dispatch evaluator → compares output against ground truth
+ * 4. Parse evaluation (regex on ### Overall: PASS/FAIL)
+ * 5. Route: PASS → done, FAIL + max reached → escalate, FAIL → continue
+ */
+export declare function runAutoresearchCycle(stage: AutoresearchStage, ctx: RunContext, state: PipelineState, onProgress?: (eventType?: string, eventData?: Record<string, unknown>) => Promise<void>): Promise<AutoresearchResult>;