# Issue Workflow

> Fetch a GitHub issue and run the full grooming → implementation → review → QA pipeline.

- Skill: `wp-media/issue-workflow` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add wp-media/issue-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wp-media/issue-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: wp-media (https://skillmd.com/u/wp-media)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wp-media/issue-workflow

---


# Issue Workflow

## Config loading

Read `.claude/maestro.json` to resolve project-specific values:
- `{TEMP_ROOT}` = `.ai.temp_root`
- `{REPO}` = `.ai.repo`
- `{SLUG}` = `.ai.slug`
- `{E2E_URL}` = `.ai.e2e.local_url`
- `{E2E_BOOT}` = `.ai.e2e.boot_cmd`
- `{E2E_SETTINGS}` = `.ai.e2e.settings_path`
- `{E2E_CI}` = `.ai.e2e.ci_integration`

Repository: `{REPO}` (from `.claude/maestro.json`)

When the user asks to work on an issue by number, such as:
- `/task 123`
- `issue 123`
- `#123`

follow this workflow. The orchestrator runs **inline in this conversation** — read the
user's opening message before kicking it off, since it uses that for escalation
calibration (high autonomy / standard / high oversight).

## Tooling

Use shell commands as the primary approach. The GitHub MCP (`mcp_github_*`) may be used if it is connected — but shell is always the safe fallback and is preferred for reliability.

| Operation | Shell (primary) | GitHub MCP (if connected) |
|---|---|---|
| Issue fetch | `bash .claude/skills/issue-workflow/scripts/issue-sync.sh <N>` | `mcp_github_github_issue_read` |
| Branch creation | `bash .claude/skills/issue-workflow/scripts/make-issue-branch.sh` | — |
| Staging & committing | `git add` / `git commit` | — |
| Pushing | `git push -u origin <branch>` | — |
| PR creation | `gh pr create` | `mcp_github_github_create_pull_request` |
| CI monitoring | `gh pr checks <PR#>` | `mcp_github_github_pull_request_read` |

## Steps

1. **Extract** the issue number from the user's message.

2. **Fetch the issue** — run `bash .claude/skills/issue-workflow/scripts/issue-sync.sh <N>` (or use the MCP equivalent). Read the resulting file at `{TEMP_ROOT}/issues/<N>/issue.md`.

3. **Check for parent epics** — if `Parent Epic (GitHub)` or `Parent Epics (Task List)` has entries, sync each parent with `issue-sync.sh <epic-N>` and read those files at `{TEMP_ROOT}/issues/<epic-N>/issue.md` for context.

4. **Check if this is an Epic** — if the issue has label `epics`, Issue Type `EPIC`, or has sub-issues listed, ask the user: "Work the epic as a whole, or a specific sub-issue?" If a sub-issue is chosen, sync it and proceed with the epic context in mind.

5. **Determine base branch** — default is `origin/develop` unless the user specified otherwise.

6. **Invoke the `orchestrator` skill inline** (do not spawn it as a sub-agent — it runs in this conversation context so it can read the user's intent for escalation calibration):
   > Inputs: issue number `N`, issue file `{TEMP_ROOT}/issues/<N>/issue.md`, base branch

The orchestrator skill manages everything from here: calibration → grooming → spec review → dispatch → implementation → lead review → push & PR → CI → QA → finalize. It spawns the specialist agents (`grooming-agent`, `challenger`, `backend-agent`, `frontend-agent`, `release-agent`, `lead-reviewer`, `qa-engineer`, `ticket-writer`) as isolated sub-agents, but the orchestrator itself stays inline so it can surface decisions back to the user naturally.

Monitor progress at `{TEMP_ROOT}/issues/<N>/workflow-log.html`.