Cortex

AI Task Governance Protocol
纯 Markdown 驱动 · 零依赖 · 所有 AI 编辑器的统一治理层

---

Why Cortex?

AI 编辑器（Copilot、Cursor、Claude Code、Windsurf、Cline…）各有强大的执行引擎，但缺乏统一的治理层——任务无追踪、产出无归档、跨会话无法恢复。

Cortex 不替代任何 AI 编辑器的能力，而是作为放大器，为所有工具提供统一的治理协议：

• 有产出 — 每个阶段强制通过 deliverables-writer 写入 docs/，任务完成即有归档
• 可追踪 — knowledge.db 任务状态 + docs/progress.md 滚动日志，跨会话恢复无损
• 可扩展 — Hook 注入 + cortex-ext/ 用户扩展，用户可在任意阶段接入自定义能力
• 零依赖 — 纯 Markdown 协议，无运行时
• 不侵入 — 用户现有的 rules、instructions、skills、MCP 工具始终有效，Cortex 只加治理层

不是所有交互都需要 Cortex — 简单问答和单步编辑直接回应，只有多步骤任务才启动治理流程。

Quick Start

方式一：npx（推荐）

npx create-cortex

交互式引导，自动检测你使用的 AI 工具，生成对应配置。

非交互模式：

npx create-cortex --tools copilot,cursor,claude --yes

方式二：git submodule

git submodule add https://github.com/<owner>/cortex.git .cortex
bash .cortex/install.sh

方式三：直接下载

从 GitHub Releases 下载最新版，解压到项目根目录的 .cortex/ 下。

验证

打开你的 AI 编码工具，提一个任务。如果 Agent 自动从 .cortex/CORTEX.md 开始读取并遵循启动顺序，说明集成成功。

支持的 AI 工具

安装器支持以下工具——自动检测或通过 --tools 指定：

工具	配置文件	加载方式
GitHub Copilot	.github/copilot-instructions.md	VS Code 自动加载
Cursor	.cursor/rules/cortex.mdc	alwaysApply: true
Claude Code	CLAUDE.md	CLI 启动时自动读取
Windsurf	.windsurfrules	自动加载
Cline	.clinerules/cortex.md	自动加载
Codex / OpenCode	AGENTS.md	自动读取（共享文件，自动去重）
Trae	.trae/rules/cortex.md	alwaysApply: true
CodeBuddy	.codebuddy/rules/cortex.md	自动加载
Roo Code	.roo/rules/cortex.md	自动加载
Aider	CONVENTIONS.md	自动读取
Augment	.augment-guidelines	自动加载

所有配置文件都是轻量指引，引导 AI 工具去读 CORTEX.md 单一入口。

核心概念

启动顺序

CORTEX.md → bootstrap → context → knowledge.db → workflow phase → dispatch(+hooks) → skill → deliverables

