codeconductor：AI Agent 工具实践指南

在项目中评估codeconductor，可以先看清用途边界：codeconductor是一个AI-辅助软件工程框架，旨在将混沌提示转变为可重现的工程系统。团队若要把它用于日常自动化，应先处理输入边界、依赖和失败处理如果不清楚就很难稳定复用，否则试用结果很容易失真。我的评估方法是用一项范围明确的真实任务完成最小试跑，然后检查配置时间、输出质量、异常信息和维护痕迹是否与文档一致。对愿意先做小范围验证并复查原始文档的团队来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

codeconductor

停止提示。开始编排。

codeconductor 是一个开源框架，用于构建结构化、可重复的 AI- 辅助软件工程工作流程。

它帮助开发人员和团队协调专业代理进行规划、 实施、测试、文档和审查——使用版本化代理 合同、任务卡和基于风险的路由。

[!IMPORTANT]

Current Scope

发布的软件包是1.6.1（当前稳定行：1.6.x）。局限性 矩阵： docs/current-status.md。这个存储库： 迭代时为 bun run dev …（不是 npx）。

在 1.6.x 稳定版中发布：

• npx cc-codeconductor setup --target <target> --yes — 入职流程
• npx cc-codeconductor init — 检测项目堆栈，写入 .codeconductor/config.yml，将council.yml和policy.yml复制到 .codeconductor/presets/
• npx cc-codeconductor install council --target <opencode|克劳德|法典|双子座|光标|阿吉|圆周率|全部>
• npx cc-codeconductor install preset --target <opencode|克劳德|法典|双子座|光标|阿吉|圆周率|缪斯|全部>
• npx cc-codeconductor install lsp --target <…>
• npx cc-codeconductor detect / status / version / doctor / update / migrate
• npx cc-codeconductor seo audit / seo llms（SSRF-受保护的获取）
• npx cc-codeconductor help / cc-help（不同的合约 - 参见中断 更改如下）
• npx cc-codeconductor ask "<problem>" — 推荐 /cc: 斜线命令
• npx cc-codeconductor debt-harvest（别名：harvest）
• npx cc-codeconductor ccep … — CCEP 是规范的消费者工作流程循环 (parse / profile / resolve / compile / validate / evaluate / consensus / taskcard)
• npx cc-codeconductor openspec … — OpenSpec 交付循环和积压工具 (validate / scan / plan / status / next / start / done / block / archive)
• npx cc-codeconductor scorecard …
• npx cc-codeconductor goal / ingest / product / orchestrate / impact / verify — 产品 OS（参见 docs/product-os.md)
• install preset 之后的斜线命令 — 21 CCEP 工作流程加上 /cc-ask； 优先使用 /cc-iterative、/cc-triage、/cc-handoff 进行寻路； /cc-backlog 作者 BACKLOG.md； /cc-openspec 和 /cc-tdd-cycle 用于交货和 TDD
• /cc-pagespeed --url <url> — PageSpeed 洞察/核心网络生命之后 install preset; PAGESPEED_API_KEY 可选，但推荐使用 CrUX 现场数据（参见docs/pagespeed-usage.md）
• /cc-security / /cc:security — 授权防御安全工作流程 具有域 security-* 技能和授权门
• 堆栈特定技能选择（ts-next-drizzle、spring-kotlin-jpa、 laravel-tall, python-data-api)
• 理事会共识：法定人数，所需信心，criticalFindingsPolicy， 加上 securityVeto / complianceVeto
• 15 个指挥代理，包括 reviewer、security-reviewer 和 complexity-auditor

实验性（仅限库，不是 CLI 运行时）：

• runWorkflowPipeline() — 8 相环路输入 src/core/pipeline/workflow-loop.ts

尚不存在的：

• 运行时沙箱/OS-级别隔离
• 政策制定者/统一目标执行
• 全栈特定资产修剪

安全说明：策略是声明性的。代理执行取决于目标 跑步者。 install preset --target cursor 覆盖运行器命令目录； 仅维护者存根（cc-self-review、cc-update-preset-models）是 已跳过，因此此存储库可以进行测试 install preset。

推荐CLI流量

从高级入门命令开始，然后使用维护命令 检查并协调已安装的线束：

