mav-github-issue-workflow

name	mav-github-issue-workflow
description	Standard patterns for interacting with GitHub issues — reading, commenting, updating, state tracking, branching, and PR creation. Use as a dependency from workflow skills, not directly.
user-invocable	false
disable-model-invocation	true

GitHub Issue Workflow Patterns

Reusable patterns for GitHub issue interactions. Workflow skills (e.g., do-issue-guided, do-issue-solo) reference this skill for consistent GitHub operations.

Issue State

The maverick-task-progress marker on the GitHub issue is the single state surface for issue-driven work. It records the current phase, the working branch, and the artefact comment ids — durable on GitHub, shared across instances, written only through the CLI. There is no local state file; anything local is a derivable cache.

Read it:

uv run maverick task-progress read <repo> <issue>

Write phase checkpoints (merge semantics — accreted fields like the branch and comment ids survive):

uv run maverick task-progress set <repo> <issue> <phase>
uv run maverick task-progress set <repo> <issue> branch --branch feat/42-add-export
uv run maverick task-progress set <repo> <issue> tasks --has-sub-issues

Never compose or edit the marker comment by hand — the CLI owns the schema. For marker kinds without a dedicated verb, use uv run maverick gh-state write.

Reading an Issue

Always fetch structured JSON to get the full picture including comments.

gh issue view $ISSUE_NUMBER --json title,body,labels,assignees,milestone,comments,state

Reading Specific Fields

# Just the body
gh issue view $ISSUE_NUMBER --json body -q '.body'

# Labels as comma-separated list
gh issue view $ISSUE_NUMBER --json labels -q '[.labels[].name] | join(", ")'

Posting Artefact Comments

One comment per artefact — design, plan, tasks, completion. Post and update them only through the CLI, which returns the comment id from the API response (never scraped from output that may carry warnings) and records it in the task-progress marker automatically:

# Post (body from a file, or '-' for stdin)
uv run maverick issue comment post <repo> <issue> --kind design --body-file /tmp/design.md

# Revise later — updates the same comment, keeping one artefact per kind
uv run maverick issue comment update <repo> <issue> --kind design --body-file /tmp/design-v2.md

Identity

The CLI posts as the Maverick GitHub App when configured, so Maverick-generated comments are visually distinct from the human user's. Plain gh is fine for read operations.

Failure modes:

• App not configured — the CLI falls back to the user's gh credentials automatically. Acceptable for solo / ad-hoc use; the fallback applies to the whole session, never per-call.
• App configured but missing issues:write or pull_requests:write — the call fails with HTTP 403. This is a setup error: stop and tell the user to grant the permission via the GitHub App settings, then re-run. Do not retry as the human user.

Artefact templates

Design (--kind design):

## Solution Design

### Approach
<high-level description>

### Areas Affected
- <list of packages/files>

### Key Decisions
- <architectural choices and rationale>

### Risks / Open Questions
- <anything that might complicate implementation>

---
*Posted by Claude Code*

Plan (--kind plan): numbered steps, each with Files / Change / Verify lines.

Completion (--kind completion): branch name, summary of changes, verification status.

Branching

Follow the mav-git-workflow skill for branch naming conventions, base branch identification, and branch creation. After creating the branch, record it:

uv run maverick task-progress set <repo> <issue> branch --branch "$BRANCH_NAME"

Pull Requests

Create PR Referencing the Issue

PR_TARGET=$(uv run maverick git-workflow pr-target)
git push -u origin $BRANCH

gh pr create --base "$PR_TARGET" --title "<concise title>" --body "$(cat <<PR_EOF
## Summary
<1-3 bullet points>

Closes #$ISSUE_NUMBER

## Test Plan
- [ ] <verification steps>

---
*Created by Claude Code*
PR_EOF
)"

Closes #N must appear in the PR body and survive into the squash commit body — in squash-merge repos GitHub scans the commit that lands on the default branch, not the PR description at click-time (#56). Whether the PR body becomes the squash body depends on the repository's squash-commit default ("PR title and description" vs "commit details"); do not rely on it. do-issue-solo re-verifies the PR body before merging, and maverick issue close-on-merge closes the issue explicitly either way — GitHub's keyword auto-close is a bonus, not the mechanism.

Resuming Work

When resuming work on an issue (new session, after crash, subagent picking up), do not reconstruct state by hand — ask the CLI:

uv run maverick coord resume-point <repo> <issue>

It reads the task-progress marker, finds the PR via the recorded branch, inspects CI and the review verdict, and returns {next, instruction, evidence}. Follow the instruction. If the evidence contradicts what you observe locally, GitHub wins — local files are a cache.