1. 读取 CORTEX.md（唯一入口）
2. 读取 protocol/bootstrap/README.md
3. 读取 context/README.md
4. 加载 .cortex/runtime/knowledge.db，查询 active_tasks 恢复任务状态
5. 选择当前 workflow phase，读取 workflow/*.md
6. 通过 protocol/dispatch.md 调度 skill（含 hook 注入）
7. 扫描 skills/*/CORTEX.yaml，扫描 cortex-ext/*/CORTEX.yaml（若存在）
8. 执行阶段动作，完成后通过 runtime-updater subagent 更新 knowledge.db
9. 通过 deliverables-writer skill 写入产出到 docs/
10. 验证不通过时进入 protocol/execution-control.md 定义的 reflow control

Workflow 阶段

阶段	文件	说明
Plan	workflow/01-plan.md	任务分析与拆解
Execute	workflow/02-execute.md	增量执行切片
Verify	workflow/03-verify.md	三态验证（pass / fail / unknown）
Deliver	workflow/04-deliver.md	交付（仅 pass 可进入）

Skill 体系

4 个核心 Skill（protocol 必需）：

Skill	用途
runtime-updater	维护 knowledge.db 任务状态，提供 Python 脚本操作
verify-gate	三态验证（pass / fail / unknown）
reflow-analyzer	分析失败原因，决定回流目标
deliverables-writer	每阶段强制写入产出到 docs/
3 个框架 On-Demand Skill（通过 hook 注入）：

Skill	Hook	用途
clarify-requirement	before-plan	需求澄清
qa-editor	before-plan	QA 编辑
每个 skill 是独立目录，采用 metadata-first 模式：

skills/
└── my-skill/
    ├── CORTEX.yaml      # 元数据（name, kind, stage_affinity, activation_mode）
    ├── SKILL.md          # Controller 协议（命中后才展开）
    ├── prompt.md         # Subagent 指令（可选）
    └── references/       # 参考材料（可选）

用户扩展 Skill 在项目根目录的 cortex-ext/ 中，通过 Hook 系统注入：

# cortex-ext/my-ext/CORTEX.yaml
kind: skill
hook: before-plan          # 注入时机
stage_affinity: [plan]
activation_mode: on-demand

框架目录（.cortex/）保持只读，用户无需修改其中任何文件。

Hook 系统

每个 workflow 阶段提供 before-* 和 after-* 两个注入点：

Hook	时机
before-plan / after-plan	Plan 阶段前后
before-execute / after-execute	Execute 阶段前后
before-verify / after-verify	Verify 阶段前后
before-deliver / after-deliver	Deliver 阶段前后

Dispatch 时自动扫描 skills/*/CORTEX.yaml 和 cortex-ext/*/CORTEX.yaml，匹配 hook 字段后按优先级注入。如果 cortex-ext/ 不存在则跳过。

Task Tracking

任务状态存储于 .cortex/runtime/knowledge.db 的 active_tasks 表，支持跨会话恢复：

存储	用途
active_tasks 表	活跃任务状态追踪（phase、status、slice 等）
decisions 表	用户决策记录
docs/progress.md	人可读进度日志

• 由 runtime-updater subagent 通过 update_knowledge.py 统一维护
• 查询任务状态通过 query_knowledge.py active-tasks

项目结构

cortex/
├── packages/
│   ├── core/                     # npm: cortex-flow（协议内容）
│   │   ├── CORTEX.md             #   唯一入口
│   │   ├── protocol/             #   协议控制面
│   │   ├── workflow/             #   阶段 contract
│   │   ├── skills/               #   能力切片（4 核心 + 3 on-demand）
│   │   └── context/              #   上下文策略与模板
│   └── create-cortex/            # npm: create-cortex（CLI 脚手架）
│       └── src/index.ts          #   交互式安装、工具检测、配置生成
├── install.sh                    # 无 Node.js 时的 bash 备选安装器
├── pnpm-workspace.yaml
└── package.json

用户项目安装后的结构：

my-project/
├── .cortex/                      # Cortex 协议（只读）
│   ├── CORTEX.md
│   ├── protocol/
│   ├── workflow/
│   ├── skills/
│   └── context/
├── cortex-ext/                   # 用户自定义扩展（可选）
│   └── my-skill/
│       ├── CORTEX.yaml
│       └── SKILL.md
├── state/                        # 运行时任务状态
├── docs/                         # 强制产出目录
├── CLAUDE.md                     # ← 由 create-cortex 生成
├── .github/copilot-instructions.md
└── src/                          # 用户项目代码

自定义

添加用户扩展 Skill

在项目根目录的 cortex-ext/ 下创建目录，包含 CORTEX.yaml（声明 kind: skill 和 hook）+ SKILL.md。Dispatch 时会自动扫描并在匹配的 hook 点注入。框架目录保持只读，无需修改。

添加核心 Skill

在 skills/ 下创建目录，包含 CORTEX.yaml + SKILL.md。如需纳入最小闭环，在 CORTEX.md 中注册。

修改 Workflow

编辑 workflow/*.md 中的阶段 contract。保持阶段间依赖关系和 hook 注入点即可。

文档

• 架构说明：docs/cortex/01-harness-architecture.md
• 贡献指南：CONTRIBUTING.md

贡献

欢迎贡献！请先阅读 CONTRIBUTING.md。

许可证

MIT License