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

skills/gitea-issue-devops-agent/SKILL.md

@@ -1,10 +1,25 @@
 ---
 name: gitea-issue-devops-agent
-description: End-to-end Gitea issue delivery workflow with guided onboarding, branch-scoped preview environments, and resource-aware deployment decisions. Use when tasks involve connecting to Gitea, processing text/image issues, fixing code on issue-specified branches, allocating/reusing test environments per branch, running test submission loops, coordinating review approvals, and closing issues only after verified delivery and engineer-confirmed merge.
+description: Use when coordinating AI-assisted Gitea issue delivery where work must stay traceable across issue selection, branch or PR flow, CI/CD, preview environments, and human merge approval.
 ---
 
 # Gitea Issue DevOps Agent
 
+## Overview
+
+Treat AI as a fast but unstable engineer. The public workflow must remain `issue -> branch -> PR -> CI/CD -> human-confirmed merge`, while the internal execution model must narrow context, persist plans, require verification evidence, and keep humans in control of final merge decisions.
+
+This skill is platform-aware for Gitea, but its delivery contract must stay portable across basic DevOps primitives: `git`, `issue`, `PR`, and `CI/CD`.
+
+## Core Principles
+
+- Start coding only from a selected issue, not from an unbounded issue queue, unless the user explicitly asks for triage-only queue scanning.
+- Every delivery issue must have a persisted plan before any code changes.
+- External collaboration stays Git-native: issue, branch, PR, pipeline, review app, merge.
+- AI output is provisional until tests, smoke paths, and review evidence exist.
+- Engineers stay in the loop from the initial PR onward and own white-box review.
+- Keep one active issue per branch and per execution agent unless the user explicitly approves batching.
+
 ## Mandatory Guided Start
 
 Run this interaction before any coding or issue action:
@@ -17,7 +32,16 @@ Run this interaction before any coding or issue action:
    - `automatic`
    - `semi-automatic`
    - `manual` (non-automatic)
-4. Ask optional defaults:
+4. Ask for the selected issue trigger source:
+   - explicit issue number
+   - issue comment / webhook trigger
+   - app/CLI selection
+   - triage-only queue scan without coding
+5. Ask optional defaults:
+   - target base branch (for example `main`, `develop`, protected release branch)
+   - branch naming convention for issue branches
+   - plan storage path (default `.tmp/devops-plans/<repo>__issue-<number>.md`)
+   - issue template policy (`required` or `recommended`) for `bug`, `enhancement`, and `feature`
    - designated reviewers (for semi-automatic mode)
    - branch test submission entrypoint (CI command/job)
    - environment policy:
@@ -29,19 +53,98 @@ Run this interaction before any coding or issue action:
      - websocket public entry: explicit WS URL (`wss://...`) or same-origin path (`/ws`)
    - deployment environment + health endpoint
    - minimum issue quality score (default `70`)
-5. Validate connectivity by running:
+   - `jj` policy:
+     - `disabled`
+     - `optional-internal`
+     - `required-internal`
+6. Validate connectivity by running:
    - `python scripts/issue_audit.py --repo <owner/repo> --base-url <gitea_url> --token <token> --state all --download-attachments --output-dir .tmp/issue-audit`
-6. Initialize preview-slot state (if branch previews enabled):
+7. Initialize preview-slot state (if branch previews enabled):
    - `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots <slot_csv> --list`
-7. Echo back the selected mode and all gate rules, then start work.
+8. Echo back the selected mode, selected issue trigger, target base branch, plan path, `jj` policy, and all gate rules, then start work.
 
 If repository or token is missing/invalid, stop and request correction. Never start development without a successful connectivity check.
 