npx cc-codeconductor setup --target claude --yes
npx cc-codeconductor status
npx cc-codeconductor version
npx cc-codeconductor doctor
npx cc-codeconductor update --check
npx cc-codeconductor migrate --dry-run

• setup 检测项目，初始化线束，安装选定的 目标，并运行 doctor。
• status为轻量级安装仪表板； version 报告 CLI 和项目线束版本。
• doctor 诊断配置和托管文件。 update 安全协调 安装的线束文件，同时 migrate 应用兼容性修复。
• init 和 install 仍然可用作自动化的低级原语 和有针对性的安装。

为什么是codeconductor？

大多数 AI 编码工作流程都会失败，因为它们将模型视为开发人员。

codeconductor 将模型视为受控内部的专业工人 工程系统。它定义：

• 谁计划
• 谁实施
• 谁测试
• 谁评论
• 何时升级
• 何时停止
• 代理合同如何随时间演变

这不是一个即时收集。它是一个工作流框架。

历史记录：v1.3.0

v1.3.0 是 1.3.x 系列中的稳定版本。它保留了 v1.0.0 工作流程合同基线并添加跨目标预设修复、集中化 技能版本控制、跑步者同等性改进和上下文网页设计 工程技能。升级后重新安装预设。

与 v0.5.0 的重大变化

• help 与 cc-help。 help 打印 CLI 命令列表。库存 技能、子代理和命令是 cc-help --target。 help --target 无 更长地列出该库存。
• 规范 TaskCard。 交货摄入量为 ccep taskcard。 OpenSpec 卡 保持相视图（phase、backlogId、prompt、agent）并且不是 崩溃到Canonical。
• 理事会达成共识。 带有 ccep consensus --input @verdicts.json 的门（退出 0/1/2 = APPROVED / REJECTED / ESCALATED）。多数需要法定人数， 显式 confidence 和 criticalFindingsPolicy（默认值：升级）。那里 不是顶级 cc council 命令。
• OpenSpec 状态机。 start / done / block / archive 写入 BACKLOG.md 和 openspec-state.json 原子地。非法转换失败 关闭。
• 架构。 ExecutionContext.ast.source 包括 product-graph。 ReviewerOutput 查找 axis 通过参谋工程师轴进行扩展。
• CCEP bootstrap. 安装的斜线命令运行 ccep profile → compile （每个委派阶段一个角色范围的提示）→ 委派前 evaluate 给代理商。代理 JSON 必须验证 对抗佐德；未知的输出模式关闭失败。

斜杠命令

在 install preset 之后，21 个 CCEP 工作流程加上 /cc-ask（总共 22 个），分层 他们做什么而不是他们接触哪个子系统：

优选使用 /cc-iterative、/cc-triage 和 /cc-handoff 进行寻路。 /cc-ask 推荐来自自然语言问题的命令；它没有 启动工作流程。

ODD 采用和升级

ODD 选择加入，直到配对交付证据显示非劣质接受， 测试以及上下文低于 OpenSpec 的结果。运行 bun run dev scorecard suite-run --suite odd-adoption 保留该决定 可重现。 ODD 采用指南 说明路线 选择、基于账本的恢复以及何时返回到 OpenSpec、TDD 或 理事会。

OpenSpec 和 TDD

OpenSpec 是 BACKLOG.md 的传递循环：

validate → scan → plan → status → next → start → done | block → archive

代理阶段：验证积压→发现→设计→测试→实施→ 审查。只要两个阶段都适用，就需要实施前测试。 /cc-tdd-cycle 强制红色 → 绿色 → 重构（tester 然后 implementer）。

收据驱动开发

RDD 将本地验证证据与确切的代码、测试、合约、 锁定文件及其观察到的配置。使用bun run dev rdd capture --task <id>, bun 运行 dev rdd verify --receipt <id>, and bun 运行 dev rdd status 检查该证据。更改后的候选人将使其收据无效并要求 受影响的验证再次运行。 RDD 补充了 TDD 和突变 测试：它检查证据的新鲜度而不是行为的覆盖范围。 在 Git 存储库中运行 bun run dev rdd install-hooks 来安装保留 预提交和预推送检查；该钩子针对最新的运行 rdd git-check 收据。

审核代理

15 个指挥代理在 presets/<target>/agents/ 中发货。审核路径：

