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

---
name: llm-project-workflow
description: >-
  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.
---
> **Also known as:** `gitea-workflow`, `git-pr-workflows` (canonical multi-runtime names — see docs/workflow-skill-mount.md / #551).


# 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`](workflows/review-merge-pr.md) | [`schemas/review-merge-final-report.md`](schemas/review-merge-final-report.md) |
| Reconcile already-landed open PRs | [`workflows/reconcile-landed-pr.md`](workflows/reconcile-landed-pr.md) | [`schemas/reconcile-landed-final-report.md`](schemas/reconcile-landed-final-report.md) |
| Create or update Gitea issues | [`workflows/create-issue.md`](workflows/create-issue.md) | [`schemas/create-issue-final-report.md`](schemas/create-issue-final-report.md) |
| Work on an assigned issue / author code | [`workflows/work-issue.md`](workflows/work-issue.md) | [`schemas/work-issue-final-report.md`](schemas/work-issue-final-report.md) |
| PR-only queue cleanup (one canonical review per PR) | [`workflows/pr-queue-cleanup.md`](workflows/pr-queue-cleanup.md) | [`schemas/pr-queue-cleanup-final-report.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.
- **BLOCKED + DIAGNOSE default rule (required):** If any required workflow step, skill, tool, capability, preflight, instruction, profile, worktree binding, or terminal/MCP operation cannot be performed or loaded (including the canonical ones listed in this skill and its loaded workflow), immediately enter `BLOCKED + DIAGNOSE`. Stop before any git or Gitea mutation. Diagnose using the standard template in [`templates/blocked-diagnose-report.md`](templates/blocked-diagnose-report.md). Attempt *only* safe non-mutating recovery. Report using the template. Do not continue, use fallbacks, or treat the missing requirement as harmless.
- If the required workflow cannot be loaded, stop and produce a recovery handoff
  only (see BLOCKED + DIAGNOSE rule above).
- 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.

## Covered blocker classes (BLOCKED + DIAGNOSE must trigger for these)

- missing required skill or workflow guide (e.g. gitea-workflow, llm-project-workflow)
- broken terminal/tool runner or shell spawn failure
- MCP capability failure, reset, or deadlock (e.g. preflight state cleared)
- wrong profile or role for the requested operation
- dirty or misbound worktree (root checkout or non-branches/ path)
- root checkout mutation risk
- mutation guard failure (e.g. branches-only guard)
- missing required MCP tool/schema or operation
- stale or inconsistent runtime state (e.g. lease vs actual, dirty state disagreement)
- unavailable project instructions or checked-in guides
- any other failure of a step the current workflow or controller prompt declares "required"

**Prohibited unless controller authorizes in writing for this instance:** temp scripts, direct API fallback, MCP internals, direct imports, in-memory state restoration, manual bypasses, or any continuation that hides the blocker. All such cases must be reported as process/tooling defects.

## 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/`](templates/):

- [`start-issue.md`](templates/start-issue.md) — author work (loads `work-issue.md`)
- [`review-pr.md`](templates/review-pr.md) — review (loads `review-merge-pr.md`)
- [`pr-queue-cleanup.md`](templates/pr-queue-cleanup.md) — one PR per cleanup run
- [`merge-pr.md`](templates/merge-pr.md) — merge (loads `review-merge-pr.md`)
- [`recover-bad-state.md`](templates/recover-bad-state.md)
- [`reconcile-closed-not-merged-pr.md`](templates/reconcile-closed-not-merged-pr.md)
- [`worktree-cleanup.md`](templates/worktree-cleanup.md)
- [`release-tag.md`](templates/release-tag.md)
- [`canonical-state-comments.md`](templates/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`](templates/release-tag.md) and
`scripts/release-tag`.

## Proof: missing required workflow steps stop before mutation

- The llm-project-workflow router (this file) and every loaded workflow (work-issue.md, review-merge-pr.md, create-issue.md, etc.) now declare at the top: if required step/skill/tool/capability/instruction/profile/worktree binding/preflight fails, STOP, state BLOCKED, use blocked-diagnose-report.md template, only non-mutating recovery.
- Controller prompts (start-issue.md, review-pr.md, merge-pr.md, recover-bad-state.md, etc.) and the runbooks (docs/llm-workflow-runbooks.md) explicitly require the same and prohibit unsafe fallbacks.
- MCP guards (branches-only mutation guard #274, worktree binding #510, preflight purity, role checks, lease gates, gitea_lock_issue, etc.) plus the "prove before mutation" rules ensure that a BLOCKED state prevents git/Gitea mutations.
- When a skill/guide/tool is missing (e.g. gitea-workflow not mounted for a runtime), the load step in the router/prompt fails the "required" check → BLOCKED + report before any gitea_* call or git command that mutates.
- Terminal/shell failures, capability deadlocks, wrong profile, dirty/misbound worktree, root risk, guard failures, missing schema, stale state, unavailable instructions all map to the covered blocker classes and trigger the same stop + report.
- No code path in the canonical workflows allows continuation past a declared required step without the BLOCKED report.
- See also: Global LLM Worktree Rule, Shell Spawn Hard-Stop Rule, Identity and profile safety, Subagent Tool-Budget Guardrails, and the explicit prohibition list in Universal rules.

Tests / proof docs updated in this change + runbooks. Full relevant test runs (see PR handoff) pass; `git diff --check` clean. Missing-step cases are now documented to fail closed before mutation.

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