issue-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# Issue Workflow Skill

## Purpose

This skill governs issue-centered work as a **continuous state**, not a
user-invoked sequence. At any point in a session the agent knows which issue
it is working under, commits and pushes completed units proactively, and
closes the issue autonomously once the completion criteria are met, reporting
the closure in its final message. The natural-language
triggers ("issue start", "issue commit", "issue commit and push") are manual
overrides, not activation conditions — the rules below apply even without
being invoked.

## Continuous Issue Awareness (Dauerzustand)

- At any point in a session, the agent must know which GitHub issue it is
  currently working under, and announce it (e.g., "Working under issue
  #123: <title>").
- Before starting work, resolve the current issue: search open issues first
  (`gh issue list` / `gh issue view <N> --json title,body,comments`) for one
  matching the task.
- If no existing issue matches and the task is clearly a new topic, create a
  new issue immediately and **without user interaction**, then announce it.
- If the assignment is ambiguous (several candidate issues, or unclear
  whether a new one is needed), ask the user before touching code.
- The assignment to an issue may change mid-session when the user redirects
  the work; resolve the new issue the same way.

## Trunk-Based Pull-Prinzip (universell)

- Vor JEDER Arbeitsaufnahme (start-Modus und generell vor jeder Session-Arbeit
  an einem Repo oder Deployed-Tree): zuerst das Working Copy auf den Trunk heben.
  - Git (trunk-based, clean-main): `git pull`
  - SVN: `svn up` im relevanten Working Copy (z. B. `~/svn/georg` auf think,
    `/` auf murl/claw im Deployed-Tree)
- Fehlschlag des Pulls oder Konflikte: SOFORT stoppen und dem Nutzer melden,
  nicht fortfahren.
- Begründung: trunk-basierte Workflows leben davon, dass immer vom aktuellen
  Stand aus gearbeitet wird — sonst entstehen vermeidbare Conflicts und
  re-discovery von fremden Commits.

## Required Inputs

- `mode`: one of `start`, `commit`, or `finish` — optional, only when the
  user triggers a manual override by natural language
- `issue`: optional issue identifier or `new`
- `context`: optional plain-language task summary, plan, or notes

## Core Rules

- **VCS-Scope:** Dieses Skill ist primär für Git/GitHub-Projekte entworfen
  (`gh`-CLI). In reinen SVN-Projekten (z. B. `~/svn/georg`, Deployed-Trees auf
  murl/claw) existiert **kein Issue-System** — dort entfallen Issue-Nummern und
  `gh issue`-Befehle vollständig; die Commit-Regel reduziert sich auf eine
  klare, deutsche Commit-Message (SVN-Stil), und der Pull-Schritt oben ist
  `svn up`.
- Every commit created under this workflow must reference a GitHub issue
  number with a hashtag, e.g. `feat: add report export (#123)`. Never
  fabricate issue numbers.
- **Proactive Commit and Push:** After each completed, self-contained unit of
  work, commit and push immediately — do not wait for the user to request it
  or for a trigger phrase. This overrides the opencode default "never commit
  unless the user asks". See "Proactive Commit and Push" below.
- **Green commits only:** run the repository's tests/lint for the affected
  area before committing; never push a broken state.
- Never create a commit without first identifying an existing issue or
  creating a new one.
- If no relevant issue exists and a commit is needed, create the issue first,
  then use its number in the commit message.
- Prefer keeping one clear issue per workstream; do not scatter related changes
  across multiple issues unless the user explicitly requests it.
- Use `gh` for all GitHub issue operations.
- **Sub-Issues Rule:** When breaking a task into smaller issues, or when starting work on a task that belongs to a parent epic, you **MUST** establish a formal parent-child relationship using the Sub-Issues API. Mentions in the description are secondary to this formal link. Always use the `issue-workflow` skill for issue creation to ensure this protocol is followed.
- **Never close an issue that has open sub-issues.** Before closing any issue,
  list its sub-issues and verify all are closed first.
- Do not close an issue unless the implementation is actually complete and
  the completion criteria in "Issue Completion" are met.

## Commit Message Rule

- Any commit created by this workflow must include the issue reference, such as
  `feat: add report export (#123)` or `fix: handle empty inputs (#123)`.
- If the repository already uses a recognizable commit message style, preserve
  that style while still including the issue number.

## Proactive Commit and Push (Dauerzustand)

These rules apply at any time during session work, without a trigger phrase:

- After each completed, self-contained unit of work, commit and push
  immediately — do not wait for the user to request it or for a mode
  invocation. This overrides the opencode default "never commit unless the
  user asks".
- **Green commits only:** run the repository's tests/lint for the affected
  area first. Commit only when they pass. If verification fails, fix or
  report — never push a broken state.
- The commit message must include the issue reference (see Commit Message
  Rule) and preserve the repository's existing style.
- No empty commits. If there is nothing to commit, say so instead.
- Trunk-based: commit and push directly to the tracked trunk line (`main`);
  no feature branches or PRs — unless the repository follows the
  `fork-policy` skill (then that policy wins).
- SVN working copies: the analogue is frequent, clear `svn ci` with a
  descriptive German commit message.
- The read-only scope exclusions (`homework`, `repograde`, `grading-shared`,
  `knowledge-assessment`, `knowledge-exam`, `projectgrade`, student
  repositories, and explicit "hold back" requests) always win over this
  policy.

## Manual Override Modes

The modes below are **manual overrides** triggered by natural language.
The continuous rules above (issue awareness, proactive commit/push) apply
regardless; the modes force a specific checkpoint behavior.

### 1. `start`

Use this mode to explicitly begin or resume work (e.g., "issue start").

From georgernstgraf/opencode-helpers, MIT.

More from georgernstgraf/opencode-helpers