• reviewer — CRITICAL / WARNING / SUGGESTION 的审核报告； CRITICAL 块合并
• security-reviewer — 专用安全分析； securityVeto 覆盖 多数共识
• complexity-auditor — 膨胀和非原生抽象；之前运行 reviewer 重构、API 更改和数据库迁移路线

v1.0.0合约基线介绍了business-agent， continuous-architect 和 impact-analyst。

确定性 TypeScript 验证 (CCEP)

CCEP就是CLI + Zod，没有额外的提示。来源：src/core/ccep/ 和 src/validation/schemas.ts.

parseCommand → resolveContext → resolveWorkflowPhase → compilePrompt → validateAgentOutputBySchema

npx cc-codeconductor ccep parse --command review "PR #42" --output json
npx cc-codeconductor ccep profile tdd-cycle --output json
npx cc-codeconductor ccep validate --command feature --phase implement --role implementer --output json 
  '{"status":"success","confidence":0.9,"warnings":[],"artifacts":[],"next_actions":[],"filesChanged":[],"tests":{"runner":"bun test","result":"passed"}}'
npx cc-codeconductor ccep consensus --input @verdicts.json
npx cc-codeconductor ccep taskcard --command feature --input @card.json

ccep validate 根据命名模式检查每个角色的 JSON (planner-output, implementer-output, review-report, technical-plan, council-verdict，……）。请参见 docs/CCEP.md。

产品 OS

稳定产品线包括 goal / ingest / product / orchestrate / impact / verify，加上 .codeconductor/product-graph.json 和相关工件。 详细信息： docs/v1.3.0-release-notes.md 和 docs/product-os.md.

从 v0.5.0 迁移

npx cc-codeconductor install preset --target=<opencode|claude|cursor|codex|gemini|agy|pi|muse> --force

核心概念

它是如何运作的

Task Card → Risk Classification → Routing Policy → Conductor Agent → Deliverable → Scorecard

1. 使用结构化任务卡定义任务
2. 风险分类（低/中/高）
3. 路由到正确的 Conductor Agent
4. 有限制地实施
5. 通过测试验证
6. 合并前审查

当前支持

• OpenCode、Claude、Codex、Gemini、Cursor、Agy 和 Pi 预设
• 克劳德代码兼容预设（请参阅 Claude 环境选项和最佳实践)
• Spring Boot / Kotlin 工作流程
• Python / Django 工作流程指导
• 15 个指挥代理 — 包括 reviewer、security-reviewer、 complexity-auditor、business-agent、continuous-architect 和 impact-analyst
• 21 CCEP 斜杠命令工作流程加上 install preset 之后的 /cc-ask
• OpenSpec 交付循环 (validate … archive) 实施前测试
• 确定性 CCEP 验证（每个代理角色的 Zod 模式）
• 任务卡模板
• 记分卡模板
• 端到端示例
• YAML-驱动型号配置
• 与提供者无关的 AgentContract 抽象，具有目标渲染器 克劳德、OpenCode、Codex 和 Agy
• 用于多代理治理的理事会共识引擎（councilConsensus()） 使用 majority/unanimous 算法、法定人数、所需置信度、 criticalFindingsPolicy、安全否决、合规否决
• 第 5 阶段运行时模块 — 范围上下文注入、TDD 历史压缩、 简洁的代理间消息传递以及编译修复中的令牌预算执行 循环
• 工作流循环核心（实验性） — 8 阶段管道 (runWorkflowPipeline) 带挂钟/文件修改/线路更改 设计和委员会裁决中的护栏和 STOP 大门（仅限图书馆；不是 发货 CLI 运行时）
• 堆栈特定预设 — ts-next-drizzle、spring-kotlin-jpa、 laravel-tall, python-data-api
• 专业技能 — 细雨模式架构师， Tailwind-responsive-auditor、seo-analytics-injector、jpa-nplusone- detector、 spring-auth-auditor、livewire-alpine-bridge、fastapi-pydantic-strict、 tdd 突变测试器、身份验证令牌检查器
• 目标编排 — goal 规划者 + goal-state 编写者提供反馈 Orchestrator 的依赖顺序委托循环
• 内存压缩 + 升级发射器 - 将代理间上下文保持在内部 代币预算和表面护栏破坏作为升级报告

供应链

