From d1d2bc250564214a92cc28fc3eca12ea21c9c18e Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Thu, 2 Jul 2026 03:26:25 -0400 Subject: [PATCH] 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) --- README.md | 4 + docs/llm-workflow-runbooks.md | 6 + skills/llm-project-workflow/SKILL.md | 190 ++++++++++++++++++ .../templates/merge-pr.md | 28 +++ .../templates/recover-bad-state.md | 32 +++ .../templates/review-pr.md | 26 +++ .../templates/start-issue.md | 29 +++ .../templates/worktree-cleanup.md | 28 +++ 8 files changed, 343 insertions(+) create mode 100644 skills/llm-project-workflow/SKILL.md create mode 100644 skills/llm-project-workflow/templates/merge-pr.md create mode 100644 skills/llm-project-workflow/templates/recover-bad-state.md create mode 100644 skills/llm-project-workflow/templates/review-pr.md create mode 100644 skills/llm-project-workflow/templates/start-issue.md create mode 100644 skills/llm-project-workflow/templates/worktree-cleanup.md diff --git a/README.md b/README.md index 32aff90..7174241 100644 --- a/README.md +++ b/README.md @@ -186,6 +186,10 @@ Notes: [`docs/llm-workflow-runbooks.md`](docs/llm-workflow-runbooks.md) for the task-scoped, profile-based runbooks (create/review/merge/close, thin launchers, migration, fail-closed rules). +- For the **portable** version of this workflow (issue-first, isolated + worktrees, no self-review/merge, profile safety, cleanup, fail-closed) that + can be copied into any project, see the reusable skill + [`skills/llm-project-workflow/SKILL.md`](skills/llm-project-workflow/SKILL.md). - **Audit logging (#18):** mutating actions emit a durable, redacted JSON audit record — timestamp, action, result (`allowed`/`blocked`/`failed`/`succeeded`), profile name + audit label, authenticated username, target repo/issue/PR, diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md index 16fda8a..0e4c9c4 100644 --- a/docs/llm-workflow-runbooks.md +++ b/docs/llm-workflow-runbooks.md @@ -7,6 +7,12 @@ package of the MCP Control Plane: creating issues, implementing them, opening and reviewing pull requests, merging, and closing out — safely and reproducibly. +> For the **project-agnostic** version of these operating rules (issue-first, +> isolated worktrees, no self-review/merge, profile safety, cleanup, fail-closed) +> that can be copied into any repository, see the reusable skill +> [`skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) +> and its `templates/`. This runbook is the Gitea-specific application of it. + These runbooks are **operational guidance only**. They add no tooling; the behavior they rely on already exists (canonical runtime profiles, the interactive setup menu, identity/eligibility checks, gated review/merge, and diff --git a/skills/llm-project-workflow/SKILL.md b/skills/llm-project-workflow/SKILL.md new file mode 100644 index 0000000..6955c38 --- /dev/null +++ b/skills/llm-project-workflow/SKILL.md @@ -0,0 +1,190 @@ +--- +name: llm-project-workflow +description: >- + 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](#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): + +```bash +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: + +```bash +git fetch --prune +git worktree add -b fix/issue-123-example branches/fix-issue-123-example /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 + +```text +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 --prune`. +3. Confirm local `master` equals remote `master` (`git rev-list --left-right --count /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 `), 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 `). +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 /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 `, 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 ` and `git log /`. + +## J. Prompt snippets + +Ready-to-copy templates live in [`templates/`](templates/): + +- [`start-issue.md`](templates/start-issue.md) — start a new issue. +- [`review-pr.md`](templates/review-pr.md) — review a PR. +- [`merge-pr.md`](templates/merge-pr.md) — merge a PR (eligible reviewer only). +- [`recover-bad-state.md`](templates/recover-bad-state.md) — recover from bad state. +- [`worktree-cleanup.md`](templates/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 | +|-------------|---------|--------------| +| `` | 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. diff --git a/skills/llm-project-workflow/templates/merge-pr.md b/skills/llm-project-workflow/templates/merge-pr.md new file mode 100644 index 0000000..f0de7dc --- /dev/null +++ b/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 # for issue # 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 #: 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 "), + 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 #, 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. +``` diff --git a/skills/llm-project-workflow/templates/recover-bad-state.md b/skills/llm-project-workflow/templates/recover-bad-state.md new file mode 100644 index 0000000..ffe5e04 --- /dev/null +++ b/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 . 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 . + +Diagnose first: +1. git fetch --prune +2. git status --short; git worktree list +3. git rev-list --left-right --count /master...master # ahead/behind +4. For any PR involved: confirm state (open/closed/merged) AND whether + /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 , THEN git reset --hard /master. Verify with + `git branch --contains ` 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. +``` diff --git a/skills/llm-project-workflow/templates/review-pr.md b/skills/llm-project-workflow/templates/review-pr.md new file mode 100644 index 0000000..6ee8833 --- /dev/null +++ b/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 # for issue #. + +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 # detached, branches/review-* + cd branches/review- +5. Confirm the worktree is clean. Inspect the FULL diff; confirm scope matches + issue #; 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. +``` diff --git a/skills/llm-project-workflow/templates/start-issue.md b/skills/llm-project-workflow/templates/start-issue.md new file mode 100644 index 0000000..64dc5eb --- /dev/null +++ b/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 . + +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 --prune; confirm local master == /master (0 0). +3. Create the issue "" (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. +``` diff --git a/skills/llm-project-workflow/templates/worktree-cleanup.md b/skills/llm-project-workflow/templates/worktree-cleanup.md new file mode 100644 index 0000000..a9ffa95 --- /dev/null +++ b/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. +```