diff --git a/README.md b/README.md index 32aff90..ce27439 100644 --- a/README.md +++ b/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. +### 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. +
Codex / non-MCP tools diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md index 16fda8a..cb19156 100644 --- a/docs/llm-workflow-runbooks.md +++ b/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. diff --git a/skills/llm-project-workflow/SKILL.md b/skills/llm-project-workflow/SKILL.md new file mode 100644 index 0000000..f82a8af --- /dev/null +++ b/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 --prune +git worktree add -b branches/ /master +cd branches/ +``` + +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. 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..38daf1b --- /dev/null +++ b/skills/llm-project-workflow/templates/merge-pr.md @@ -0,0 +1,43 @@ +# Merge PR Prompt + +You are the merge operator for PR `` in ``. + +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 `` is open and targets ``. +2. Confirm the PR head is still `` 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 `` contains the merge. +7. Close or release linked issue `` 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 diff --git a/skills/llm-project-workflow/templates/recover-dirty-worktree.md b/skills/llm-project-workflow/templates/recover-dirty-worktree.md new file mode 100644 index 0000000..d8d54b3 --- /dev/null +++ b/skills/llm-project-workflow/templates/recover-dirty-worktree.md @@ -0,0 +1,31 @@ +# Recover Dirty Worktree Prompt + +You are recovering repository state in ``. + +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 `` is ahead of `/`, 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 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..f29e28d --- /dev/null +++ b/skills/llm-project-workflow/templates/review-pr.md @@ -0,0 +1,34 @@ +# Review PR Prompt + +You are independently reviewing PR `` in ``. + +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 `` is open and targets ``. +4. Confirm the PR head is `` 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 ``. +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 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..3cf673c --- /dev/null +++ b/skills/llm-project-workflow/templates/start-issue.md @@ -0,0 +1,34 @@ +# Start Issue Prompt + +You are implementing issue `` in ``. + +Rules: + +- No repository changes unless the issue exists and is claimed. +- Use an isolated branch worktree under `branches/`. +- Branch from latest `/`. +- Keep the change limited to issue ``. +- 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 `` matches + `/`. +4. Create branch `` in `branches/`. +5. Implement only the scoped change. +6. Run ``. +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