feat(agent): update pnpm agent workflow

AGENTS.md

@@ -79,11 +79,50 @@ AI 继续任务
 
 ```bash
 pnpm agent                    # 获取项目知识和当前任务
-pnpm agent --chapter 00-必读  # 查看必读章节
+pnpm agent roadmap current    # 查看当前 Roadmap
+pnpm agent chapter 00-必读     # 查看必读章节
 ```
 
 详细的项目信息、技术栈、开发流程请查阅白皮书。
 
+---
+
+## 开发闭环（必须遵循）
+
+```bash
+# 1) 获取索引 + Roadmap
+pnpm agent
+pnpm agent roadmap current
+
+# 2) 领取任务（Issue）
+pnpm agent claim <issue#>
+
+# 3) 创建 worktree（严格校验分支前缀与 .env.local）
+pnpm agent worktree create issue-<id> --branch feat/issue-<id> --base main
+cd .git-worktree/issue-<id>
+
+# 4) 阅读白皮书（先文档后编码）
+pnpm agent toc
+pnpm agent chapter <路径>
+
+# 5) 开发 + 测试
+pnpm dev
+pnpm test
+pnpm typecheck
+
+# 6) 提交 + 推送 + PR
+git add -A
+git commit -m "feat/fix: 描述"
+git push -u origin <branch>
+gh pr create --title "标题" --body "Closes #<issue#>" --base main
+
+# 7) 合并 + 清理
+gh pr merge --squash --delete-branch
+pnpm agent worktree delete issue-<id>
+```
+
+> 白皮书是唯一权威来源：若用户补充/纠正知识，必须先更新 `docs/white-book/` 再继续开发。
+
 <!-- OPENSPEC:START -->
 
 # OpenSpec Instructions

CLAUDE.md

@@ -7,10 +7,10 @@
 pnpm agent
 
 # 2. 查看当前任务
-pnpm agent --roadmap current
+pnpm agent roadmap current
 
 # 3. 查阅白皮书必读章节
-pnpm agent --chapter 00-必读
+pnpm agent chapter 00-必读
 ```
 
 完整工作流和命令速查见 [AGENTS.md](./AGENTS.md)
@@ -69,8 +69,8 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 所有编码工作必须在 `.git-worktree/` 目录下进行：
 
 ```bash
-git worktree add .git-worktree/issue-28 -b feat/issue-28
-cd .git-worktree/issue-28 && pnpm install
+pnpm agent worktree create issue-28 --branch feat/issue-28
+cd .git-worktree/issue-28
 # 开发...
 gh pr create --body "Closes #28"
 ```

docs/white-book/附录/H-开发规范/index.md

@@ -14,11 +14,10 @@
 
 ```bash
 # 1. 创建 worktree
-git worktree add .git-worktree/<feature-name> -b <branch-name>
+pnpm agent worktree create <feature-name> --branch <branch-name> --base main
 
 # 2. 进入 worktree 开发
 cd .git-worktree/<feature-name>
-pnpm install
 
 # 3. 开发完成后提交
 git add -A
@@ -36,9 +35,13 @@ cd ../..
 git pull origin main
 
 # 7. 清理 worktree
-git worktree remove .git-worktree/<feature-name>
+pnpm agent worktree delete <feature-name>
 ```
 
+> 注意：`pnpm agent worktree create` 会在仓库根目录查找 `.env.local`，缺失则直接报错并停止。
+> `pnpm agent worktree delete` 会通过 `gh` 校验 PR 合并状态，未合并需要显式 `--force`。
+> 分支命名必须以 `feat/`、`fix/`、`docs/`、`test/`、`refactor/`、`chore/`、`ci/`、`openspec/` 或 `release/` 开头。
+
 ### 为什么用 Worktree
 
 - 隔离开发环境，避免分支切换污染
@@ -76,9 +79,10 @@ Closes #28
 
 ```bash
 pnpm agent                    # 项目知识 + 当前任务
-pnpm agent --claim 28         # 领取任务
-pnpm agent --chapter <路径>   # 查阅白皮书
-pnpm agent --stats            # 进度统计
+pnpm agent claim 28           # 领取任务
+pnpm agent chapter <路径>     # 查阅白皮书
+pnpm agent stats              # 进度统计
+pnpm agent worktree list      # 查看 worktree 状态
 
 pnpm dev                      # 启动开发服务器
 pnpm test                     # 运行单元测试

openspec/changes/update-agent-cli/proposal.md