已发布 1.6.1 声明两个生产依赖项 (package.json dependencies;同样的 npm）。两者都没有进一步 npm transitive dependencies.

graph LR
  cc["[email protected]"]
  zod["zod@^3.23.8"]
  yaml["yaml@^2.4.5"]
  cc --> zod
  cc --> yaml

预期的运行时功能（用户调用的 CLI 命令，不是 npm 安装):

• 网络 — seo audit / seo llms（safeFetch 带有 SSRF 防护装置）； install lsp 二进制下载（固定 URL + SHA-256）
• 进程spawn（无shell） - git（scorecard，OpenSpec，循环防护）； verify / 编译检查； doctor； install lsp (tar / npm / pip)

没有 preinstall / postinstall 生命周期脚本。插座可能仍然 在已发布的捆绑包中标记网络和 shell 功能存在；那就是 此 CLI 是预期的，并且不是安装时执行。

用于实时漏洞扫描、依赖性警报和运行时行为 分析，参见 套接字 — cc-codeconductor 依赖项。

程序化 API

除了 CLI 之外，cc-codeconductor 还附带一个库条目。 bin 命令仍然解析为 dist/index.js。应用程序代码应导入 包根目录：

import {
  LoopEngine,
  runLoop,
  runVerification,
  getNextTask,
  startTask,
  completeTask,
  loopStateMachine,
  createInitialState,
} from 'cc-codeconductor';

导出表面（此次要稳定）：

• 编排器：getReadyTasks、getNextTask、startTask、completeTask、 goalTaskToCanonicalCard, buildTaskEnvelope, formatGoalStatus
• 循环引擎（TC3）：LoopEngine、runLoop、runLoopForProject、 shouldRunAgentLoop, formatFeedback
• 验证：runVerification、gateTaskCompletion、validateEvidenceIds
• Zod 合约：src/validation/schemas.ts 中的所有内容
• 域循环：createInitialState、loopStateMachine及其类型

infrastructure/ 和 *-internal 模块不属于公共 API 的一部分。

bun run build   # CLI → dist/index.js, library → dist/library.js + .d.ts

CLI 用法

安装

# Requires Bun ≥1.0 or Node ≥20.11
bun run src/cli/main.ts --help
# or after build:
# node dist/index.js --help

命令

init — 在项目中初始化 codeconductor

npx cc-codeconductor init              # detect stack, write .codeconductor/config.yml
npx cc-codeconductor init --force      # overwrite existing config
npx cc-codeconductor init --global     # write to ~/.codeconductor/
npx cc-codeconductor init --dry-run    # preview without writing
npx cc-codeconductor init --locale=es  # set Spanish as the instruction language
npx cc-codeconductor init --locale=en  # set English (default)

第一次运行时，init 将 council.yml 和 policy.yml 复制到 .codeconductor/presets/，这样您就可以在不接触框架的情况下自定义它们 文件。 install 首先从那里读取。

[!IMPORTANT]

--locale 被记住。 一旦运行 init --locale=es，该值为 保存到.codeconductor/config.yml。随后的每个 install preset 将 自动使用该区域设置 - 无需重复该标志。要更改它，请运行 init --locale=en --force 或在配置中编辑 defaults.locale。

detect — 检测项目堆栈

npx cc-codeconductor detect
npx cc-codeconductor detect --output json

输出：

Detected:
  - languages: javascript, typescript
  - runtimes: node, bun
  - frameworks: ...

install preset — 安装完整代理预设

npx cc-codeconductor install preset --target opencode     # project-level
npx cc-codeconductor install preset --target claude
npx cc-codeconductor install preset --target codex
npx cc-codeconductor install preset --target agy          # antigravity cli
npx cc-codeconductor install preset --target pi            # pi.dev coding agent
npx cc-codeconductor install preset --target all          # all targets

npx cc-codeconductor install preset --target claude --global   # write to ~/.claude/
npx cc-codeconductor install preset --target all --global

npx cc-codeconductor install preset --target claude --locale=es   # override locale once
npx cc-codeconductor install preset --target all --dry-run        # preview
npx cc-codeconductor install preset --target claude --force       # overwrite

区域设置解析顺序（第一场比赛获胜）：

1. 命令行上的 --locale 标志
2. .codeconductor/config.yml中的defaults.locale（由init --locale设置）
3. en（内置默认）

每个目标安装的文件：

使用--global，文件写入~/而不是./下。

堆栈特定预设 (v0.4.0)