+## Issue Intake Contract (Required)
+
+- Require issue templates for `bug`, `enhancement`, and `feature`. See `references/issue-template-standard.md`.
+- A coding run must start from one fixed issue chosen by a human or an explicit trigger. Queue polling is for triage only unless the user explicitly enables unattended processing.
+- If the selected issue is too broad for one reviewable PR, split it into sub-issues before coding.
+- If issue quality is below threshold, request details and stop before branch creation.
+- For image/UI issues, attachment intake is mandatory before implementation.
+
+## Plan-First Orchestration (Required)
+
+Before any code change, the MajorAgent must create and persist a plan for the selected issue. Use `references/plan-template.md`.
+
+Minimum plan fields:
+
+- issue number and title
+- trigger source and current issue status
+- target base branch and working branch
+- current problem description
+- expected behavior and acceptance criteria
+- related interfaces, services, and directories
+- allowed file/path scope for edits
+- verification steps, including issue-level e2e coverage
+- assigned execution agent
+- risk notes and blockers
+- evidence links or placeholders for commit, PR, pipeline, and preview URL
+
+Required status flow:
+
+- `selected`
+- `planned`
+- `in_progress`
+- `pending_test`
+- `pending_review`
+- `merged`
+- `closed`
+- `needs_info`
+- `blocked`
+- `rejected`
+
+Hard rules:
+
+- No code changes before the plan exists.
+- No status promotion without evidence.
+- If scope changes materially, update the plan before continuing.
+
+## Agent Role Separation (Required)
+
+### MajorAgent
+
+- Pull issues, comments, and attachments from Gitea.
+- Perform semantic triage and create the plan.
+- Select or create the issue branch and initialize the PR.
+- Decide whether work can proceed automatically or must pause for human input.
+
+### SubAgent (Developer)
+
+- Load only the plan and the minimal code context needed for the issue.
+- Modify code only within the allowed path scope unless explicit approval expands scope.
+- Keep patches small and reversible.
+- Update the plan to `pending_test` with a concise implementation summary.
+
+### TestAgent
+
+- Load the plan, diff, and verification steps.
+- Validate build, targeted tests, issue-level e2e path, and smoke path.
+- Update the plan to `pending_review` only when evidence is complete.
+- Reopen the plan to `in_progress` if failures or regressions appear.
+
+### Human Reviewer / Maintainer
+
+- Review the draft PR and the plan evidence.
+- Use the AI coding tool for follow-up adjustments if needed.
+- Approve or reject final merge.
+
 ## Mode Definitions
 
 ### 1) Automatic Mode
 
-- Read issue-specified branch and work on that branch.
+- Start only after a fixed issue has been selected and a plan has been created.
+- Read or create the issue branch and open/update the draft PR automatically.
 - Implement fix, run checks, push branch, allocate/reuse branch preview env, and trigger branch test submission automatically.
 - Monitor test results and issue feedback, then iterate on the same branch until pass.
 - Close issue only after evidence is complete.
@@ -49,7 +152,8 @@ If repository or token is missing/invalid, stop and request correction. Never st
 
 ### 2) Semi-Automatic Mode
 
-- Read issue-specified branch and work on that branch.
+- Start only after a fixed issue has been selected and a plan has been created.
+- Read or create the issue branch and open/update the draft PR.
 - Implement and push fix.
 - Notify designated reviewer with change summary, risk, and test plan.
 - Wait for explicit human review approval.
@@ -62,7 +166,9 @@ If repository or token is missing/invalid, stop and request correction. Never st
 Require explicit human confirmation before each major action:
 
 - selecting issue
+- finalizing the plan
 - confirming target branch
+- creating or updating the PR
 - applying code changes
 - pushing commits
 - triggering tests/deploy
@@ -73,11 +179,15 @@ No autonomous transition is allowed in manual mode.
 
 ## Branch-First Rules
 
-- Treat issue-declared branch as the source of truth.
+- Treat issue-declared branch as the source of truth when provided.
+- If the issue does not declare a branch, create one from the configured protected base branch after the plan is approved.
+- Preferred naming pattern: `<type>/issue-<number>-<slug>` or `issue/<number>-<slug>`.
 - Accept branch hints from issue fields/body/comments (example: `branch: feat/login-fix`).
 - If branch is missing or ambiguous, ask user/reporter and pause that issue.
 - Do not silently switch branches.
 - Keep one active issue per branch unless user explicitly approves batching.
+- Open or update a draft PR immediately after branch selection so the review surface exists from the start.
+- Keep issue, branch, PR, preview env, and plan bound together for the full lifecycle.
 
 ## Environment Model (Required)
 
@@ -142,9 +252,14 @@ Hard rule:
 
 ## Standard Workflow (All Modes)
 
-### 1) Intake and Prioritization
+### 1) Issue Selection and Trigger
 
