## ADDED Requirements

### Requirement: Complete HTTP API reference documentation
项目 SHALL 提供完整的 HTTP API 参考文档（`docs/agent-api-reference.md`），供任何 Agent 阅读。文档 SHALL 覆盖所有公开端点，包含请求/响应格式、错误码、示例。

#### Scenario: Agent reads API reference to understand available endpoints
- **WHEN** Agent 阅读 `docs/agent-api-reference.md`
- **THEN** 文档 SHALL 列出所有端点：healthz、agents/register、agents/heartbeat、agents/deregister、agents (GET)、tasks (GET)、tasks/{id} (GET)、tasks/dequeue、tasks/{id}/status、tasks/{id}/retry、tasks/{id}/complete、receipts、webhooks/forgejo
- **AND** 每个端点 SHALL 包含：HTTP 方法、URL、请求体格式、响应格式、错误码、curl 示例

#### Scenario: Agent checks authentication requirements
- **WHEN** Agent 查看 API 参考的认证部分
- **THEN** 文档 SHALL 说明：http_pull 模式需要 Bearer token（注册时获取），ssh_cli 模式不需要 Agent 认证，webhook 端点需要 HMAC-SHA256 签名

#### Scenario: Agent understands error responses
- **WHEN** Agent 收到错误响应
- **THEN** 文档 SHALL 列出所有错误码：401 Unauthorized、403 Forbidden、404 Not Found、400 Bad Request、500 Internal Server Error
- **AND** 每个错误码 SHALL 包含触发场景描述

### Requirement: Agent onboarding guide
项目 SHALL 提供 Agent 接入指南（`docs/agent-onboarding-guide.md`），描述两种执行模式的完整工作流程。

#### Scenario: New agent team leader reads onboarding guide
- **WHEN** 新的 Team Leader Agent（如 Jeeves）阅读 onboarding guide
- **THEN** 文档 SHALL 描述两种执行模式的区别和使用场景：
  - ssh_cli：Orchestrator 主动调度，适用于 Codex、Claude Code、OpenCode 等有 CLI 的 Agent
  - http_pull：Agent 自主拉取，适用于 OpenClaw/Jeeves、Hermes 等有自己的调度器的 Agent

#### Scenario: Agent follows ssh_cli workflow
- **WHEN** Agent 按 ssh_cli 模式接入
- **THEN** 文档 SHALL 描述完整流程：配置 host → Agent 安装 CLI → Orchestrator 自动发现 → 任务自动分配和执行 → PR 创建 → webhook 回调

#### Scenario: Agent follows http_pull workflow
- **WHEN** Agent 按 http_pull 模式接入
- **THEN** 文档 SHALL 描述完整流程：调用 register API → 获取 token → 定期 heartbeat → 调用 dequeue 拉任务 → 执行 → 调用 complete/receipt API

#### Scenario: Agent understands Forgejo integration
- **WHEN** Agent 阅读 Forgejo 集成部分
- **THEN** 文档 SHALL 描述：Issue 如何变成任务（webhook → label 解析）、任务如何关联 Git 分支（`task/{task_id}`）、PR 生命周期如何驱动状态更新（opened → review_pending、merged → completed）

#### Scenario: Agent understands structured prompt format
- **WHEN** ssh_cli 模式的 Agent 需要理解传入的 prompt
- **THEN** 文档 SHALL 描述结构化 prompt 的格式：Task ID、Type、Goal、Constraints、Branch、Expected output、Validation