四个堆栈特定预设现已在 presets/ 中发货，并在 src/core/presets/preset-registry.ts。每一个都捆绑了一个经过调整的 architect.md 和 implementer.md 单堆栈，加上匹配的专业技能 （见下文）。

// Programmatic access via the registry
import { listPresets, getPreset } from 'cc-codeconductor/core/presets/preset-registry';

listPresets();
// [
//   { name: 'council',            version: '0.1.0', ... },
//   { name: 'seo-hotel',          version: '0.3.0', ... },
//   { name: 'ts-next-drizzle',    version: '0.4.0', ... },
//   { name: 'spring-kotlin-jpa',  version: '0.4.0', ... },
//   { name: 'laravel-tall',       version: '0.4.0', ... },
//   { name: 'python-data-api',    version: '0.4.0', ... },
// ]

const next = getPreset('ts-next-drizzle');

init / detect 从项目中识别堆栈并连接匹配的 当您运行时，将专业技能转移到通用目标工作流程上 install preset。完整堆栈特定资产 pruning/replacement（交换 堆栈包的整个 agent/command 树）尚未实现 — 注册表和技能连接是真实的；将完整堆栈安装交换的声明视为 充满抱负，直到落地。

堆栈特定预设的全套资源位于 presets/<preset-name>/agents/ — 如果您需要应用，请手动复制它们 按名称预设。

install council — 安装委员会规范

npx cc-codeconductor install council --target opencode     # project-level
npx cc-codeconductor install council --target claude
npx cc-codeconductor install council --target codex
npx cc-codeconductor install council --target agy          # antigravity cli
npx cc-codeconductor install council --target pi            # pi.dev coding agent
npx cc-codeconductor install council --target all          # all targets

npx cc-codeconductor install council --target claude --global  # write to ~/.claude/
npx cc-codeconductor install council --target opencode --global
npx cc-codeconductor install council --target all --global

npx cc-codeconductor install council --target opencode --dry-run   # preview
npx cc-codeconductor install council --target opencode --force     # overwrite

install lsp — 安装和配置 LSP 服务器

npx cc-codeconductor install lsp --target opencode          # auto-detect languages
npx cc-codeconductor install lsp --target all               # all AI tools
npx cc-codeconductor install lsp --target claude --lang typescript,python  # explicit languages
npx cc-codeconductor install lsp --target all --global      # global install + global configs
npx cc-codeconductor install lsp --target cursor --dry-run  # preview
npx cc-codeconductor install lsp --target all --force       # overwrite existing configs

支持的语言：TypeScript、PHP、Python（通过 Pyright）、Kotlin。支持 目标：opencode、claude、codex、gemini、cursor、agy。

doctor — 验证配置

npx cc-codeconductor doctor

检查配置是否存在且有效，报告运行器目录状态，验证 AGENTS.md 和 CLAUDE.md 不超过 40KB 大小限制，并检查 是否有可用于已安装预设、目标运行器配置的更新，或者 技能。

update — 智能更新预设

npx cc-codeconductor update
npx cc-codeconductor update --force
npx cc-codeconductor update --dry-run
npx cc-codeconductor update --global

智能更新所有当前安装的目标预设、议会配置、 和技能（来自 skills-lock.json），将用户编辑保留在托管之外 块。还验证 AGENTS.md 和 CLAUDE.md 不超过 40KB 尺寸限制。

migrate — 修复克劳德代码 settings.json

npx cc-codeconductor migrate               # ./.claude/settings.json
npx cc-codeconductor migrate --global      # ~/.claude/settings.json
npx cc-codeconductor migrate --dry-run     # preview without writing
npx cc-codeconductor migrate --file .claude/settings.local.json

将每个 Write(path) 权限规则重写为 Edit(path) — Claude 代码 仅应用以第二种方式编写的文件范围规则，因此 Write(path) 静默规则永远不会匹配 - 并且会删除结果的重复数据。重装不行 删除磁盘上已有的错误规则（权限数组通过联合合并），所以这 是一个独立的修复通道，而不是 update 自行修复的东西。

help / cc-help — 不同的帮助合约

npx cc-codeconductor help                    # general CLI usage
npx cc-codeconductor --help                  # same general usage text
npx cc-codeconductor cc-help                 # preset inventory for active target
npx cc-codeconductor cc-help --target claude # inventory for a specific target
npx cc-codeconductor cc-help --output json   # machine-readable inventory