-- Pull issues, comments, and attachments from Gitea API.
+- Start from a fixed issue chosen through comment mention, webhook, app/CLI selection, or explicit human instruction.
+- Repo-wide polling may be used for triage reports, but not for autonomous coding unless the user explicitly enables queue processing.
+
+### 2) Intake and Prioritization
+
+- Pull the selected issue, comments, and attachments from Gitea API.
 - If issue text/comments indicate image evidence but `attachments_downloaded` is `0`, stop and report image-intake failure before coding.
 - Prioritize in this order:
   - `closed_but_unresolved`
@@ -153,30 +268,48 @@ Hard rule:
   - `closed_open_reopen_candidates`
 - For issues with images, inspect attachments before coding.
 
-### 2) Deduplication and Quality Gate
+### 3) Deduplication and Quality Gate
 
 - Group issues by semantic intent, not literal wording.
 - Keep one parent issue for implementation.
 - Use `references/triage-standard.md` for score and comment templates.
 - For low-quality issues, request details and mark as `needs-info`.
 
-### 3) Fix Execution
+### 4) Plan Generation
+
+- MajorAgent must generate a plan before branch creation or code changes.
+- Persist the plan to the configured plan path and echo the summary back to the user.
+- Record the allowed file/path scope so later diffs can be checked against it.
+- Record the issue-level e2e scenario from the reporter's perspective.
+
+### 5) Branch and PR Initialization
+
+- Create or reuse the issue branch from the configured base branch.
+- Create or update the associated draft PR targeting the protected integration branch.
+- The PR body must include issue link, plan summary, intended file scope, and verification checklist.
+
+### 6) Fix Execution
 
 - Prefer small, reversible patches.
 - Link every code change to issue ID in commit or PR/MR notes.
 - Split cross-cutting work into incremental commits.
+- Do not modify files outside the allowed plan scope without explicit approval and a plan update.
+- Any new dependency, framework, SDK, or major library change must be checked against official docs, maintenance status, and local compatibility before merge.
+- Do not trust knowledge-base output as truth unless it has clear provenance and matches the current codebase.
 
-### 4) Verification Gate
+### 7) Verification Gate
 
 - Required:
   - build/compile passes
   - affected unit/integration tests pass
+  - issue-level e2e test is added or updated and passes in the PR pipeline unless the user explicitly waives it
   - smoke path for reported scenario passes
 - For UI/image issues:
   - compare before/after screenshots
   - verify in at least one Chromium browser
+- If verification evidence is missing, do not claim the issue is fixed.
 
-### 5) Branch Test Submission ("提测")
+### 8) Branch Test Submission ("提测")
 
 - Submit testing on the issue branch (CI pipeline + branch preview env).
 - Allocate/reuse branch slot before submission.
@@ -184,35 +317,44 @@ Hard rule:
 - Verify websocket handshake is healthy on the published preview URL/path before asking QA to test.
 - Post evidence in issue comment:
   - commit SHA
+  - PR URL
   - test run URL and result
   - environment/slot/URL
   - deployment scope (`skip`/`client_only`/`server_only`/`full_stack`/`infra_only`)
   - shared backend reused or dedicated backend started
+  - e2e result
   - verification steps
 - If fail/reject, iterate on same branch and re-submit.
 
-### 6) Loop Control
+### 9) Loop Control
 
 - Continue `fix -> test submission -> feedback -> fix` until done.
 - Reopen immediately if verification fails or regression appears.
 - Do not close based on title-only or assumption-only validation.
 
-### 7) Closure Rule
+### 10) Human Review and AI-Assisted Refinement
+
+- From the initial PR onward, engineering review is the default path.
+- Engineers may continue refinement inside an AI coding tool, but all follow-up work must stay on the same issue branch and update the same plan.
+- Human review is the white-box gate between initial AI output and final merge readiness.
+
+### 11) Closure Rule
 
 Close issue only when all are true:
 
 - root cause identified
 - fix verified with reproducible evidence
 - test submission passed
+- PR review state is recorded
 - closure comment includes commit/test/deploy evidence
 
-### 8) Merge Rule (Always Human-Confirmed)
+### 12) Merge Rule (Always Human-Confirmed)
 
 - Final merge must be approved by an engineer in all modes.
 - Agent can prepare merge notes/checklist, but must wait for explicit merge confirmation.
 - Merge only after confirmation, then post final release evidence.
 
