Menu
Work on a GitHub issue interactively with the user. Proceeds autonomously through routine work but pauses for confirmation at key decision points and when uncertain.
| name | do-issue-guided |
| description | Work on a GitHub issue interactively with the user. Proceeds autonomously through routine work but pauses for confirmation at key decision points and when uncertain. |
| argument-hint | issue number (e.g., 123) |
| user-invocable | true |
| disable-model-invocation | false |
Depends on: mav-scope-boundaries, mav-git-workflow, mav-github-issue-workflow, mav-create-solution-design, mav-create-tasks, mav-plan-execution, mav-local-verification, mav-bp-cicd, mav-claude-code-recovery, mav-bp-logging, mav-bp-alerting, mav-systematic-debugging, do-docs, do-cybersecurity-review, do-pullrequest-review
Work on GitHub issue `` interactively. Follow every phase in order. Do not skip phases. Proceed autonomously through routine work, but pause for user confirmation at key decision points marked with 🔲 Checkpoint.
Run this first. If it exits non-zero, halt and report the stderr output to the user verbatim. Do not proceed.
uv run maverick preflight do-issue-guided
The check verifies the project is initialised and required tools (gh, git, uv) are on PATH. PR code review runs locally as the agent-code-reviewer subagent (see Phase 6); the optional CI-side re-run described in mav-bp-remote-code-review is not required.
If `` is empty or not a valid issue number, ask the user for the issue number before proceeding. Do not attempt any phase without it.
Run Phases 1 and 2 as a subagent to keep the main context window clean for implementation.
guided.claude/issue-state.json has phase set to design.claude/issue-state.json has comments.design set to a comment ID🔲 Checkpoint — Design review: Present a brief summary of the solution design to the user. Include the key approach, main components affected, and any trade-offs. Ask the user to confirm or suggest changes before proceeding. Do not continue until the user approves.
Run Phase 3 as a subagent to keep the main context window clean for implementation.
.claude/issue-state.json.claude/issue-state.json has phase set to tasks.claude/issue-state.json has comments.tasks set to a comment ID.claude/issue-state.json has has_sub_issues set to true🔲 Checkpoint — Tasks review: Present the task list to the user — each task title and description, their order, and any dependencies. Ask the user to confirm, reorder, add, or remove tasks. Do not continue until the user approves.
STORY_BASE=$(uv run maverick git-workflow story-base)
$STORY_BASE.branch in the state file.docs/maverick/skills/. For each topic directory that contains a SKILL.md, read it. These project skills provide codebase-specific guidance (libraries, patterns, configuration) that supplements the best-practice skills. If none exist, continue without them.implement in the state file.If .claude/issue-state.json has has_sub_issues: true:
Otherwise (checklist tasks):
- [ ] to - [x])Follow the mav-plan-execution skill for the execution loop, verification discipline, failure handling, and crash recovery. In guided mode, it will:
git diff $(uv run maverick git-workflow story-base)...HEAD).review in the state file.🔲 Checkpoint — Review results: Present a summary of the review outcome to the user — what was flagged, what was fixed, and what was pushed back on. If there were significant changes during review, highlight them.
This phase always runs before push. The agent decides whether any docs work is needed; the workflow does not skip the analysis based on its own heuristic.
The agent is dispatched with a pre-filtered shortlist of docs the diff plausibly touches, not the open-ended "audit every doc" brief. On prior issues the unbounded brief ate ~6 min of wall clock on a 15-file diff. The agent still reports any out-of-shortlist docs it believes are impacted; those surface as a follow-up note for you to review.
Compute the diff and changed paths:
BASE=$(uv run maverick git-workflow story-base)
git diff "origin/${BASE}...HEAD" > /tmp/diff.patch
git diff --name-only "origin/${BASE}...HEAD" > /tmp/changed-paths.txt
Build the candidate doc shortlist. Derive search terms from the
diff (basenames + top-level directories from changed paths, plus
identifier-like tokens introduced or removed in added/removed lines).
Grep every docs/ tree in the repo. An empty shortlist is valid.
{
cut -d/ -f1 /tmp/changed-paths.txt
sed 's|.*/||; s|\.[^.]*$||' /tmp/changed-paths.txt
grep -E '^[+-][^+-]' /tmp/diff.patch \
| grep -Eo '\b(function|def|class|interface|type|const|export)[[:space:]]+[A-Za-z_][A-Za-z0-9_]+' \
| awk '{print $NF}'
} | awk 'length($0) >= 3' | sort -u > /tmp/doc-terms.txt
mapfile -t DOC_ROOTS < <(find . -type d -name docs \
-not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.venv/*')
: > /tmp/doc-shortlist.txt
if [[ ${#DOC_ROOTS[@]} -gt 0 && -s /tmp/doc-terms.txt ]]; then
while IFS= read -r term; do
grep -rlF -- "$term" "${DOC_ROOTS[@]}" 2>/dev/null || true
done < /tmp/doc-terms.txt \
| grep -E '\.(md|mdx)$' \
| sort -u > /tmp/doc-shortlist.txt
fi
Dispatch the agent-tech-docs-writer agent with:
update (per do-docs)/tmp/diff.patch/tmp/doc-shortlist.txt. If
the file is empty, pass the literal string
<empty — scan only for gaps requiring new coverage>.docs/, create the new
document.Checkpoint — Review docs outcome with the user: show what was updated or created (or the explicit no-op decision), surface any out-of-shortlist docs the agent flagged, and confirm before pushing. If updates are inaccurate or out of scope, push back and ask the agent to revise.
Commit any doc changes with a docs: conventional commit.
This phase always runs before push. Any changed code AND any code that could be impacted by the changes (callers, importers, dependents) must be reviewed by do-cybersecurity-review before the push proceeds.
git diff $(uv run maverick git-workflow story-base)...HEAD.updatecomplete in the state file.🔲 Checkpoint — Done: Present the PR URL to the user and summarise what was delivered.
feat: add rubric export (#42)).Scan a project for missing best-practice areas and implement the top recommendation for each gap. Currently covers linting and unit testing. Installs tools, writes configs, and adds CI steps.
Implement a focused code change. Use this skill as the wrapper for any implementation work so the Maverick workflow report captures what was done and so the agent applies the project's coding standards before editing. Intended to be invoked once per task from inside a do-issue-* or do-epic phase, not standalone.
Run a security audit of the project's existing codebase and write a findings report to docs/security-audit.md. Covers secrets exposure, dependency vulnerabilities, authentication and authorisation patterns, input validation, transport security, and common OWASP risks. Run as part of do-init or on demand.
Create, restructure, or update technical documentation. Handles greenfield projects, refactoring non-compliant docs, and incremental updates after code changes.
Work on a multi-story GitHub epic end-to-end. Builds a DAG from the child stories, groups them into waves, runs waves in parallel via per-story worktrees, ejects PRs that fail agent-code-review for human handling, and propagates blocks to downstream stories. Requires git worktrees.
Initialise a project for use with Maverick — verifies the GitHub App, installs the CLI if needed, writes the project config with integration tracking, scaffolds docs, generates project skills, runs an initial cybersecurity audit, then commits the changes and opens a PR.