conductor-ai-code-agent

Conductor

An AI coding harness with a 14-gate flow, 22 roles and 30 skills. This is the Node.js/TypeScript implementation of Conductor — the global CLI cdt (alias conductor) — a faithful port of the Python original conductor-main.

Version 0.6.0 · Node.js ≥ 18 · TypeScript (strict) · CommonJS

Conductor conducts an AI coding agent through a 14-gate flow — from domain discovery and specification through implementation, security, and penetration testing — using a crew of 22 roles (each paired 1:1 with a skill), 30 skills, and 5 turn-time rules. It works in two complementary modes:

• Native harness — Conductor holds its own credentials, calls the LLM providers directly, runs its own agent loop (cdt chat), and loads roles/skills/flow natively. Works with API keys or keyless local models (Ollama, llama.cpp, LM Studio, vLLM) — no key at all.
• Emitter — Conductor writes its roles/skills/flow into another harness's native layout (Claude Code, Codex, OpenCode, Cursor, Kimi, Pi), so you keep driving your own licensed subscription CLI, shaped by Conductor.

Why both exist is economic and ethical: the only legitimate way to use a subscription (Claude Max / ChatGPT) is through the provider's own licensed CLI. Conductor never impersonates another application's OAuth client to reach a subscription from the native loop — subscriptions go through emission, API keys and local models run natively.

Table of contents

• Key features
• Quickstart
• The 14-gate flow
• The /cdt commands
• Roles, skills and rules
• CLI reference
• Project layout
• Development
• Documentation
• Related projects

Key features

The flow

• 14-gate flow (templates/flow.md) — discovery → spec (SDD) → security by design → architecture/SLOs → test-first → implementation → CI & supply-chain → validation → app pentest → release readiness → observability → continuous learning → local pentest (Docker replica) → VPS/cloud pentest. Each gate has a mandatory protocol, a depth calibration, and an associated role/model.
• Mechanical enforcement — two git hooks wired by cdt init/cdt sync:
  • cdt gate guard (commit-msg hook) — the grounding gate: blocks a substantive code commit that skipped the library (fail-open by design).
  • cdt gate prepush (pre-push hook) — the landing guard: blocks a push to develop/main that is missing a mandatory gate {3, 5, 7, 8, 9}, returning a three-valued verdict allow / deny / could-not-evaluate — tooling failures surface loudly, never silently collapse into allow.
• Four drivers — /cdt (interactive, stops for your approval at every gate), /cdt-intake (the front door: triage + rich spec), /cdt-triage (unattended loop over CI failures/issues/commits), /cdt-auto (autonomous gate execution with auto-approve, context monitoring and resume).

Roles, skills and rules

• 22 roles — scoped to general software development (engineering, architecture, data, ops, quality, security and design; e.g. tech-lead, software-engineer, software-architect, security-engineer, qa-guardian, sdet, ux-designer, ...). The role ↔ skill relation is 1:1 (invariant R7), and the delegation graph (spawns) is a validated DAG executed by the task tool.
• 30 skills — 22 role-paired + 3 meta-skills (self-learning, quality-baseline, choose-visual-direction) + 5 role extra_skills (incident-response, supply-chain-security, secure-coding-patterns, pentest-infrastructure, audit-visual-design).
• 5 rules — core, grounding-at-commit, no-secrets, schema-change, test-first. Rules carry frontmatter (condition, scope, interruptMode, alwaysApply) evaluated by a turn-time rule engine (TTSR) mid-stream, so a rule fires while the model is producing prose or a tool call — not after the fact.

Native harness

• 18 providers — 13 API-key (anthropic, openai, openrouter, deepseek, groq, mistral, google, xai, zai, moonshot, together, fireworks, cerebras), 4 keyless local (ollama, llamacpp, lmstudio, vllm), 1 custom OpenAI-compatible endpoint.
• Agent loop (agent/loop.ts) — engine that knows nothing of disk, session or policy; every decision is a callback. One loop serves the main session, subagents and the advisor.
• Advisor & reactive fallback — a second-model reviewer (--advisor, read-only) and cross-provider model fallback when the primary fails.
• Sessions — append-only entry tree (id/parentId) with fork, branch, undo and compaction (cdt session).
• Budget — token/currency budgeting (src/budget.ts, .cdt/triage.json), enforced even across subagent delegation.
• Toolkit — file read/write/edit, shell, search, skill loading, delegation, code evaluation kernels, artifacts, ask_user, and more.

Projects and memory

• Enrolment — cdt init / cdt sync write .cdt/ (stack profile, build/test/lint/run recipes, memory tree, triage policy) and emit the adapter files into the chosen target harness.
• Library / RAG — cdt up starts a native stack (Ollama with bge-m3 embeddings + embedded ChromaDB, no Docker required) and ingests a bundled reference corpus (library/) of engineering books. Precomputed embeddings can be exported/imported as a portable artifact — no GPU, no hours of CPU embedding.
• Memory and diary — per-project journal (cdt journal, JSONL), semantic diary via Honcho (cdt honcho setup|up|down|ask), local memory backend, and project skills (cdt learn distill writes to .cdt/skills/ and overrides the built-in of the same name).
• Redaction — a shared redaction layer protects secrets in exports and anywhere else the harness emits content; credentials are stored with OS-level protection (DPAPI on Windows).