-### 9) Environment Cleanup
+### 13) Environment Cleanup
 
 - On issue close/merge:
   - release preview slot
@@ -221,6 +363,42 @@ Close issue only when all are true:
 - On TTL expiry:
   - reclaim idle slot automatically (automatic mode) or after confirmation (semi/manual)
 
+## AI Reliability Guardrails
+
+- Evidence before assertions: never claim “fixed”, “tested”, or “deployed” without command output, screenshots, or links proving it.
+- Diff-scope gate: compare the actual diff with the plan's allowed paths before PR update or merge request.
+- Dependency gate: do not add new packages or major version upgrades without checking official documentation, maintenance state, and environment compatibility.
+- Deprecated-tech gate: do not introduce deprecated or no-longer-recommended libraries/classes unless the user explicitly approves the trade-off.
+- Context minimization: every execution agent should load the issue, plan, diff, and only the code areas it needs.
+- No silent batching: do not mix unrelated fixes into one issue branch or PR.
+
+## Knowledge Context Policy
+
+- Do not blindly vectorize or load the entire repository as context for each issue.
+- Build a curated issue context pack consisting of:
+  - issue body and comments
+  - plan summary
+  - touched directories and interfaces
+  - related tests
+  - relevant configuration and prior PR/commit references
+- Record the chosen context sources in the plan so later agents can reuse them.
+- Treat knowledge-base retrieval as a hint layer, not as a source of truth.
+
+## Jujutsu (`jj`) Integration Strategy (Optional but Recommended Internally)
+
+`jj` should improve internal execution reliability, not replace the external Git workflow.
+
+Use `jj` only under these rules:
+
+- Keep Git branches, PRs, and CI/CD as the public system of record.
+- Map the issue branch to a `jj` bookmark when `jj` is enabled.
+- Use `jj` change IDs to support iterative rewrites without losing traceability.
+- Use `jj` workspaces for parallel SubAgent/TestAgent/human adjustments on the same issue without sharing one mutable working copy.
+- Use the `jj` operation log for undo, recovery, and audit when AI changes diverge or go out of scope.
+- Prefer `jj` for local mutating history operations if enabled; avoid mixing arbitrary mutating `git` commands with `jj` in the same workspace.
+- If colocated workspaces are used, keep `git` mostly read-only except for explicit remote operations such as fetch/push handled by the workflow.
+- Do not require `jj` in CI or for non-engineer participants. `jj` is an internal accelerator, not the product front door.
+
 ## Script Usage
 
 - `scripts/issue_audit.py`: collect issues/comments/attachments, detect duplicates, score quality, detect unresolved/closed-open links, extract issue branch hints, and generate reports.
@@ -234,9 +412,16 @@ Close issue only when all are true:
 - `scripts/change_scope.py`: detect changed scope and recommend minimum deploy strategy.
   - `python scripts/change_scope.py --repo-path <repo> --base-ref origin/main --head-ref HEAD`
 - `references/triage-standard.md`: scoring rubric and templates for needs-info, review request, test submission, and merge approval.
+- `references/issue-template-standard.md`: standard issue templates for `bug`, `enhancement`, and `feature`.
+- `references/plan-template.md`: default plan structure and status machine for MajorAgent/SubAgent/TestAgent handoff.
 
 ## Operational Constraints
 
+- Never start coding from an unselected issue unless the user explicitly enables autonomous queue mode.
+- Never skip plan creation for a delivery issue.
+- Never modify files outside the planned scope without an explicit plan update or user approval.
+- Never claim success without verification evidence.
+- Never introduce new dependencies or deprecated libraries without compatibility review.
 - Never bulk-close issues without per-issue verification evidence.
 - Never ignore attachment images for UI/interaction issues.
 - Never merge feature requests and bugfixes into one untraceable commit.

