pi-ouroboros

English | 简体中文

pi-ouroboros 是面向 pi 的 prompt-first 自主编码工作流：项目理解 + 可恢复工作循环 + 轻量运行时工具。

它不是硬编码任务调度器。主 agent 负责判断怎么工作；扩展只提供当前工作区、项目记忆、子代理、搜索和安全防护等确定性工具。

核心理念

1. 先理解项目：有价值的长期事实进入 PROJECT.md，且只在用户确认后更新。
2. 自主工作循环：理解 -> 计划 -> 执行 -> 验证 -> 决定继续、修复、询问或结束。
3. 集中提问：只为真实决策或阻塞项询问用户，并给出推荐答案。
4. 当前工作区：.ouroboros/ 是当前工作台，不是多任务队列。
5. 薄运行时：没有 runner、任务调度器、逐 run 授权回放或 active-run 指针。

运行时工具

| 工具 | 用途 | |---|---| | oo_start_work | 根据 workflow 和固定 intent stages 初始化当前 .ouroboros/ 工作区；不会覆盖 active/blocked work。 | | oo_status | 查看当前工作和 work.md 恢复摘要。 | | oo_note | 将候选长期项目发现追加到 .ouroboros/memory/discoveries.md。 | | oo_memory | 只读查看 PROJECT 记忆和 discovery ledger 状态。 | | oo_memory_apply | 写入用户确认后的 PROJECT 记忆、changelog 和 discovery 决策。 | | oo_finish_work | 用验证、最终总结和 warning-only 检查结束、放弃或阻塞当前工作。 | | oo_onboard_preflight | onboarding 前只读预检 PROJECT、memory、git 新鲜度和候选文档。 | | oo_config | 读取或创建 .ouroboros/config.json，输出会隐藏 API key。 | | oo_subagent | 运行内置子代理；有当前工作时保存 artifact。 | | oo_search / oo_fetch | 搜索和抓取外部文档。 | | oo_acceptance_check | 收尾前对当前 goal/work 做 warning-only 机械检查。 |

当前工作区

.ouroboros/
|-- goal.md
|-- work.md
|-- memory/
|   |-- PROJECT.md
|   |-- PROJECT.changes.md
|   |-- PROJECT.backup.md
|   |-- brand-spec.md
|   `-- discoveries.md
|-- config.json
|-- archive/
`-- artifacts/
    `-- index.md

memory/ 是长期项目记忆，普通工作清理不会删除它。brand-spec.md 是 ui-design 使用的可选视觉身份记忆。work.md 是主 agent 当前计划和恢复上下文。

开始工作

对于新的用户任务，主 agent 应选择全局 workflow 和固定 intent stages，然后调用 oo_start_work。继续、收尾、状态查看、配置、记忆处理等 lifecycle/runtime 操作用对应内部工具完成，不为了这些操作新建 work。

示例：

oo_start_work({
  title: "analyze current project",
  objective: "Explain the current project structure and key risks.",
  workflow: "simple",
  stages: [{ intent: "understand", summary: "Read relevant docs/code and explain project structure" }],
  successCriteria: ["Explanation is backed by code/doc evidence"],
  routingRationale: ["The user asked for project understanding that benefits from recoverable work context"]
})

如果已经存在 active/blocked work，工具不会覆盖文件。主 agent 应调用 oo_status，然后继续、完成、放弃或阻塞旧工作后再开始新工作。

Slash commands

• /ouroboros-status：显示当前工作状态提示。
• /oo-init：引导新项目初始化（需求、技术选型、项目生成、PROJECT.md）。
• /oo-onboard：提示 agent 执行 onboarding。
• /project-memory：提示 agent 处理当前 discoveries。

内置技能与子代理

• ouroboros：工作流协议与运行时集成。
• web-design-engineer：ui-design 使用的设计协议，用于视觉方向、brand spec 和 UI critique。

| Agent | 角色 | |---|---| | explorer | 只读项目探索。 | | web-researcher | 外部文档和 web 调研。 | | implementer | 实现一个明确的垂直切片并验证。 | | spec-reviewer | 只读检查任务/切片合规性。 | | acceptance-reviewer | 根据 goal、work、diff 和验证证据做验收 review。 | | adversarial-reviewer | 挑战计划、设计和高风险假设。 | | looker | 使用配置的视觉模型做图片分析。 |

文档

• 设计
• 使用指南
• 测试
• 发布流程
• 工作流场景
• 术语表

包与发布

• 发布日志位于 CHANGELOG.md。
• npm 发布流程记录在 docs/release.md。
• GitHub Actions 会在 GitHub Release 标签匹配 v<package version> 时，使用仓库 NPM_TOKEN secret 发布。
• 项目 logo 位于 docs/assets/pi-ouroboros-logo.png。

开发

npm install
npm run verify
npm run pack:dry-run

本地 pi session：

export OUROBOROS_DEV_EXTENSION_PATH="$PWD/index.ts"
pi -e ./index.ts --skill ./skills/ouroboros/SKILL.md --prompt-template ./prompts/implement.md

许可证

MIT