docs: make devops skill plan-first and jj-aware

README.md

@@ -3,7 +3,7 @@
 # gitea-issue-devops-agent
 
 > **Issue-Driven DevOps 产品官网**  
-> 把 `Issue -> Branch -> Preview Slot -> Test Loop -> Human-Confirmed Merge` 变成标准交付引擎。
+> 把 `Issue -> Plan -> Branch -> Draft PR -> Preview Slot -> Test Loop -> Human-Confirmed Merge` 变成标准交付引擎。
 
 ## 公网产品页
 
@@ -14,18 +14,22 @@
 
 ## 核心价值
 
-### 1) 分支隔离提测
+### 1) 计划先行，避免 AI 脑裂
+
+每个 issue 在编码前先生成可持久化 Plan，明确范围、验收、验证路径和 Agent 分工，避免多 Agent 或长流程中的上下文漂移。
+
+### 2) 分支隔离提测
 
 每个 issue 固定独立分支和预览槽位，主干保持稳定回归，避免提测互相覆盖。
 
-### 2) 智能节省资源
+### 3) 智能节省资源
 
 按改动自动识别部署策略：`skip / client_only / server_only / full_stack / infra_only`。  
 **服务端未变更就不重启服务端**。
 
-### 3) 证据化闭环
+### 4) 证据化闭环
 
-提测沉淀 commit、测试链接、环境 URL、验证步骤；最终合并必须工程师人工确认。
+提测沉淀 commit、PR、测试链接、环境 URL、验证步骤；最终合并必须工程师人工确认。
 
 ## 一键安装
 
@@ -90,7 +94,8 @@ python skills/gitea-issue-devops-agent/scripts/preview_slot_allocator.py --state
 - `repo_url`
 - `api_key`（Gitea token，需 issue 读写权限）
 - `mode`（`automatic` / `semi-automatic` / `manual`）
-- 可选：`reviewers`、`test_entry`、`deploy_env`、`health_endpoint`、`min_quality_score`
+- `issue` 或固定 issue 触发来源
+- 可选：`target_base`、`plan_path`、`reviewers`、`test_entry`、`deploy_env`、`health_endpoint`、`min_quality_score`、`jj_policy`
 
 ### Claude Code
 
@@ -132,6 +137,7 @@ $gitea-issue-devops-agent
 repo_url: https://fun-md.com/FunMD/document-collab
 api_key: <TOKEN>
 mode: automatic
+issue: 48
 ```
 
 ### OpenCode
@@ -167,12 +173,14 @@ mode=manual
 | `repo_url` | 目标仓库完整地址。优先使用完整 URL。 | `https://fun-md.com/Fun_MD/devops-skills` | 常规接入，避免 `base_url + owner/repo` 组合歧义 |
 | `api_key` | Gitea token，至少具备 issue 读写权限。 | `gta_xxx` | 需要读取 issue、评论、附件并回写提测证据 |
 | `mode` | 执行模式：`automatic` / `semi-automatic` / `manual`。 | `automatic` | 决定自动化程度和人工审批点 |
+| `issue` | 固定 issue 编号或触发来源。 | `48` | 将一次交付限定在一个可控 issue 上 |
 
 ### 重要可选参数
 
 | 参数 | 说明 | 典型值 | 使用场景 |
 | --- | --- | --- | --- |
 | `reviewers` | 指定评审人列表（逗号分隔）。 | `alice,bob` | `semi-automatic` 模式下提交后等待人工评审 |
+| `plan_path` | Plan 持久化路径。 | `.tmp/devops-plans/devops-skills__issue-48.md` | MajorAgent/SubAgent/TestAgent 共享状态 |
 | `test_entry` | 分支提测入口（CI 命令或 job 名）。 | `gitea workflow run issue-branch-preview` | 多条流水线并存时明确提测入口 |
 | `main_env_url` | 主干稳定环境 URL。 | `https://main.qa.example.com` | 回归对比、基线验证 |
 | `shared_qa_url` | 共享 QA 环境 URL（可选）。 | `https://qa.example.com` | 需要跨分支集成验证 |
@@ -183,6 +191,7 @@ mode=manual
 | `min_quality_score` | issue 最低质量分（默认 70）。 | `70` | 低质量 issue 先补充信息再进入开发 |
 | `skip_asset_endpoints` | 跳过 `/issues/*/assets` 端点抓图。 | `true` | 自建 Gitea 禁用了 assets API 时兜底 |
 | `target_base` | 变更比较基线分支。 | `origin/main` | 用于 `change_scope` 判断部署范围 |
+| `jj_policy` | `jj` 使用策略：`disabled` / `optional-internal` / `required-internal`。 | `optional-internal` | 仅作为内部执行与恢复层，不改变外部 Git/PR 流程 |
 
 ### 参数组合示例（按场景）
 
@@ -193,6 +202,8 @@ mode=manual
 repo_url=https://fun-md.com/Fun_MD/devops-skills \
 api_key=<TOKEN> \
 mode=automatic \
+issue=48 \
+plan_path=.tmp/devops-plans/devops-skills__issue-48.md \
 test_entry="issue-branch-preview" \
 main_env_url=https://main.qa.example.com \
 preview_slots=preview-a,preview-b \
@@ -209,6 +220,7 @@ $gitea-issue-devops-agent
 repo_url: https://fun-md.com/Fun_MD/devops-skills
 api_key: <TOKEN>
 mode: manual
+issue: 48
 deploy_env: prod-like-staging
 health_endpoint: /healthz
 ```
@@ -222,6 +234,7 @@ Use skill gitea-issue-devops-agent.
 repo_url=https://fun-md.com/Fun_MD/devops-skills
 api_key=<TOKEN>
 mode=semi-automatic
+issue=48
 reviewers=alice,bob
 test_entry=issue-branch-preview
 shared_qa_url=https://qa.example.com