<p align="center">
  <img src="docs/assets/pi-ouroboros-logo.png" alt="pi-ouroboros logo" width="160">
</p>

# pi-ouroboros

[English](README.md) | 简体中文

pi-ouroboros 是面向 [pi](https://pi.dev) 的 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 机械检查。 |

## 当前工作区

```text
.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。

示例：

```text
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` | 使用配置的视觉模型做图片分析。 |

## 文档

- [设计](docs/design.md)
- [使用指南](docs/usage.md)
- [测试](docs/testing.md)
- [发布流程](docs/release.md)
- [工作流场景](docs/workflow-scenarios.md)
- [术语表](docs/glossary.md)

## 包与发布

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

## 开发

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

本地 pi session：

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

## 许可证

MIT