skills/gitea-issue-devops-agent/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Gitea Issue DevOps Agent"
-  short_description: "Guided Gitea issue delivery with execution modes, branch preview slots, and resource-aware deployments"
+  short_description: "Plan-first Gitea issue delivery with fixed-issue triggers, draft PRs, preview slots, evidence gates, and optional jj-backed execution"
-  default_prompt: "Start with guided setup (repo URL, API key, mode, env policy), process issues on issue-specified branches, bind each branch to preview slots, decide deploy scope from git diff (skip/client-only/server-only/full-stack), avoid dedicated server restarts when backend is unchanged, run fix/test loops, and require engineer confirmation before final merge."
+  default_prompt: "Start with guided setup (repo URL, API key, mode, selected issue trigger, target base branch, plan path, env policy, jj policy). Require a persisted plan before code changes, create or reuse the issue branch and draft PR, restrict edits to plan-scoped paths, decide deploy scope from git diff (skip/client-only/server-only/full-stack), add or update issue-level e2e coverage, bind preview slots, avoid dedicated server restarts when backend is unchanged, keep engineers in the loop from the initial PR onward, and require evidence plus explicit engineer confirmation before final merge."

skills/gitea-issue-devops-agent/references/issue-template-standard.md

@@ -0,0 +1,143 @@
+# Issue Template Standard
+
+Use these templates to create AI-ready issues. The goal is to give both humans and agents enough context to produce a reviewable first PR instead of an ambiguous code dump.
+
+## Global Rules
+
+- Every issue should map to one reviewable outcome.
+- Prefer explicit issue selection to start delivery:
+  - issue comment mention or webhook trigger
+  - app/UI selection
+  - CLI selection
+- Queue scans may suggest issues, but should not start coding until one issue is explicitly selected.
+- Always include acceptance criteria and affected area hints.
+- If screenshots, recordings, or logs exist, attach them in the issue instead of describing them vaguely.
+
+## Common Required Fields
+
+- summary
+- issue type: `bug`, `enhancement`, or `feature`
+- current behavior
+- expected behavior
+- affected user or business impact
+- related pages/modules/interfaces
+- acceptance criteria
+- attachments or logs
+
+## Bug Template
+
+```text
+[bug-template-v1]
+Summary:
+
+Environment:
+- app version:
+- browser/device/os:
+- time window:
+
+Current behavior:
+
+Expected behavior:
+
+Reproduction steps:
+1.
+2.
+3.
+
+Affected area:
+- pages/routes:
+- services/apis:
+- files or modules if known:
+
+Impact:
+
+Evidence:
+- screenshot/video/log links:
+
+Acceptance criteria:
+- [ ]
+- [ ]
+
+Non-goals:
+```
+
+## Enhancement Template
+
+```text
+[enhancement-template-v1]
+Summary:
+
+Background:
+
+Current limitation:
+
+Desired improvement:
+
+Affected area:
+- pages/routes:
+- services/apis:
+- files or modules if known:
+
+User value:
+
+Constraints:
+- compatibility:
+- performance:
+- rollout/risk:
+
+Acceptance criteria:
+- [ ]
+- [ ]
+
+Evidence or references:
+```
+
+## Feature Template
+
+```text
+[feature-template-v1]
+Summary:
+
+Business goal:
+
+User story:
+As a <role>, I want <capability>, so that <outcome>.
+
+Scope:
+- in scope:
+- out of scope:
+
+Expected behavior:
+
+Affected area:
+- pages/routes:
+- services/apis:
+- files or modules if known:
+
+Dependencies or prerequisites:
+
+Acceptance criteria:
+- [ ]
+- [ ]
+- [ ]
+
+Validation path:
+- happy path:
+- edge cases:
+
+Evidence, mockups, or references:
+```
+
+## Selection Trigger Examples
+
+```text
+@funmd-bot take issue #123
+```
+
+```text
+CLI: devops-agent run --issue 123 --mode semi-automatic
+```
+
+```text
+UI: Select issue #123 -> Generate plan -> Create branch and draft PR
+```

skills/gitea-issue-devops-agent/references/plan-template.md

