Gitea-Tools/skills/llm-project-workflow/SKILL.md

name, description

name	description
llm-project-workflow	Router skill for safe LLM project work: identify task mode, load the matching canonical workflow file, enforce mode isolation, and emit the correct final report schema. Use at the start of any implementation, review, merge, reconciliation, or issue-filing task.

LLM Project Workflow Skill

This skill is a router. Do not perform project work from this file alone.

Before any project mutation, identify the task mode and load the matching workflow file.

Workflow modes

Task mode	Workflow	Final report schema
PR review / approval / merge	workflows/review-merge-pr.md	schemas/review-merge-final-report.md
Reconcile already-landed open PRs	workflows/reconcile-landed-pr.md	schemas/reconcile-landed-final-report.md
Create or update Gitea issues	workflows/create-issue.md	schemas/create-issue-final-report.md
Work on an assigned issue / author code	workflows/work-issue.md	schemas/work-issue-final-report.md
PR-only queue cleanup (one canonical review per PR)	workflows/pr-queue-cleanup.md	schemas/pr-queue-cleanup-final-report.md

Universal rules

• Prove identity, active profile, runtime context, and exact capability before mutation.
• A nearby capability does not count.
• Do not self-review or self-merge.
• Do not mix modes in one run.
• If the required workflow cannot be loaded, stop and produce a recovery handoff only.
• Final report must use the schema for the loaded workflow.
• If a task requires a different mode, stop and produce a handoff for the correct workflow.

Mode isolation

A run that starts in review-merge-pr mode may not create process issues, implement fixes, or edit source files.

A run that starts in reconcile-landed-pr mode may not approve, request changes, merge, implement fixes, or create normal issues.

A run that starts in create-issue mode may not review, approve, request changes, merge, implement fixes, create branches, commit, push, or create PRs.

A run that starts in work-issue mode may not review, approve, request changes, merge, close PRs, or act as reviewer.

A run that starts in pr-queue-cleanup mode may not claim issues, create branches, edit implementation files, file new issues, or review a second PR after any terminal review mutation.

If the task requires a different mode, stop and produce a handoff for the correct workflow.

---

Definitions

• Merged: Gitea PR metadata says merged=true.
• Landed: Equivalent content is present on remote master, but PR metadata may not say merged.
• Closed-not-merged: PR state is closed and merged=false.
• Reconciled: Verified whether closed-not-merged or already-landed content is present on the target branch; issue/label/tracker state repaired.

Work Selection Rule for LLMs

Before starting any issue or PR work, acquire or verify a work lease. Do not begin coding, reviewing, fixing, branching, committing, pushing, commenting, or creating a PR until you prove the target is not already being worked.

Required checks:

1. List open PRs.
2. Search for PRs linked to the target issue.
3. Search local and remote branches for the issue number.
4. Search registered worktrees for the issue branch.
5. Check dirty worktrees.
6. Check active leases or recent handoffs.
7. Check whether the issue was already completed by a merged PR.

If another active session owns the lease, stop with "work already claimed" or produce a handoff.

For Gitea-Tools: gitea_lock_issue is the fail-closed lease gate before author mutations; status:in-progress and claim comments are supporting lease signals.

Global LLM Worktree Rule

The main project checkout is a stable control checkout on master, main, or dev. All LLM task work must happen inside the project's branches/ directory.

If cwd is not inside branches/, stop before any file edit, test write, commit, merge, rebase, or cleanup. The main checkout is orchestration-only.

Shell Spawn Hard-Stop Rule

exit_code: -1 with empty stdout/stderr means the shell failed to spawn — not a command failure. After two consecutive spawn failures, hard-stop shell use for the session and emit a recovery report (#258).

Isolated worktree naming

Implementation: (fix|feat|docs|chore)/issue-<number>-<short-description>

Review: review/pr-<number>-<short-description>

Subagent Tool-Budget Guardrails

General-purpose subagents on single-step MCP tasks (for example gitea_commit_files) must not expand into 100+ tool-call retry spirals with WebFetch/Playwright/manual-encoding fallbacks (issue #259).

Default budgets (stop when exceeded):

• Single-step MCP mutation (commit_files, create_pr, lock_issue): 15 tool calls, 5 minutes wall time.
• Review / merge queue inspection: 40 tool calls, 15 minutes.
• Non-mutating exploration: 60 tool calls, 20 minutes.

Rules:

1. When the main session has gitea.repo.commit, call gitea_commit_files directly — do not delegate commit to a subagent (#260).
2. After shell spawn failure (#258), attempt the native MCP tool once before any fallback; shell unavailability never authorizes WebFetch/Playwright/ manual base64.
3. Never resume a failed subagent into a larger retry loop or spawn a second subagent for the same deterministic step — stop and report.
4. When gitea_commit_files is available, forbid WebFetch, Playwright, manual encoding, and ad-hoc _encode_* / _emit_* helpers in the repo.

Worktree folder: branch with / replaced by - under branches/.

Helpers: scripts/worktree-start, scripts/worktree-review, scripts/worktree-clean.

Identity and profile safety

• Author and reviewer identities must be distinct.
• Never place raw tokens in LLM/MCP config.
• Use gitea_whoami and gitea_resolve_task_capability before mutating.

Controller Handoff

Every task must end with a section titled exactly Controller Handoff. Compact format canonical field set per issue #182; mode-specific schemas in schemas/*-final-report.md define required fields. Use the final report schema for the loaded workflow mode — not the legacy compact block alone. review_proofs.assess_controller_handoff() validates presence.

Prompt templates

Ready-to-copy task prompts live in templates/:

• start-issue.md — author work (loads work-issue.md)
• review-pr.md — review (loads review-merge-pr.md)
• pr-queue-cleanup.md — one PR per cleanup run
• merge-pr.md — merge (loads review-merge-pr.md)
• recover-bad-state.md
• reconcile-closed-not-merged-pr.md
• worktree-cleanup.md
• release-tag.md
• canonical-state-comments.md

Adapting to a project

Placeholder	Example here
<remote>	prgs
default branch	master
profile env vars	GITEA_MCP_CONFIG, GITEA_MCP_PROFILE
branches/	branches/
helpers	scripts/worktree-start / -review / -clean

Versioning And Tagging

Releases follow SemVer from remote master only, after full test suite passes. See templates/release-tag.md and scripts/release-tag.

Bootstrap Review Path (#557)

Self-hosted MCP workflow fixes can deadlock live review daemons. Do not bypass gates with raw API, direct imports, or root checkout edits.

If and only if a controller posts a durable BOOTSTRAP REVIEW AUTHORIZATION (#557) record, follow:

docs/bootstrap-review-path.md

Otherwise stop with BLOCKED + DIAGNOSE. Bootstrap never weakens normal PR gates.