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

LLM Project Workflow

Use this skill when an LLM is asked to create issues, implement repository changes, review pull requests, merge pull requests, or recover from unsafe git state in any project.

This skill is intentionally portable. Replace the remote name, default branch, profile names, and repository URL conventions with the target project's local standards, but keep the safety rules intact.

Core Rule

No repository change happens without a tracking issue first.

Repository changes include creating files, editing files, deleting files, changing executable bits, changing documentation, adding scripts, changing config, committing, pushing, and opening pull requests.

If no issue exists, create one before touching the repository. If issue creation or issue claiming fails, stop immediately and report the blocker.

Worktree Isolation

Never implement or review directly in the main checkout.

The main checkout is for orchestration only: status checks, issue creation, issue claiming, fetching, and creating branch worktrees. Each issue gets a separate branch worktree under an ignored branches/ directory. Review work gets its own separate review worktree.

Dirty work in one branch folder must not block unrelated work in another branch folder. No LLM may edit or clean another issue's worktree unless explicitly assigned to that issue and cleanup is part of the task.

Branch Naming

Every implementation branch must include its issue number so it is traceable end to end: issue → branch → worktree folder → PR → cleanup.

Allowed implementation patterns:

• fix/issue-123-short-description
• feat/issue-123-short-description
• docs/issue-123-short-description
• chore/issue-123-short-description

Review-only branches:

• review/pr-456-short-description

Use a filesystem-safe folder under branches/ by replacing slashes with hyphens, for example branches/fix-issue-123-short-description.

scripts/worktree-start enforces this: it rejects an implementation branch that does not match (fix|feat|docs|chore)/issue-<number>-… (or a review/pr-<number>-… branch), unless --allow-unlinked is passed. Traceability is maintained by:

• the branch name (contains the issue number),
• a claim comment on the issue, e.g. Claimed. Branch: fix/issue-123-short-description. Worktree: branches/fix-issue-123-short-description.,
• the PR body — Closes #123 when the PR should close the issue, Refs #123 when related but not closing,
• cleanup after merge — remove the remote branch, local branch, and the issue worktree folder, and drop status:in-progress.