help 打印 CLI 命令列表。 cc-help 列出技能、子代理、命令、 以及活动预设（或指定的 --target）的工作流程。读取库存 来自项目根目录中的 presets/<target>/。

debt-harvest — 收集递延债务项目

npx cc-codeconductor debt-harvest            # scan src/ for // defer comments
npx cc-codeconductor debt-harvest --dir lib  # scan a different directory
npx cc-codeconductor harvest                 # alias
npx cc-codeconductor debt-harvest --output json

扫描源文件中的 // defer - [reason] 注释并将其合并到 .codeconductor/debt-ledger.md，按可选标签分组 （// defer - reason --tag）。源文件只读；只写账本。

支持的扩展：.ts、.tsx、.js、.jsx、.go、.rs、.java、 .kt, .swift, .cs, .php, .scala, .dart, .c, .cpp, .h, .hpp.

goal — 将目标分解为任务图

npx cc-codeconductor goal "Add user authentication"
npx cc-codeconductor goal "Implement CRUD for invoices"
npx cc-codeconductor cc-goal "Add search with filters"   # alias
npx cc-codeconductor goal "Add user authentication" --output json

将目标与内置模板（auth、crud、搜索、 通知、迁移）或退回到通用的 4 任务链。写到 生成的任务图为 .codeconductor/current-goal.yml 并具有依赖性 订购。编排器使用此文件按依赖顺序委托任务。

ask — 推荐斜杠命令

npx cc-codeconductor ask "login fails on Safari"
npx cc-codeconductor ask "add invoice CRUD" --output json

推荐自然语言问题中的 /cc: 斜杠命令。是否不 启动工作流程；等待人类确认。

ccep — 确定性工作流程合同

npx cc-codeconductor ccep parse --command review "PR #42" --output json
npx cc-codeconductor ccep profile tdd-cycle --output json
npx cc-codeconductor ccep resolve --command feature "Add CRUD" --output json
npx cc-codeconductor ccep compile --command feature --phase intake --role task-coach "Add CRUD" --output json
npx cc-codeconductor ccep compile --command feature --phase intake --view prompt --record-telemetry --execution-id exec-1 --task-id task-1 --context-strategy artifact "Add CRUD" --output json
npx cc-codeconductor ccep validate --command feature --phase implement --role implementer --output json 
  --input @implementer-output.json
npx cc-codeconductor ccep evaluate --command feature --input @planner.json --output json
npx cc-codeconductor ccep consensus --input @verdicts.json
npx cc-codeconductor ccep taskcard --command feature --input @card.json

子命令：parse / profile / resolve / compile / validate / evaluate / consensus / taskcard。 validate 检查代理 JSON 该角色的 Zod 架构。 consensus 退出代码：0 APPROVED、1 REJECTED、 2 ESCALATED。完整协议：docs/CCEP.md。

编译--查看提示符|层数|full 控制返回的表示； full 保留默认值。 --record-telemetry 追加本地编译 大小和时序为 .codeconductor/events.jsonl；不可用的提供商和 代币指标记录为 unknown。 --execution-id、--task-id 和 --context-strategy 在记录遥测时添加相关元数据。

openspec — 积压交付循环

npx cc-codeconductor openspec validate
npx cc-codeconductor openspec scan
npx cc-codeconductor openspec plan BC-001
npx cc-codeconductor openspec analyze --output json
npx cc-codeconductor openspec status
npx cc-codeconductor openspec next
npx cc-codeconductor openspec start BC-001-discover
npx cc-codeconductor openspec done BC-001-discover
npx cc-codeconductor openspec block BC-001-implement --reason "waiting on design"
npx cc-codeconductor openspec unblock BC-001-implement
npx cc-codeconductor openspec archive BC-001
npx cc-codeconductor odd read delivery-001
npx cc-codeconductor odd handoff --id delivery-001 --output json

子命令：validate / scan / plan / analyze / status / next / start / done / block / archive。 analyze 是只读覆盖 （FR/SC → 任务 → 测试）。计划的变更使用能力范围的增量规格； 归档在归档之前将经过验证的增量同步到持久规范中 改变。非法状态转换失败关闭。参见 docs/SDD.md 和 OpenSpec 技能。

