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.
|
||||
Reference in New Issue
Block a user