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

name, description

name	description
llm-project-workflow	Portable, safe operating workflow for LLMs working on any Git/forge project: issue-first, isolated branch worktrees, no self-review/self-merge, distinct author/reviewer profiles, cleanup after merge, and fail-closed behavior. Use at the start of any implementation, review, or merge task on a repo.

LLM Project Workflow

A reusable workflow any LLM can follow to work on any repository safely. Copy this skills/llm-project-workflow/ directory into another project unchanged; adapt only the forge-specific names in Adapting to a project.

The core promise: an LLM never does unsafe or untracked work. Every change is tracked by an issue, isolated in its own worktree, reviewed by a different identity, and cleaned up only after a real merge.

---

A. Issue-first rule

No repository change without a tracking issue. This includes creating, editing, deleting, or chmod-ing files; docs; scripts; commits; pushes; and PRs.

1. Before any change, confirm a tracking issue exists.
2. If none exists, create one first (title + problem + scope + acceptance).
3. Claim it (assign yourself or apply the status:in-progress label) and comment that work is starting, including the planned branch name.
4. If the issue cannot be created or claimed, stop. Do not touch files.

Reading the repo, running read-only status/git log, and creating/claiming the issue itself are allowed from the orchestration checkout without a prior issue.

B. Isolated worktree rule

Never implement or review in the main checkout. The main checkout is for orchestration and status only (issue creation, git status, creating worktrees).

• Each issue gets its own branch worktree under an ignored branches/ directory.
• Review work uses a separate review worktree, never the author's folder.
• Dirty work in one branch folder must not block starting another issue.
• No LLM may edit another issue's worktree unless explicitly assigned to it.
• Branch folders are removed only after the PR is merged/closed and cleanup is explicitly part of the task.

Preferred helpers (if present in the project):

scripts/worktree-start fix/issue-123-example      # → branches/fix-issue-123-example
scripts/worktree-review fix/issue-123-example     # → branches/review-fix-issue-123-example (detached)
scripts/worktree-clean  --delete-branch fix/issue-123-example

Manual equivalent:

git fetch <remote> --prune
git worktree add -b fix/issue-123-example branches/fix-issue-123-example <remote>/master
cd branches/fix-issue-123-example

venv/ and similar are not copied into new worktrees — run checks with a known interpreter path, or create a venv inside the branch folder.

C. Identity and profile safety

• Use canonical execution profiles where available; the profile is the role, not the LLM. A task selects a profile; a profile is not permanently assigned.
• Author and reviewer identities must be distinct.
• Never place raw tokens/passwords in an LLM/MCP client config. Reference secrets by keychain id or environment variable name only. Prefer a single canonical config file selected by two env vars, e.g.:
  • GITEA_MCP_CONFIG — path to the canonical profiles file
  • GITEA_MCP_PROFILE — the profile to activate
• If the authenticated user equals the PR author, stop — no self-review, no self-merge.

D. Branch naming

fix/issue-123-short-description
feat/issue-123-short-description
docs/issue-123-short-description
review/pr-456-scope-check

Worktree folder = branch with / replaced by - (branches/fix-issue-123-short-description).

E. Start-work workflow

1. Verify the orchestration checkout (right repo, clean tree).
2. Fetch/prune: git fetch <remote> --prune.
3. Confirm local master equals remote master (git rev-list --left-right --count <remote>/master...master → 0 0).
4. Create/claim the issue (§A).
5. Create the isolated worktree (§B) from latest remote master.
6. Implement the narrow scope only — no unrelated refactors or formatting churn.
7. Add/update focused tests when behavior changes.
8. Run the checks (tests, compile/lint, git diff --check, secret scan).
9. Commit with an issue-linked message.
10. Push the branch.
11. Open a PR to master.
12. If you are the author, stop before review/merge.

F. Review workflow

1. Use a separate review worktree (scripts/worktree-review <branch>), detached.
2. Verify your authenticated identity.
3. Verify the PR author — you must not be the author.
4. Verify the worktree is clean.
5. Inspect the full diff; confirm scope matches the linked issue; flag unrelated files.
6. Run the tests.
7. Do not merge if checks fail. Do not merge if the reviewer is the author.

G. Merge / cleanup workflow

Only an eligible (non-author) reviewer merges. After a real merge:

1. Confirm remote master actually contains the merge commit.
2. Close/release the issue; remove status:in-progress if used.
3. Delete the remote branch.
4. Remove the local branch.
5. Remove the branch worktree folder (scripts/worktree-clean --delete-branch <branch>).
6. Fetch/prune.
7. Confirm the main checkout is clean and current (0 0 vs remote).

Never run cleanup before the merge is confirmed on remote master.

H. Fail-closed cases

Stop and report — take no mutating action — if:

• No issue exists and one cannot be created.
• Worktree state is unclear or unexpected.
• Branch/PR state conflicts with the prompt (e.g. prompt says "merged" but it is not).
• A PR is closed but not merged.
• Local master is ahead of remote unexpectedly.
• The authenticated user is the PR author (for review/merge).
• Secrets/tokens appear in the diff.
• Tests fail.
• A cleanup step would delete unmerged work.

When in doubt, stop and surface the discrepancy; do not guess or work around a gate.

I. Recovery patterns

• Dirty worktree from another issue: do not touch it. Start your issue in its own new worktree; unrelated dirty work must not block you.
• Local master ahead of remote unexpectedly: do not push master. Confirm the commits are preserved on a feature branch (local + remote) first, then git reset --hard <remote>/master to realign. Never discard commits that are not safely pushed elsewhere.
• PR closed but not merged: the work is not in mainline. Re-push the branch, reopen (or open a replacement) PR, and let an eligible reviewer merge. Do not assume "closed" means "merged" — verify remote master contains the commits.
• Branch deleted before merge: if the commits still exist locally (a branch or reflog), re-push them and reopen the PR; otherwise recover via git fsck --lost-found. Preserve first, then proceed.
• Unauthorized/untracked file created: do not commit it. Leave pre-existing untracked artifacts (e.g. editor/agent dirs, reports) alone; stage only the files your issue names (git add <files>, never blind git add -A).
• Preserve commits before a reset: confirm the target commits are reachable from a branch that is pushed to the remote, then reset. Verify with git branch --contains <sha> and git log <remote>/<branch>.

J. Prompt snippets

Ready-to-copy templates live in templates/:

• start-issue.md — start a new issue.
• review-pr.md — review a PR.
• merge-pr.md — merge a PR (eligible reviewer only).
• recover-bad-state.md — recover from bad state.
• worktree-cleanup.md — clean up after merge.

Adapting to a project

Replace these project-specific names when copying the skill elsewhere:

Placeholder	Meaning	Example here
<remote>	Git remote for the forge	prgs
default branch	Integration branch	master
profile env vars	Canonical config + profile selectors	GITEA_MCP_CONFIG, GITEA_MCP_PROFILE
branches/	Ignored worktree directory	branches/
helper scripts	Worktree helpers	scripts/worktree-start / -review / -clean

The rules in §A–§I are project-agnostic and should not change.