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

Template: start a new issue

Copy, fill the <...> fields, and paste as the task prompt.

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:
0. Work Selection Rule — before any claim, branch, or file edits, acquire or
   verify a work lease. Required checks: list open PRs; search PRs linked to
   the target issue; search local/remote branches for the issue number; search
   registered worktrees for the issue branch; check dirty worktrees; check
   active leases or recent handoffs; check whether a merged PR already
   completed the issue. If another session owns the lease, stop (continue only
   as lease owner, review the existing PR, hand off, request takeover after
   expiry, or report "work already claimed"). Never open a parallel branch/PR
   unless the old branch is proven abandoned and takeover is recorded.
1. Identity Checklist: Before claiming work, verify and state:
   - Required identity/profile for this task: author (allowed to push branches / create PRs)
   - Current authenticated identity (from whoami): <username>
   - Target task role: author/work identity
   *If the current identity does not match the required role (or lacks push/PR permissions), STOP before claiming the issue. Relaunch/switch to the correct profile first.*
2. Verify the orchestration checkout is the right repo and clean.
3. git fetch <remote> --prune; confirm local master == <remote>/master (0 0).
4. Create the issue "<title>" (problem, scope, acceptance) and claim it
   (status:in-progress + a "starting work" comment naming the branch).
5. scripts/worktree-start <type>/issue-<n>-<slug>   # type = fix|feat|docs
   cd branches/<type>-issue-<n>-<slug>
6. Implement the narrow scope only; add/update focused tests if behavior changes.
7. Checks: run the test suite, compile/lint changed files, git diff --check,
   and scan the diff for secrets. Record the branch name and HEAD SHA at
   validation time.
8. Branch proof before commit (#177) — prove and state:
   - git branch --show-current == the intended issue branch from step 5
   - the branch is NOT master/main/develop/development/dev
   - branch and HEAD unchanged since step 7 (another session can switch a
     shared checkout mid-session; if drift is detected, STOP and reconcile
     before committing)
   If a commit accidentally lands on a protected branch: do NOT push;
   report the accident and the exact repair steps — never silently continue.
9. Commit (issue-linked message). Branch proof before push (#177): local
   branch == push target branch == intended issue branch, none protected.
   Then push the branch and open a PR to master.
   *The PR body MUST use closing keywords like `Closes #N` or `Fixes #N` to close the issue; do NOT use `Implements #N` or `Refs #N` for closing, as Gitea will not auto-close it.*
   Include an "LLM Handoff Metadata" block in the PR body (attribution only;
   never an eligibility input — docs/llm-agent-sha.md):

   LLM Handoff Metadata:
   - LLM-Agent-SHA: llm-<12 lowercase hex, e.g. llm-8f3a9c2d6b41>
   - LLM-Role: implementer
   - Authenticated-Gitea-User: <whoami result>
   - MCP-Profile: <profile name>
   - Branch: <branch>
   - Worktree: <worktree path>
   - Self-review allowed: no
10. Stop before review/merge — you are the author.

Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
§K (compact; long form only on the high-risk triggers), including the author
role fields: Selected issue, Claim/comment status, PR number opened, and an
explicit "No review/merge:" confirmation — plus branch, worktree path, files
changed, checks + results. Next line: "Review needed — PR is open". Reports
missing the handoff are downgraded (review_proofs.assess_controller_handoff).