docs: add portable LLM workflow skill
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user