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

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.