Intelligence, integration and learning

• Cross-project intelligence — knowledge graph extracted from the library (cdt graph), anonymized fleet insights (cdt fleet), plus confidence, contradiction, effectiveness, patterns, prediction, risk and project-similarity modules (src/intelligence/).
• MCP — Conductor's memories (library + journal) exposed as an MCP stdio server (cdt mcp); external MCP servers can be consumed inside cdt chat (cdt mcp add ...).
• Document generation — cdt doc renders any Markdown file to docx/pdf; cdt export assembles a gate/session range into a redacted, shareable deliverable.
• Learning and feedback — cdt learn distill distills a reusable skill from a successful session (automatic on session end); cdt feedback tells the scaffolder what misfired so it can learn across projects.
• Operations — cdt doctor (health), cdt config, cdt stats (token usage/cost by gate/role/model), cdt completions, cdt update, cdt cleanup-docker.

Quickstart

Prerequisite: Node.js ≥ 18.

# 1. Build and install the CLI (from this repo)
npm install
npm run build
npm link            # exposes `cdt` and `conductor` on your PATH

# 2. Start the native RAG stack (Ollama embeddings + embedded ChromaDB).
#    No Docker required; asks before the ~1.2 GB model download.
cdt up

# 3. Enrol a project and emit Conductor into your harness
cd /path/to/your-project
cdt init            # .cdt/ stack, recipes, memory tree + emit (default: claude)
cdt detect          # see the project's languages/frameworks
cdt up              # re-run FROM the project: ingests its stack books too

# 4. Reload your AI coding harness in that project, then drive a feature:
#    /cdt implement <your feature>   (interactive — stops at every gate)

Optional — semantic diary recall (the local JSONL journal works without it):

cdt honcho setup --provider ollama    # key-free; or deepseek/openai/... (needs a key)
cdt honcho up                         # Honcho diary backend (needs Docker)

Handy along the way:

cdt library "<question>"              # ground an answer in the reference books (RAG)
cdt journal recall "<question>"       # what this project already decided
cdt sync                              # after upgrading: refresh an enrolled project
cdt chat --gate 9 --role application-security-engineer   # native talk, gate's model + role

The 14-gate flow

#	Gate	Model role
1	Domain discovery and modeling	plan
2	Specification as the source of truth (SDD)	plan
3	Security and privacy by design (shift-left)	slow
4	Architecture, defensive design, and SLOs	plan
5	Test-first / executable specification	default
6	Implementation with clean code	default
7	Continuous integration, supply chain + quality gate	smol
8	Validation against the spec (feedback loop)	slow
9	Application penetration testing	slow
10	Release readiness & progressive delivery	default
11	Observability and operation	default
12	Continuous learning	smol
13	Local penetration testing (Docker replica)	slow
14	VPS/cloud penetration testing and hardening	slow

The model roles (slow / plan / default / smol) decide which model runs each gate and how hard it works. In the native harness this is an executed decision; in emission it is delegated to the licensed CLI that honours the hint. Gates 3, 5, 7, 8 and 9 are mandatory — the landing guard enforces them at push time.

The /cdt commands

Command	What it does
/cdt-intake <demand>	The front door. Triages the demand — greenfield / feature / bugfix — by risk × complexity × criticality, optionally writes a layman-friendly client-questions document, then a rich spec, and hands off to /cdt. Stops before generating client documents and before handing off.
/cdt <demand>	The driver. Conducts the demand through the 14 gates, stopping for your approval at every gate — it refuses to run unattended. Calibrates depth, never skips the checkpoint, never collapses gates 3, 5, 7, 8. Gate roles run as subagents.
/cdt-triage	The unattended loop. Runs on a schedule (e.g. each morning): scans recent CI failures, open issues and commits, records findings to the journal, hands actionable work to maker/checker subagents. Reads .cdt/triage.json (token budget, stop conditions) and runs headless.
/cdt-auto	Autonomous 14-gate execution with auto-approve, context monitoring and resume.

Roles, skills and rules

