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

---
name: gitea-issue-devops-agent
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.
- Treat workflow spec, compiled lock artifact, and evidence artifacts as executable system-of-record once the runtime is available; do not rely on prose-only guidance for enforcement.
- 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.

## Runtime Contract (Required)

When the repository contains the runtime package, use it instead of ad-hoc execution:

1. Author or update the workflow spec in `workflows/*.md`.
2. Compile before execution:
   - `python -m engine.devops_agent.cli compile workflows/gitea-issue-delivery.md --output workflows/gitea-issue-delivery.lock.json`
3. Validate before execution:
   - `python -m engine.devops_agent.cli validate workflows/gitea-issue-delivery.md`
4. Run or accept only through declared safe outputs.
5. Persist run evidence under `.tmp/...` and treat `run-artifact.json` as execution proof.
6. For real Gitea verification, use:
   - `python -m engine.devops_agent.cli acceptance workflows/gitea-issue-delivery.md --base-url <url> --repo <owner/repo> --token <token> --issue-number <n> --output-dir .tmp/acceptance/gitea`

Hard rules:

- No undeclared write actions.
- No execution after failed validation.
- No claiming completion without runtime evidence.

## Mandatory Guided Start

Run this interaction before any coding or issue action:

1. Ask for repository address:
   - preferred: full URL `https://<host>/<owner>/<repo>`
   - fallback: `base_url` + `owner/repo`
2. Ask for API key/token with issue read/write permissions.
3. Ask user to select mode:
   - `automatic`
   - `semi-automatic`
   - `manual` (non-automatic)
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:
     - stable main URL (`main` fixed test env)
     - optional shared QA URL
     - preview slot pool (for issue branches), e.g. `preview-a,preview-b`
     - preview URL template, e.g. `https://{slot}.qa.example.com`
     - public routing mode: `port-based` or `virtual-host`
     - websocket public entry: explicit WS URL (`wss://...`) or same-origin path (`/ws`)
   - deployment environment + health endpoint
   - minimum issue quality score (default `70`)
   - `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`
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`
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

- 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.
- Merge is still blocked until an engineer explicitly confirms merge approval.

### 2) Semi-Automatic Mode

- 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.
- After approval, allocate/reuse branch preview env, trigger branch test submission and continue loop.
- Close issue only after evidence is complete.
- Merge is still blocked until an engineer explicitly confirms merge approval.

### 3) Manual Mode (Non-Automatic)

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
- closing/reopening issue
- executing merge

No autonomous transition is allowed in manual mode.

## Branch-First Rules

- 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)

Always avoid `main` and issue branches overwriting each other.

1. `main` fixed env (stable):
   - one permanent URL for regression/baseline testing
2. optional shared QA env:
   - integration testing across multiple completed branches
3. issue preview slot env (ephemeral pool):
   - small fixed pool (`N` slots, e.g. 2)
   - one active branch binds to one slot
   - issue comments must include slot + URL + branch
   - close/merge/TTL expiry releases slot

Never deploy different branches to the same fixed URL unless user explicitly approves override.

### Routing Strategy (Recommended)

- Prefer `virtual-host` over raw ports for multi-branch testing:
  - `main.example.com`, `preview-a.example.com`, `preview-b.example.com`
  - Keep internal process ports private; expose only 80/443.
- Use same-origin WS path for frontend (`VITE_WS_URL=/ws`) and route `/ws/*` to the slot server.
- If `port-based` is used, every active env must have unique client/server ports; never reuse one public URL for two branches.

## Issue -> Branch -> Environment Binding

- Binding key: `<repo>#<issue>#<branch>`
- Environment selection:
  - if branch already has assigned slot: reuse same slot
  - else allocate free slot from pool
  - if no free slot:
    - in `automatic`: evict oldest expired/inactive slot if policy allows
    - in `semi-automatic` / `manual`: request explicit confirmation before eviction
- Persist slot state in `.tmp/preview-slots.json` via `scripts/preview_slot_allocator.py`

## Resource-Aware Deployment Strategy (Required)

Before every branch test submission, detect change scope:

- `python scripts/change_scope.py --repo-path <local_repo> --base-ref <target_base> --head-ref <branch_or_sha>`

Use the scope result to minimize resource usage:

1. `skip` (docs/tests/chore-only):
   - do not deploy
   - post no-op verification evidence
2. `client_only`:
   - build/deploy client only
   - reuse existing shared/stable server
   - do not start a dedicated server for this branch
3. `server_only`:
   - deploy/restart server only
   - keep existing client if unchanged
4. `full_stack`:
   - deploy both client and server
5. `infra_only`:
   - apply infra/workflow changes; restart only required components

Hard rule:
- If server-related scope is unchanged, do not provision/restart dedicated server processes for that issue branch.

## Standard Workflow (All Modes)

### 1) Issue Selection and Trigger

- 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`
  - `open` + `quality_score >= min_quality_score`
  - `open` + `quality_score < min_quality_score` (request details first)
  - `closed_open_reopen_candidates`
- For issues with images, inspect attachments before coding.

### 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`.

### 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.

### 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.

### 8) Branch Test Submission ("提测")

- Submit testing on the issue branch (CI pipeline + branch preview env).
- Allocate/reuse branch slot before submission.
- Apply resource-aware deployment decision from change scope.
- 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.

### 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.

### 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

### 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.

### 13) Environment Cleanup

- On issue close/merge:
  - release preview slot
  - stop branch-only processes (if any)
  - keep main/shared env untouched
- 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

### Runtime CLI

- `python -m engine.devops_agent.cli compile workflows/gitea-issue-delivery.md --output workflows/gitea-issue-delivery.lock.json`
- `python -m engine.devops_agent.cli validate workflows/gitea-issue-delivery.md`
- `python -m engine.devops_agent.cli run workflows/gitea-issue-delivery.md --event-payload <payload.json> --output-dir .tmp/runtime-run --base-url <url> --token <token>`
- `python -m engine.devops_agent.cli acceptance workflows/gitea-issue-delivery.md --base-url <url> --repo <owner/repo> --token <token> --issue-number <n> --output-dir .tmp/acceptance/gitea`

- runtime writes `run-artifact.json` and should be used as the evidence source for status promotion and issue comments.

- `scripts/issue_audit.py`: collect issues/comments/attachments, detect duplicates, score quality, detect unresolved/closed-open links, extract issue branch hints, and generate reports.
  - image intake uses three sources: markdown/html links, payload `assets/attachments` fields, and `/issues/*/assets` API endpoints.
  - if your Gitea blocks the assets endpoints, pass `--skip-asset-endpoints` and rely on payload extraction.
- `scripts/preview_slot_allocator.py`: allocate/reuse/release/list preview slots by issue+branch.
  - allocate example:
    - `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots preview-a,preview-b --repo <owner/repo> --issue 48 --branch dev --ttl-hours 24 --url-template https://{slot}.qa.example.com`
  - release example:
    - `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots preview-a,preview-b --release --repo <owner/repo> --issue 48 --branch dev`
- `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.
- `references/jj-default-usage.md`: default `jj` installation strategy, verification, and scenario-based usage guidance.

## 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.
- Never bypass engineer merge confirmation.
- Never allow branch previews to overwrite main stable env.
- Never start dedicated branch server when scope indicates client-only changes.
- When changing public service ports under PM2, do not rely on `pm2 restart --update-env` alone; delete and recreate the process so CLI args (for example `--port`) actually change.
- If a branch must be rebound to a specific preview slot (for example `preview-a`), release the existing issue allocation first, then redeploy; reuse logic otherwise keeps the previous slot by design.