sysadmin
565363d5f4
Document the narrow controller-authorized path for landing MCP workflow fixes when live daemons cannot canonically review themselves, with required audits, allowed/forbidden actions, and post-land restart steps.
199 lines
8.1 KiB
Markdown
199 lines
8.1 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# 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.
|
|
- 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/`](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)
|
|
|
|
## 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`.
|
|
|
|
## 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.
|
|
|