@@ -0,0 +1,15 @@
+# Change: Update agent CLI subcommands and worktree workflow
+
+## Why
+当前 `pnpm agent` 仍以 flag 方式组织功能，命令结构可读性和可扩展性不足，同时缺少统一的 worktree 管理入口。
+
+## What Changes
+- 将 `pnpm agent` 主要功能调整为子命令形式（roadmap/claim/done/create/stats/toc/chapter/epic/worktree）。
+- 新增 `pnpm agent worktree` 子命令，支持 create/delete/list，并联动依赖安装与 `.env.local` 同步。
+- worktree list 输出包含 PR 编号、状态与 CI/CD 检查概况；create 缺失 `.env.local` 时直接失败。
+- worktree create 对分支前缀进行严格校验，避免不符合规范的命名。
+- 更新 AGENTS.md 与白皮书中与 agent/worktree 相关的工作流指引。
+
+## Impact
+- Affected specs: agent-cli (new)
+- Affected code: scripts/agent/cli.ts, scripts/agent/readme.ts, scripts/agent/roadmap.ts, scripts/agent/whitebook.ts (usage text), AGENTS.md, docs/white-book/附录/H-开发规范/index.md

openspec/changes/update-agent-cli/specs/agent-cli/spec.md

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: Agent CLI subcommands
+`pnpm agent` SHALL expose primary functions as subcommands (roadmap/claim/done/create/stats/toc/chapter/epic/worktree) and provide usage help when requested.
+
+#### Scenario: Default usage
+- **WHEN** the user runs `pnpm agent` without arguments
+- **THEN** the CLI prints the agent index内容
+
+#### Scenario: Help usage
+- **WHEN** the user runs `pnpm agent --help` or `pnpm agent help`
+- **THEN** the CLI prints subcommand usage说明
+
+### Requirement: Worktree create workflow
+`pnpm agent worktree create` SHALL create a new worktree under `.git-worktree/`, install dependencies, and copy `.env.local` from the repository root. The command MUST require `--branch` and print a detailed summary on success.
+
+#### Scenario: Create worktree
+- **WHEN** the user runs `pnpm agent worktree create issue-28 --branch feat/issue-28`
+- **THEN** the worktree directory is created, dependencies are installed, and `.env.local` is copied into the new worktree
+
+#### Scenario: Missing branch flag
+- **WHEN** the user omits `--branch`
+- **THEN** the command fails with an explicit error and does not proceed
+
+#### Scenario: Missing env file
+- **WHEN** `.env.local` does not exist in the repository root
+- **THEN** the command fails with an explicit error and does not proceed
+
+#### Scenario: Create summary
+- **WHEN** worktree creation succeeds
+- **THEN** the output includes worktree path, branch name, base reference, install result, env copy result, and next-step guidance
+
+### Requirement: Worktree branch naming validation
+`pnpm agent worktree create` SHALL reject branch names that do not start with an approved prefix (feat/, fix/, docs/, test/, refactor/, chore/, ci/, openspec/, release/).
+
+#### Scenario: Invalid branch prefix
+- **WHEN** the user provides a branch without an approved prefix
+- **THEN** the command fails with an explicit error and does not proceed
+
+### Requirement: Worktree delete safety
+`pnpm agent worktree delete` SHALL verify whether the associated branch has an open or unmerged PR via `gh` and refuse deletion unless `--force` is provided.
+
+#### Scenario: Delete with open PR
+- **WHEN** a worktree’s branch has an open PR and the user runs delete without `--force`
+- **THEN** the command stops with a warning and does not remove the worktree
+
+#### Scenario: Forced delete
+- **WHEN** the user runs delete with `--force`
+- **THEN** the worktree is removed regardless of PR status
+
+### Requirement: Worktree list visibility
+`pnpm agent worktree list` SHALL enumerate worktrees under `.git-worktree` and display their branch, PR number, PR status, and CI/CD check status.
+
+#### Scenario: List worktrees
+- **WHEN** the user runs `pnpm agent worktree list`
+- **THEN** the output includes each worktree path with branch name, PR number, PR status, and CI/CD check information

openspec/changes/update-agent-cli/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [x] 1.1 更新白皮书与 AGENTS.md 的 agent/worktree 指引为子命令格式
+- [x] 1.2 将 `pnpm agent` CLI 迁移为子命令解析结构
+- [x] 1.3 新增 `worktree` 子命令模块（create/delete/list）
+- [x] 1.4 更新 agent 输出文案与关联提示（readme/roadmap 等）
+- [x] 1.5 验证：运行 `pnpm agent help` 与 worktree 子命令基础流程