Forges like Gitea do not expose a native issue→branch association through the API (only a PR's head branch), so linkage is enforced by the branch name, claim comment, PR body, and cleanup process above — not a dedicated API field.

Worktree Creation

Generic pattern:

git fetch <remote> --prune
git worktree add -b <branch> branches/<safe-branch-folder> <remote>/master
cd branches/<safe-branch-folder>

For Gitea-Tools specifically:

./scripts/worktree-start fix/issue-123-example
cd branches/fix-issue-123-example

If the default branch is not master, use the target project's default branch. If local master is ahead of the remote unexpectedly, stop before creating the worktree and ask for explicit recovery instructions.

Identity And Profile Safety

Use canonical execution profiles where available. The profile is the role; the LLM is not permanently an author, reviewer, or merger.

Author and reviewer identities must be distinct. Before review, approval, merge, or branch cleanup, verify both the authenticated user and the PR author. If the authenticated user is the PR author, stop immediately.

Never place raw tokens or passwords in LLM configs, prompts, commits, PR comments, logs, or tool outputs. Prefer profile references such as:

• GITEA_MCP_CONFIG
• GITEA_MCP_PROFILE

If identity cannot be determined, fail closed. Do not approve, merge, close, or clean up with an unknown identity.

Implementation Workflow

1. Verify the request has a tracking issue. If not, create one.
2. Claim the issue using the project's in-progress convention, such as status:in-progress.
3. Fetch/prune and confirm the local default branch matches the remote default branch.
4. Create an issue-specific branch worktree from the latest remote default branch.
5. Implement only the issue scope inside that worktree.
6. Run focused checks and the project's required full checks.
7. Inspect the diff for scope, secrets, and unrelated files.
8. Commit.
9. Push.
10. Open a PR to the default branch.
11. Stop before review or merge if you authored the PR.

Review Workflow

1. Use a separate review worktree.
2. Verify authenticated identity.
3. Verify PR author.
4. Stop if authenticated identity matches the PR author.
5. Verify the PR is open and targets the expected base branch.
6. Verify the PR head matches the reviewed commit or includes it.
7. Verify the review worktree is clean.
8. Inspect changed files and diff against the linked issue scope.
9. Run required tests and checks.
10. Inspect for secrets, credential paths, raw environment dumps, unrelated work, and disallowed behavior.
11. If checks fail, leave exact blockers and do not approve or merge.
12. If checks pass and the reviewer is eligible, approve or leave the requested review comment according to the task.

Merge And Cleanup Workflow

Only merge when assigned merge duty and reviewer-eligible.

After an eligible merge:

1. Confirm the PR is still open and targets the expected base branch.
2. Confirm the PR head is still the reviewed commit or includes it.
3. Confirm the authenticated user is not the PR author.
4. Merge through the project's gated merge workflow.
5. Confirm remote master or the target default branch contains the merge.
6. Close or release the linked issue according to project workflow.
7. Remove status:in-progress or the equivalent in-progress label when applicable.
8. Delete the merged remote branch when policy allows.
9. Remove the local PR branch.
10. Remove the local branch worktree folder only after confirming it is merged or no longer needed.
11. Fetch/prune.
12. Confirm the main checkout is clean and current.

Do not delete branches or worktrees containing unmerged work.

Fail-Closed Cases

Stop immediately if any of these are true:

• no issue exists and one cannot be created
• the issue cannot be claimed
• a worktree is dirty and belongs to the current task, but its state is unclear
• dirty work belongs to another issue or another LLM
• branch or PR state conflicts with the prompt
• the PR is closed but not merged
• local master is ahead of the remote unexpectedly
• authenticated identity cannot be verified
• authenticated user is the PR author for review, approval, or merge
• the active profile is unknown or not allowed for the requested operation
• secrets, tokens, passwords, auth headers, or credential paths are found in the diff
• tests or required checks fail
• branch cleanup would delete unmerged work
• production, deploy, rollback, migration, restart, CI trigger, or unrelated service behavior appears outside the issue scope

Fail closed means no mutation, no approval, no merge, and no cleanup that could destroy work.

Recovery Patterns

Dirty worktree from another issue:

• Do not edit, reset, delete, or clean it.
• Create or use a separate branch worktree for the assigned issue.
• Report the unrelated dirty files only if they affect the task.

Dirty worktree from the current issue:

• Inspect status and diff.
• Preserve useful work in a commit, patch, or explicit handoff only when asked.
• Do not reset or delete ambiguous work without explicit approval.

Local default branch ahead of remote:

• Stop.
• Report the local and remote commit hashes.
• Ask whether to push, preserve, or reset. Do not choose destructively.

PR closed but not merged:

• Do not merge.
• Release the issue from in-progress only if the task explicitly asks and the project workflow allows it.
• Leave a clear comment explaining the PR is closed without merge.

Branch deleted before merge:

• Verify whether the PR was merged.
• If merged, cleanup can continue.
• If not merged, stop and report that the source branch is missing.

Unauthorized untracked file created:

• Stop immediately.
• Report the exact file path.
• Do not commit it.
• Remove it only when explicitly instructed or when the recovery request asks for removal.
• Recreate the change only after an issue exists and is claimed.

Need to preserve commits before reset:

• Prefer non-destructive preservation: tag, branch, patch file, or pushed backup branch.
• Do not use destructive reset or checkout commands unless the user explicitly requests that operation.

Prompt Templates

Ready-to-copy templates live in templates/:

• start-issue.md
• review-pr.md
• merge-pr.md
• recover-dirty-worktree.md
• release-tag.md

Adapt the placeholders to the project before use.

Versioning And Tagging

Releases follow SemVer: vMAJOR.MINOR.PATCH (use v0.x.y while unstable). Choose the bump by the largest change since the last tag:

• PATCH — bug fixes, docs, tests, wrappers, non-breaking workflow polish.
• MINOR — new tools/helpers/config features; backward-compatible behavior.
• MAJOR — breaking config/schema/API behavior or a changed MCP contract.

Tags must:

• be created only from master (the exact commit on remote master),
• be created only after the full test suite passes,
• be annotated tags (git tag -a), never lightweight,
• include release notes / a changelog summary referencing the merged PRs/issues.

Never tag feature branches, dirty worktrees, unreviewed or self-authored work, or commits not present on remote master.

Release process (see templates/release-tag.md):

1. git fetch <remote> --prune.
2. Verify local master equals remote master (0 0) and the tree is clean.
3. Run the full test suite; stop on any failure.
4. Inspect merged issues/PRs since the last tag (git log --oneline <last-tag>..<remote>/master).
5. Choose the version bump.
6. Create the annotated tag on remote master with release notes.
7. Push the tag.
8. Create/update release notes if the forge supports it.