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

2026-03-13 13:18:48 +08:00
parent acb77a821c
commit ccfdda4342
6 changed files with 490 additions and 27 deletions
--- a/skills/gitea-issue-devops-agent/references/issue-template-standard.md
+++ b/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
+```
--- a/skills/gitea-issue-devops-agent/references/plan-template.md
+++ b/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`.
--- a/skills/gitea-issue-devops-agent/references/triage-standard.md
+++ b/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>