@@ -0,0 +1,98 @@
+# Plan Template
+
+Every delivery issue must have a persisted plan before code changes. Store it in a stable path such as:
+
+```text
+.tmp/devops-plans/<repo>__issue-<number>.md
+```
+
+## Plan Template
+
+```text
+[issue-plan-v1]
+Issue:
+- repo:
+- number:
+- title:
+- type:
+- trigger source:
+
+Status:
+- current: selected
+- owner agent:
+- reviewer:
+
+Branching:
+- target base branch:
+- working branch:
+- PR:
+
+Problem:
+
+Expected behavior:
+
+Acceptance criteria:
+- [ ]
+- [ ]
+
+Related scope:
+- interfaces/apis:
+- directories/files:
+- tests:
+
+Allowed path scope:
+- path/glob 1
+- path/glob 2
+
+Curated context pack:
+- issue body/comments
+- attachments
+- code references
+- prior PRs/commits/docs
+
+Implementation notes:
+
+Verification plan:
+- build/compile:
+- unit/integration:
+- e2e:
+- smoke path:
+- screenshot/browser checks:
+
+Evidence:
+- commit:
+- pipeline:
+- preview url:
+- screenshots:
+
+Risk and blockers:
+
+Handoff notes:
+```
+
+## Required Status Flow
+
+- `selected`
+- `planned`
+- `in_progress`
+- `pending_test`
+- `pending_review`
+- `merged`
+- `closed`
+- `needs_info`
+- `blocked`
+- `rejected`
+
+## Ownership Rules
+
+- MajorAgent creates and updates the plan before coding starts.
+- SubAgent reads only the plan plus minimal code context and updates implementation notes.
+- TestAgent updates verification results and may move the status back to `in_progress`.
+- Human reviewer confirms `pending_review` to merge readiness.
+
+## Scope Rules
+
+- If the diff touches files outside the allowed path scope, stop and either:
+  - update the plan with justification, or
+  - request human approval.
+- If a new dependency or deprecated technology is introduced, record the compatibility decision in `Risk and blockers`.

skills/gitea-issue-devops-agent/references/triage-standard.md

@@ -53,10 +53,29 @@ Use this at session start before any implementation:
    - automatic：自动修复+提测循环，最终合并仍需工程师确认
    - semi-automatic：修复后先人工 review，再提测循环
    - manual：全流程人工确认
-可选：指定 reviewer、提测命令、部署环境、健康检查地址。
+4) 固定 issue 触发来源（issue 编号 / 评论触发 / app/CLI 选择 / 仅扫描不编码）
+可选：目标基线分支、分支命名规则、Plan 存储路径、指定 reviewer、提测命令、部署环境、健康检查地址、jj 策略。
 可选（推荐）：主环境 URL、共享 QA URL、预览槽位池（如 preview-a/preview-b）和预览 URL 模板。
 ```
 
+## Plan Summary Template
+
+Use this comment or PR note after the MajorAgent has created the plan:
+
+```text
+[issue-plan-summary-v1]
+已生成执行计划：
+- issue: #<number>
+- status: <selected|planned|...>
+- target base: <branch>
+- working branch: <branch>
+- allowed scope: <paths>
+- expected behavior: <summary>
+- verification: <unit/integration/e2e/smoke>
+- assigned agent: <major|sub|test>
+未完成前不会进入代码修改。
+```
+
 ## Review Request Template (Semi-Automatic)
 
 ```text
@@ -65,6 +84,7 @@ Use this at session start before any implementation:
 - issue: #<number>
 - branch: <branch>
 - commit: <sha>
+- pr: <url>
 - change summary: <summary>
 - risk: <risk notes>
 - test plan: <plan>
@@ -79,12 +99,14 @@ Use this at session start before any implementation:
 - issue: #<number>
 - branch: <branch>
 - commit: <sha>
+- pr: <url>
 - pipeline/test run: <url>
 - environment: <env/version>
 - preview slot: <slot>
 - preview url: <url>
 - deploy scope: <skip|client_only|server_only|full_stack|infra_only>
 - server strategy: <reused-shared|dedicated-branch-server>
+- e2e: <passed|failed|waived-with-approval>
 - verify steps: <steps>
 如失败或结果不符合预期，将继续同分支迭代修复。
 ```
@@ -121,6 +143,7 @@ Use this at session start before any implementation:
 - issue: #<number>
 - branch: <branch>
 - target: <target branch>
+- pr: <url>
 - review status: <approved/pending>
 - test status: <passed/failed>
 - release evidence: <links>
@@ -133,6 +156,7 @@ Use this at session start before any implementation:
 [issue-verified-close-v1]
 已修复并发布。
 - commit: <sha>
+- pr: <url>
 - tests: <summary>
 - deploy: <pipeline/run url>
 - verify: <how verified>