odd handoff 从交付分类帐和当前的 工作区状态。它包含任务、范围、证据、更改的路径和下一步 行动；它不会返回账本正文或对话记录。

产品 OS — ingest / product / orchestrate / impact / verify

npx cc-codeconductor ingest
npx cc-codeconductor product graph
npx cc-codeconductor orchestrate status
npx cc-codeconductor impact --files src/cli/router.ts
npx cc-codeconductor verify --task TC-001

在.codeconductor/中构建并查询产品图。详情： docs/product-os.md.

全局选项

配置目录

init 创建 .codeconductor/：

.codeconductor/
├── config.yml          # project settings, target, locale, preset versions
└── presets/
    ├── council.yml     # customizable copy of the council preset
    └── policy.yml      # customizable copy of policy rules

config.yml中的关键字段：

defaults:
  target: opencode     # default runner for install/update
  locale: es           # instruction language injected into agent files

编辑 .codeconductor/presets/council.yml 以添加、删除或重新配置代理 在运行 install 之前。

型号配置

每个预设都包含 src/presets/models/ 中的 YAML 配置文件，该文件 定义每个代理角色使用哪些模型：

src/presets/models/
├── opencode.yml    # model defaults for OpenCode target
├── claude.yml      # model defaults for Claude target
└── codex.yml       # model defaults for Codex target

代理模板文件包含在 install 期间替换的占位符：

要自定义模型，请在运行之前编辑目标的 YAML 文件 install。每个文件将代理角色映射到特定于提供者的模型名称。

指令语言（ --locale ）

代理降价文件（CLAUDE.md、AGENTS.md、README.md）包括 {{LANGUAGE_INSTRUCTIONS}} 占位符，在安装时替换 在活动区域设置上：

区域设置是粘性：使用 init --locale=es 设置一次，并且每个 后续的 install preset 会自动使用它。覆盖每次运行 install preset --locale=en.

# One-time setup
npx cc-codeconductor init --locale=es

# All future installs use Spanish automatically
npx cc-codeconductor install preset --target=claude
npx cc-codeconductor install preset --target=all --global

# Override just this run
npx cc-codeconductor install preset --target=claude --locale=en

# Change the saved locale
npx cc-codeconductor init --locale=en --force

存储库结构

codeconductor/
├── README.md
├── LICENSE
├── CHANGELOG.md
├── ROADMAP.md
├── SECURITY.md
├── policy.yml              ← declarative policy model
│
├── src/                    ← CLI source (TypeScript + Bun)
│   ├── cli/                ← entry point, router, error codes
│   ├── commands/           ← init, detect, install, ccep, openspec, …
│   ├── core/               ← config, detection, filesystem, presets, goal
│   │   ├── ccep/           ← CCEP parse/profile/validate/evaluate
│   │   ├── openspec/       ← backlog loop and state machine
│   │   ├── product/        ← Product OS ingest and console
│   │   ├── context/        ← scoped context injection (Phase 5)
│   │   ├── compaction/     ← TDD history compaction hook (Phase 5)
│   │   ├── messages/       ← concise inter-agent formatter (Phase 5)
│   │   └── loop/           ← compile-fix loop controller (Phase 5)
│   ├── adapters/           ← opencode, claude, codex generators
│   ├── domain/council/     ← council spec, agent, contract
│   ├── domain/loop/        ← loop state machine
│   ├── validation/         ← Zod schemas
│   ├── utils/              ← Result type, logger, invariant
│   └── presets/council/    ← bundled council.yml preset
│
├── test/
│   ├── cli.test.ts         ← integration tests
│   └── fixtures/           ← bun, node, django, spring projects
│
├── docs/
│   ├── architecture.md
│   ├── security-model.md
│   ├── cli-contract.md
│   ├── policy-schema.md
│   ├── routing-policy.md
│   ├── task-card-template.md
│   ├── agent-scorecard.md
│   └── guides/
│
├── presets/                ← runner presets (agents, commands, skills)
│   ├── opencode/
│   ├── claude/
│   └── cursor/
│
└── examples/
    └── spring-boot-kotlin/

路线图

已发布的软件包：1.6.x（当前稳定版：1.6.1）。剩余差距（沙箱、策略编译器、完整的 堆栈特定的资产修剪）：docs/current-status.md。 发布历史：CHANGELOG.md。

有关历史注释，请参阅 ROADMAP.md。