• 22 roles in src/roles.ts — each an agent template under templates/agents/, each paired 1:1 with a skill. The delegation graph (spawns) is a validated DAG of known roles (invariant R23).
• 30 skills under templates/skills/*/SKILL.md — each with a "When to use" section and numbered steps (invariant R6).
• 5 rules under templates/rules/ — core.md, grounding-at-commit.md, no-secrets.md, schema-change.md, test-first.md — always-on/conditional rules that fire at turn-time via the TTSR engine.

CLI reference

cdt chat [message] [--gate N] [--role R] [--advisor]   # /login, /logout, /models, /effort inside
cdt auth [login|logout|status|list]
cdt init [path] [--target spec] | cdt sync | cdt detect | cdt list
cdt target list|show|update <spec>          # emit targets (dual-mode)
cdt library "<question>" | status|stacks|reindex|update|add|export|import|compact
cdt journal add|recall|log                  # project diary
cdt journal edit <id> [text] --mode update|forget|invalidate  # correct/retire a diary entry (syncs to memory backend)
cdt learn distill                           # distill a skill (auto: SessionEnd)
cdt gate guard|status                       # grounding hard gate (auto: commit-msg)
cdt gate prepush|land-status                # landing guard (auto: pre-push)
cdt up | down [--docker] | cdt ingest       # native RAG stack
cdt honcho setup|up|down|ask                # semantic diary (Honcho)
cdt mcp [--transport ...]                   # MCP server (memories)
cdt doc <file.md> [--format ...]            # render docx/pdf from markdown
cdt export [--gates N-M] [--kind k1,k2] [--format docx|pdf|html]
cdt graph <entity>|build|stats              # knowledge graph
cdt fleet [--save|--json]                   # cross-project insights
cdt feedback "<...>"|report|list|consent    # feedback to the scaffolder
cdt config get|set|validate | cdt doctor [path] | cdt completions <shell>
cdt update [--reinstall] | cdt cleanup-docker [--yes]
cdt quickstart | version | help

Every command takes cdt <command> --help for options; unknown commands get a "did you mean ...?" suggestion. Full reference: docs/features/en/cli-reference.md.

Project layout

bin/cdt.js            CLI entry point (require dist/cli.js)
src/
  cli.ts              command dispatch, usage, quickstart
  agent/              native harness: loop, host, advisor, tui, plain
  llm/                providers (anthropic, openai-compatible), catalog,
                      schema compat, tool-call dialect, JSON streaming
  rag/                RAG core, ingestion, stack (Ollama + embedded ChromaDB),
                      portable export/import
  tools/              agent tools: files, shell, search, skills, task,
                      eval kernels, artifacts, ask_user, ...
  targets/            harness emitters: claude, codex, opencode, cursor,
                      kimi, pi
  intelligence/       knowledge graph, fleet, code-aware RAG, confidence,
                      contradiction, effectiveness, patterns, predict, risk
  session.ts          append-only session tree (fork/branch/undo)
  journal.ts          per-project diary (JSONL)
  ttsr.ts             turn-time rule engine
  gate.ts             grounding hard gate (commit-msg hook)
  gate_land.ts        landing guard (pre-push hook, three-valued verdict)
  redact.ts           secret redaction layer
  budget.ts           token/currency budget
  project.ts          enrolment, .cdt/ config, home/profile resolution
  + auth, credentials (DPAPI), oauth, detect, docgen, export, learn,
    feedback, doctor, mcp client/server, honcho, update, worktree, ...
templates/            harness-neutral surfaces: agents, skills, rules,
                      commands, automations, flow.md, e2e
library/              bundled reference corpus (categories 01–14) +
                      precomputed embeddings (portable import)
docs/                 feature docs (en + pt-BR), ADRs, specs, security
                      threat models, QA reports
tests/                vitest suites (ports of the Python original's tests)
infra/                legacy Docker compose (conductor, honcho)

Development

Requires Node.js ≥ 18.

npm install          # install dependencies
npm run build        # tsc -> dist/
npm run dev          # run the CLI from source via tsx (src/cli.ts)
npm test             # vitest run (tests/surfaces, e2e_init, budget, ...)
npm run test:watch   # vitest watch
npm run lint         # eslint src tests
npm run typecheck    # tsc --noEmit

The test suite is hermetic: it redirects CONDUCTOR_HOME to a temp dir and needs no Docker or network to pass.

Port status

This is a deliberate, line-by-line port of the Python conductor-main, and most of its behaviour is verified by ported tests and a full parity audit (kept alongside the workspace). MCP tools invocable mid-turn in interactive cdt chat, isolated-worktree subagents, and HNSW indexing in the RAG core — once the audit's headline gaps — are now implemented and covered by tests (tests/chat_cmd_mcp_wiring.test.ts, src/agent/host.ts's spawn({isolated: true}), tests/rag_hnsw.test.ts). Remaining gaps live in the parity audit itself; contributions to close them are welcome.

Documentation

• Features reference (EN) — one topic per file: overview, gate flow, roles/skills/rules, native harness, providers/models, emission, RAG library, memory & diary, export & redaction, MCP, learning, cross-project intelligence, CLI reference.
• Guia de funcionalidades (PT-BR)
• Architecture decision records — 18 ADRs covering the redaction seam, TTSR engine, landing guard, advisor/fallback, hardening, and more.
• Specs, Security threat models, QA reports, Postmortems.

Related projects

• conductor-main — the Python original this project ports (also the source of the install one-liners referenced by cdt quickstart).
• conductor-library / conductor-viewer — the reference corpus and its viewer, part of the Conductor ecosystem.

Portuguese: um guia em português dos recursos está em docs/features/pt-BR.