thermiteau/mav-github-issue-workflow

Depends on: mav-git-workflow

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 File

Maintain a local state file at .claude/issue-state.json to track progress across sessions and subagents. This file MUST be gitignored.

Structure

{
  "issue": 42,
  "repo": "owner/repo",
  "branch": "feat/42-short-description",
  "phase": "understand|design|plan|branch|implement|complete",
  "comments": {
    "design": null,
    "plan": null,
    "completion": null
  }
}

Initialise State

Create the state file at the start of work. Infer the repo from the current git remote.

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
mkdir -p .claude
cat > .claude/issue-state.json << EOF
{
  "issue": $ISSUE_NUMBER,
  "repo": "$REPO",
  "branch": null,
  "phase": "understand",
  "comments": {
    "design": null,
    "plan": null,
    "completion": null
  }
}
EOF

Read State

cat .claude/issue-state.json

Update State Field

Use jq (or equivalent) to update individual fields:

# Update phase
jq '.phase = "design"' .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

# Update branch
jq '.branch = "feat/42-add-export"' .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

Ensure Gitignore

Before creating the state file, ensure it is gitignored:

grep -q 'issue-state.json' .gitignore 2>/dev/null || echo '.claude/issue-state.json' >> .gitignore

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(", ")'

# Comment count
gh issue view $ISSUE_NUMBER --json comments -q '.comments | length'

Posting Comments

Use one comment per artifact (design, plan, completion). Capture the comment ID so it can be updated later.

Identity

Maverick-generated comments — design, plan, tasks, completion, PR-review verdicts, and updates to any of those — are posted as the Maverick GitHub App so they are visually distinct from the human user's edits. Use uv run maverick gh-app gh -- <args> for any write that produces a comment. Plain gh is fine for read operations (gh issue view, gh api ... --jq '.body').

Failure modes — do not silently switch identity mid-workflow:

• App not configured — uv run maverick gh-app gh ... exits with code 4 and a GitHub App not configured message. For solo / ad-hoc single-machine use this is acceptable; fall back to plain gh issue comment ... (the comment will be authored by the human user). The fallback only applies to the entire session, not per-call: if the App is configured, every comment goes through it.
• App configured but missing issues:write or pull_requests:write — the underlying gh call fails with HTTP 403. This is a setup error, not a runtime fallback. Stop the workflow and tell the user to grant the permission via the GitHub App settings, then re-run. Do not retry as the human user.

Post and Capture ID

COMMENT_URL=$(uv run maverick gh-app gh -- issue comment $ISSUE_NUMBER --body "$(cat <<'EOF'
## Section Title

Content here

---
*Posted by Claude Code*
EOF
)" 2>&1)

Extract the comment ID from the URL for later updates:

# gh issue comment prints the URL to stdout, extract the numeric ID
COMMENT_ID=$(echo "$COMMENT_URL" | grep -o '[0-9]*$')

Then save to state:

jq ".comments.design = $COMMENT_ID" .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

Post Design Comment

COMMENT_URL=$(uv run maverick gh-app gh -- issue comment $ISSUE_NUMBER --body "$(cat <<'DESIGN_EOF'
## 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*
DESIGN_EOF
)" 2>&1)

COMMENT_ID=$(echo "$COMMENT_URL" | grep -o '[0-9]*$')
jq ".comments.design = $COMMENT_ID | .phase = \"design\"" .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

Post Plan Comment

COMMENT_URL=$(uv run maverick gh-app gh -- issue comment $ISSUE_NUMBER --body "$(cat <<'PLAN_EOF'
## Implementation Plan

1. **Step name**
   - Files: `path/to/file.ts`
   - Change: <what the change does>
   - Verify: <test command or check>

2. **Step name**
   - Files: `path/to/file.ts`
   - Change: <what the change does>
   - Verify: <test command or check>

---
*Posted by Claude Code*
PLAN_EOF
)" 2>&1)

COMMENT_ID=$(echo "$COMMENT_URL" | grep -o '[0-9]*$')
jq ".comments.plan = $COMMENT_ID | .phase = \"plan\"" .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

Post Completion Comment

BRANCH=$(jq -r '.branch' .claude/issue-state.json)

COMMENT_URL=$(uv run maverick gh-app gh -- issue comment $ISSUE_NUMBER --body "$(cat <<DONE_EOF
## Implementation Complete

**Branch:** \`$BRANCH\`

### Changes Made
- <summary of changes>

### Verification
- [ ] Linting passes
- [ ] Tests pass

---
*Posted by Claude Code*
DONE_EOF
)" 2>&1)

COMMENT_ID=$(echo "$COMMENT_URL" | grep -o '[0-9]*$')
jq ".comments.completion = $COMMENT_ID | .phase = \"complete\"" .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

Updating Comments

When a design or plan is revised, update the existing comment instead of posting a new one. Read the comment ID from the state file.

REPO=$(jq -r '.repo' .claude/issue-state.json)
COMMENT_ID=$(jq -r '.comments.design' .claude/issue-state.json)

uv run maverick gh-app gh -- api "repos/$REPO/issues/comments/$COMMENT_ID" \
  -X PATCH \
  -f body="$(cat <<'EOF'
## Solution Design (Revised)

<updated content>

---
*Posted by Claude Code*
EOF
)"

The update goes through the same App identity as the original post, so the comment author stays consistent across edits.

Branching

Follow the mav-git-workflow skill for branch naming conventions, base branch identification, and branch creation.

After creating the branch, save to state:

jq ".branch = \"$BRANCH_NAME\" | .phase = \"branch\"" .claude/issue-state.json > .claude/issue-state.tmp && mv .claude/issue-state.tmp .claude/issue-state.json

Pull Requests

Create PR Referencing the Issue

ISSUE_NUMBER=$(jq -r '.issue' .claude/issue-state.json)
BRANCH=$(jq -r '.branch' .claude/issue-state.json)
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
)"

Using Closes #N in the PR body automatically closes the issue when the PR is merged.

Resuming Work

When resuming work on an issue (new session, after crash, subagent picking up):

digraph resume {
    "State file exists?" [shape=diamond];
    "Read state file" [shape=box];
    "Read phase" [shape=box];
    "Continue from current phase" [shape=box];
    "Ask user for issue number" [shape=box];
    "Initialise state" [shape=box];

    "State file exists?" -> "Read state file" [label="yes"];
    "State file exists?" -> "Ask user for issue number" [label="no"];
    "Read state file" -> "Read phase";
    "Read phase" -> "Continue from current phase";
    "Ask user for issue number" -> "Initialise state";
    "Initialise state" -> "Continue from current phase";
}

1. Check if .claude/issue-state.json exists
2. If yes — read it, resume from the recorded phase
3. If no — this is a fresh start, initialise the state file
4. If comment IDs are present, verify they still exist on the issue before updating

Cleanup

After the PR is created and the workflow is complete:

rm .claude/issue-state.json

Do not delete the state file until the PR is successfully created, as it is needed for crash recovery.

<!-- maverick-plugin-version: 3.3.6 -->