docs: add portable LLM workflow skill

README.md

@@ -270,6 +270,15 @@ The generated launcher snippets contain only `command`, `args`,
 `GITEA_MCP_CONFIG`, and `GITEA_MCP_PROFILE` — never a token or password.
 </details>
 
+### Portable LLM workflow skill
+
+Reusable LLM operating rules are packaged as a portable skill at
+[`skills/llm-project-workflow/SKILL.md`](skills/llm-project-workflow/SKILL.md).
+It documents issue-first work, isolated branch worktrees, no self-review or
+self-merge, profile safety, fail-closed behavior, merge cleanup, and recovery
+patterns. Copy the `skills/llm-project-workflow/` directory into other projects
+that should use the same workflow.
+
 <details>
 <summary><strong>Codex / non-MCP tools</strong></summary>
 

docs/llm-workflow-runbooks.md

@@ -12,6 +12,12 @@ behavior they rely on already exists (canonical runtime profiles, the
 interactive setup menu, identity/eligibility checks, gated review/merge, and
 audit logging). See [Related documents](#related-documents).
 
+For cross-project use, copy the portable workflow skill at
+[`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md).
+It extracts the issue-first, isolated-worktree, no-self-review, profile-safety,
+merge-cleanup, fail-closed, and recovery rules into a reusable package that can
+be adapted to other repositories.
+
 ## Principle: the profile is the role, not the LLM
 
 ```text
@@ -316,6 +322,7 @@ with the profile and authenticated user when `GITEA_AUDIT_LOG` is set (see
 
 ## Related documents
 
+- [`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) — portable cross-project LLM workflow skill.
 - [`gitea-execution-profiles.md`](gitea-execution-profiles.md) — the profile model.
 - [`safety-model.md`](safety-model.md) — trust boundaries and audit logging.
 - [`tool-boundaries.md`](tool-boundaries.md) — per-tool allowed operations.

skills/llm-project-workflow/SKILL.md

@@ -0,0 +1,225 @@
+# 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
+
+Use issue- or PR-scoped names:
+
+- `fix/issue-123-short-description`
+- `feat/issue-123-short-description`
+- `docs/issue-123-short-description`
+- `review/pr-456-scope-check`
+
+Use a filesystem-safe folder under `branches/` by replacing slashes with
+hyphens, for example `branches/fix-issue-123-short-description`.
+
+## Worktree Creation
+
+Generic pattern:
+
+```bash
+git fetch <remote> --prune
+git worktree add -b <branch> branches/<safe-branch-folder> <remote>/master
+cd branches/<safe-branch-folder>
+```
+
+For Gitea-Tools specifically:
+
+```bash
+./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`
+
+Adapt the placeholders to the project before use.

skills/llm-project-workflow/templates/merge-pr.md

@@ -0,0 +1,43 @@
+# Merge PR Prompt
+
+You are the merge operator for PR `<pr-number>` in `<repo-name>`.
+
+Hard gate:
+
+- Verify authenticated identity before reviewing or merging.
+- Verify PR author.
+- If authenticated user matches the PR author, stop immediately.
+- Merge only if assigned merge duty and reviewer-eligible.
+
+Workflow:
+
+1. Confirm PR `<pr-number>` is open and targets `<default-branch>`.
+2. Confirm the PR head is still `<reviewed-commit>` or includes it.
+3. Confirm changed files still match the reviewed file list.
+4. Confirm previous validation still applies or rerun required checks.
+5. Merge through the gated project merge workflow.
+6. Confirm remote `<default-branch>` contains the merge.
+7. Close or release linked issue `<issue-number>` according to project policy.
+8. Remove `status:in-progress` if applicable.
+9. Delete the merged remote branch if policy allows.
+10. Remove local PR branch and branch worktree only after merge is confirmed.
+11. Fetch/prune.
+12. Confirm main checkout is clean/current.
+
+Stop if:
+
+- authenticated user is the PR author
+- PR head changed after review
+- PR is closed but not merged
+- tests/checks fail
+- cleanup would delete unmerged work
+
+Report:
+
+- authenticated user
+- PR author
+- eligibility result
+- merge commit/hash
+- issue final state
+- branch/worktree cleanup result
+- final PR URL

skills/llm-project-workflow/templates/recover-dirty-worktree.md

@@ -0,0 +1,31 @@
+# Recover Dirty Worktree Prompt
+
+You are recovering repository state in `<repo-name>`.
+
+Rules:
+
+- Do not reset, delete, clean, or overwrite work unless explicitly instructed.
+- Do not edit another issue's worktree unless assigned to that issue.
+- Preserve ambiguous work before any destructive operation.
+
+Workflow:
+
+1. Run `git status --short --branch`.
+2. Identify whether dirty files belong to the current issue, another issue, or
+   unknown work.
+3. If dirty work belongs to another issue, leave it alone and use a separate
+   worktree for the current task.
+4. If an unauthorized untracked file was created, stop and report its exact path.
+5. Remove unauthorized files only when explicitly instructed.
+6. If local `<default-branch>` is ahead of `<remote>/<default-branch>`, stop and
+   report both commit hashes.
+7. If cleanup is requested, verify the branch is merged or explicitly abandoned
+   before deleting any branch or worktree.
+
+Report:
+
+- current branch
+- dirty files
+- ownership assessment
+- actions taken
+- remaining blockers

skills/llm-project-workflow/templates/review-pr.md

@@ -0,0 +1,34 @@
+# Review PR Prompt
+
+You are independently reviewing PR `<pr-number>` in `<repo-name>`.
+
+Hard gate:
+
+- Verify authenticated identity.
+- Verify PR author.
+- If authenticated user matches the PR author, stop immediately.
+- Do not approve or merge unless reviewer-eligible.
+
+Workflow:
+
+1. Create or use a separate review worktree.
+2. Fetch/prune.
+3. Confirm PR `<pr-number>` is open and targets `<default-branch>`.
+4. Confirm the PR head is `<expected-commit>` or includes it.
+5. Confirm changed files match the issue scope.
+6. Inspect the diff for correctness, secrets, unrelated behavior, and forbidden
+   changes.
+7. Run `<required-checks>`.
+8. If anything fails, leave exact blockers and do not approve.
+9. If everything passes, approve only if reviewer-eligible.
+
+Report:
+
+- authenticated user
+- PR author
+- eligibility result
+- commit reviewed
+- files changed
+- checks run and results
+- blockers or risks
+- final PR URL

skills/llm-project-workflow/templates/start-issue.md

@@ -0,0 +1,34 @@
+# Start Issue Prompt
+
+You are implementing issue `<issue-number>` in `<repo-name>`.
+
+Rules:
+
+- No repository changes unless the issue exists and is claimed.
+- Use an isolated branch worktree under `branches/`.
+- Branch from latest `<remote>/<default-branch>`.
+- Keep the change limited to issue `<issue-number>`.
+- Do not self-review or self-merge.
+
+Workflow:
+
+1. Verify the issue exists and is open.
+2. Claim it with the project in-progress label.
+3. Fetch/prune and confirm local `<default-branch>` matches
+   `<remote>/<default-branch>`.
+4. Create branch `<branch-name>` in `branches/<safe-folder-name>`.
+5. Implement only the scoped change.
+6. Run `<required-checks>`.
+7. Inspect for secrets and unrelated files.
+8. Commit, push, and open a PR.
+9. Stop before review or merge.
+
+Final handoff:
+
+- issue number/title
+- branch name
+- isolated worktree path
+- files changed
+- checks run and results
+- PR URL
+- reviewer/merge instructions