메뉴
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.
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.
Install the maverick CLI tool system-wide from the plugin directory.
| name | do-init |
| description | 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. |
| user-invocable | true |
Set up the current repository for Maverick — install the CLI if needed, validate the Maverick GitHub App, write the project-level config, scaffold docs and project skills, run the cybersecurity audit, then commit everything and open a pull request for the user to approve.
Dispatch the agent-maverick agent with task init and any user-provided arguments. The agent will follow the process below and return a structured result.
Run command -v maverick to check whether the CLI is already on PATH.
If maverick is not on PATH, dispatch the /maverick:do-install skill and wait for it to complete. After the install returns, re-run command -v maverick to confirm the binary is now resolvable. If it still is not (e.g. ~/.local/bin is not on the user's PATH), report the install message verbatim to the user and stop — they need to fix PATH and re-invoke /maverick:do-init manually.
If maverick is on PATH, verify the installed CLI matches the loaded plugin. A stale binary from an earlier plugin version can be missing subcommands the rest of this skill depends on (e.g. maverick integration, maverick preflight).
maverick --versiongrep -Po '(?<=^version = ")[^"]+' "${CLAUDE_PLUGIN_ROOT}/pyproject.toml"uv tool install --force from the plugin root, so it overwrites whatever is currently installed. After it returns, re-run maverick --version and confirm it now matches the plugin version. If it still does not, surface the mismatch to the user and stop.do-init cannot complete without a CLI version that matches the plugin. The remaining steps invoke maverick directly and depend on subcommands that may have been added in newer versions.
Run:
uv run maverick preflight do-init
This runs the same gh_app_configured runtime check the issue-driven
workflows enforce. If it exits non-zero, halt do-init immediately and
report the stderr output verbatim to the user. The remaining steps make
file changes and open a PR; running them on a machine without a working
GitHub App is wasted work because nothing downstream of do-init will
function until the App is set up.
Maverick does not create the GitHub App. That is a manual human action. If preflight fails, surface this to the user verbatim:
The Maverick GitHub App is not configured. Maverick cannot create it for you — you need to do this manually before re-running
/maverick:do-init.
Create a new GitHub App at https://github.com/settings/apps/new with these permissions: contents: read, metadata: read, pull-requests: write, issues: write.
Generate and download a private key for the App. Save it to
~/.maverick/maverick-gh-app.pem(or any path you prefer).Install the App on the repo(s) you want Maverick to operate on. Note the
installation_idfrom the install URL.Add a
gh_appblock to~/.maverick/config.json:{ "gh_app": { "app_id": <integer>, "installation_id": <integer>, "private_key_path": "~/.maverick/maverick-gh-app.pem" } }Verify with
maverick gh-app status— it should print"configured": true.Re-run
/maverick:do-init.
Run:
uv run maverick init
This detects the project's tech stack, writes .maverick/config.json with the detected modules and a fresh integration block (init: true, all other flags false), and prints a summary of what was detected. If a config already exists, the command preserves any integration flags that are already true — re-running is safe.
Write .maverick/settings.json containing {} if the file does not already exist. This is where project-specific overrides go later; an empty object is the correct default. Do not overwrite an existing file.
Dispatch /maverick:do-docs. The greenfield mode of that skill flips integration.tech_docs_scaffolded to true automatically when it completes.
Dispatch /maverick:do-upskill. It iterates every topic in topics.json and writes per-topic skills under docs/maverick/skills/, then flips integration.upskill to true.
Dispatch /maverick:do-cybersecurity-review. It scans the existing codebase for common security risks (secrets, dependency vulnerabilities, auth/input-validation patterns), writes findings to docs/security-audit.md, and flips integration.cybersecurity_reviewed to true. The review is surface-only — it reports, it does not modify code. Any FAIL findings should be tracked as follow-up issues by the user.
The earlier steps wrote a number of new and modified files. Commit them on a fresh branch and open a PR for the user to approve.
Sanity-check the working tree. Run git status --porcelain. The only changed paths should be:
.maverick/config.json, .maverick/settings.jsondocs/maverick/skills/... (from do-upskill)docs/... content created by do-docs greenfielddocs/security-audit.md (from do-cybersecurity-review)If git status shows changes outside these paths, abort and report to the user — they have unrelated uncommitted work that should be handled first.
Resolve base + branch. Capture the current branch as the PR base:
base="$(git branch --show-current)"
Choose a branch name chore/maverick-init. If a branch with that name already exists locally or on origin, abort and tell the user — a previous init attempt may be in-flight.
Create the branch and stage maverick paths only.
git checkout -b chore/maverick-init
git add .maverick/
[ -d docs/maverick ] && git add docs/maverick/
[ -f docs/security-audit.md ] && git add docs/security-audit.md
# Stage anything else under docs/ that do-docs greenfield created.
git add -u docs/ && git add docs/
Do not use git add -A or git add . — the goal is to stage only what do-init produced, not anything the user happened to leave in the tree.
Commit with a conventional message:
git commit -m "chore: initialise Maverick"
Push and open the PR:
git push -u origin chore/maverick-init
gh pr create --base "$base" \
--title "chore: initialise Maverick" \
--body "$(cat <<'EOF'
## Summary
This PR was generated by `/maverick:do-init`. Review the changes and merge when ready.
### What's in this PR
- `.maverick/` — project config and integration tracking
- `docs/maverick/skills/` — generated project-specific skills
- `docs/security-audit.md` — initial cybersecurity audit findings (review FAIL items)
- Other `docs/` content scaffolded by `do-docs`
### Verify after merge
```bash
uv run maverick integration get
EOF )"
Capture the PR URL from the gh pr create output and pass it through to the report in the next step.
Print a final summary to the user:
uv run maverick integration getagent-code-reviewer subagent during do-issue-solo / do-epic. If the project later wants the optional CI-side gate (multi-machine workflows, untrusted environments, audit needs), point the user at mav-bp-remote-code-review for the manual scaffold steps.The integration checklist gives the user (and any future Maverick session) a clear view of what's been completed and what's still pending.