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