docs: add portable llm-project-workflow skill + templates (#46)

Extract the project's operating rules into a reusable, project-agnostic skill
so any repo can adopt the same safe LLM workflow.

- skills/llm-project-workflow/SKILL.md: issue-first; isolated branch worktrees
  (main checkout = orchestration only); distinct author/reviewer identities and
  profile safety (secrets by reference only; stop if authenticated user == PR
  author); branch naming; start/review/merge/cleanup workflows; fail-closed
  cases; recovery patterns; and an "Adapting to a project" table for the
  forge-specific names.
- templates/: copy/paste prompts for start-issue, review-pr, merge-pr,
  recover-bad-state, worktree-cleanup.
- Link the skill from README.md and docs/llm-workflow-runbooks.md (the runbook
  is framed as the Gitea-specific application of the portable skill).

Docs-only; no code, no secrets, safe placeholder examples only. No change to
MCP runtime, Gitea API, credential storage, or worktree helpers.

Checks: full suite 287 passed / 0 failures; git diff --check clean; secret scan
of skills/ clean.

Closes #46. Refs #38, #39.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,28 @@
+# Template: merge a PR (eligible reviewer only)
+
+Copy, fill the `<...>` fields, and paste as the task prompt.
+
+```text
+Task: merge PR #<pr> for issue #<n> if it is eligible and checks pass.
+
+Rules (llm-project-workflow):
+- Only an eligible, NON-author reviewer merges. If authenticated user == PR
+  author → STOP.
+- Do not merge unless the PR is open, mergeable, and its checks/review pass.
+- No force-merge, no bypassing branch protections.
+
+Steps:
+1. Verify authenticated identity + active profile.
+2. Confirm PR #<pr>: author (not you), state open, mergeable, review approved.
+3. If any gate fails → STOP and report.
+4. Merge with explicit confirmation (e.g. confirmation="MERGE PR <pr>"),
+   optionally pinning the reviewed head SHA / changed-file set.
+5. Confirm remote master now contains the merge commit.
+
+Then run the cleanup template (worktree-cleanup.md):
+- close/release issue #<n>, remove status:in-progress
+- delete remote branch, remove local branch + worktree folder
+- fetch/prune; confirm main checkout is clean and current (0 0).
+
+Handoff: reviewer identity, merge result + commit, cleanup done, issue closed.
+```

skills/llm-project-workflow/templates/recover-bad-state.md

@@ -0,0 +1,32 @@
+# Template: recover from bad state
+
+Copy, fill the `<...>` fields, paste as the task prompt. Recovery is read-then-
+act: gather facts first, never discard unmerged work.
+
+```text
+Task: recover repo state for <situation>. Do not lose unmerged work.
+
+Rules (llm-project-workflow):
+- Fail closed: if state is unclear or a step would delete unmerged work, STOP.
+- Never push master. Never discard commits not safely pushed to <remote>.
+
+Diagnose first:
+1. git fetch <remote> --prune
+2. git status --short; git worktree list
+3. git rev-list --left-right --count <remote>/master...master   # ahead/behind
+4. For any PR involved: confirm state (open/closed/merged) AND whether
+   <remote>/master actually contains its commits ("closed" != "merged").
+
+Act per case:
+- Dirty worktree from another issue: leave it; start yours in a new worktree.
+- Local master ahead of remote: confirm the extra commits live on a branch
+  pushed to <remote>, THEN git reset --hard <remote>/master. Verify with
+  `git branch --contains <sha>` first.
+- PR closed but not merged: re-push the branch, reopen/replace the PR, let an
+  eligible reviewer merge. Do not merge your own.
+- Branch deleted before merge: recover commits from a local branch/reflog (or
+  git fsck --lost-found), re-push, reopen the PR.
+- Unauthorized untracked file: do not commit it; leave pre-existing artifacts.
+
+Handoff: what was wrong, evidence, action taken, current state, what remains.
+```

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

@@ -0,0 +1,26 @@
+# Template: review a PR
+
+Copy, fill the `<...>` fields, and paste as the task prompt.
+
+```text
+Task: review PR #<pr> for issue #<n>.
+
+Rules (llm-project-workflow):
+- Review in a SEPARATE detached review worktree, never the author's folder.
+- You must NOT be the PR author. If the authenticated user == PR author, stop.
+- Do not merge if any check fails.
+
+Steps:
+1. Verify your authenticated identity (whoami) and the active profile.
+2. Fetch the PR facts: PR author, head SHA, state (must be open), base branch.
+3. If authenticated user == PR author → STOP (no self-review).
+4. scripts/worktree-review <pr-head-branch>          # detached, branches/review-*
+   cd branches/review-<pr-head-branch-slug>
+5. Confirm the worktree is clean. Inspect the FULL diff; confirm scope matches
+   issue #<n>; flag any unrelated files, secrets, or formatting churn.
+6. Run the test suite; note results.
+7. Post the review verdict: approve only if scope is clean and checks pass;
+   otherwise request changes with specifics. Never merge from this review step.
+
+Handoff: reviewer identity, PR author, scope verdict, checks + results, decision.
+```

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

@@ -0,0 +1,29 @@
+# Template: start a new issue
+
+Copy, fill the `<...>` fields, and paste as the task prompt.
+
+```text
+Task: implement <issue title / one-line goal>.
+
+Rules (llm-project-workflow):
+- No repo changes without a tracking issue. If none exists, create one first;
+  if it can't be created, stop.
+- Work only in an isolated branch worktree under branches/. The main checkout
+  is orchestration/status only.
+- Do not self-review or self-merge.
+
+Steps:
+1. Verify the orchestration checkout is the right repo and clean.
+2. git fetch <remote> --prune; confirm local master == <remote>/master (0 0).
+3. Create the issue "<title>" (problem, scope, acceptance) and claim it
+   (status:in-progress + a "starting work" comment naming the branch).
+4. scripts/worktree-start <type>/issue-<n>-<slug>   # type = fix|feat|docs
+   cd branches/<type>-issue-<n>-<slug>
+5. Implement the narrow scope only; add/update focused tests if behavior changes.
+6. Checks: run the test suite, compile/lint changed files, git diff --check,
+   and scan the diff for secrets.
+7. Commit (issue-linked message), push the branch, open a PR to master.
+8. Stop before review/merge — you are the author.
+
+Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL.
+```

skills/llm-project-workflow/templates/worktree-cleanup.md

@@ -0,0 +1,28 @@
+# Template: clean up after merge
+
+Copy, fill the `<...>` fields, and paste as the task prompt. Only run AFTER a
+real merge is confirmed on remote master.
+
+```text
+Task: clean up branch/worktree for PR #<pr> / issue #<n> after merge.
+
+Rules (llm-project-workflow):
+- Do NOT clean up until the merge is confirmed on <remote>/master.
+- Cleanup would-delete-unmerged-work → STOP. Never --force-remove a dirty tree.
+
+Steps:
+1. git fetch <remote> --prune
+2. Confirm <remote>/master contains the merge of PR #<pr>
+   (git log <remote>/master | grep the merge, or git branch -r --contains <sha>).
+   If not merged → STOP; run the recovery template instead.
+3. Close issue #<n> if not auto-closed; remove the status:in-progress label.
+4. scripts/worktree-clean --delete-branch <type>/issue-<n>-<slug>
+   (removes branches/<type>-issue-<n>-<slug>; refuses if dirty; git branch -d is
+   safe-delete only — fails on unmerged.)
+5. Delete the remote branch if the merge did not already remove it.
+6. From the main checkout: git fetch <remote> --prune; git checkout master;
+   git reset --hard <remote>/master ONLY if local master safely matches remote.
+7. Confirm main checkout clean and current (git status; 0 0 vs <remote>/master).
+
+Handoff: merge confirmed, issue closed, branch+worktree removed, checkout clean.
+```