メニュー
Create, restructure, or update technical documentation. Handles greenfield projects, refactoring non-compliant docs, and incremental updates after code changes.
| name | do-docs |
| description | Create, restructure, or update technical documentation. Handles greenfield projects, refactoring non-compliant docs, and incremental updates after code changes. |
Depends on: do-tech-docs, mav-scope-boundaries
Create, restructure, or update technical documentation. Operates in three modes depending on the current state of the project's documentation.
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-docs
The check verifies the project is initialised and uv is on PATH.
If `` specifies a mode (greenfield, refactor, or update), use it. Otherwise auto-detect:
digraph detect {
"Check docs/ exists" [shape=diamond];
"Greenfield" [shape=box];
"Audit compliance" [shape=diamond];
"Refactor" [shape=box];
"Update" [shape=box];
"Check docs/ exists" -> "Greenfield" [label="no docs/"];
"Check docs/ exists" -> "Audit compliance" [label="docs/ exists"];
"Audit compliance" -> "Refactor" [label="non-compliant or gaps"];
"Audit compliance" -> "Update" [label="compliant"];
}
docs/ does not exist or contains no technical documentation -> Greenfielddocs/ exists, audit against do-tech-docs standards. If documents are non-compliant or significant gaps exist -> RefactorStart from scratch for an undocumented project.
Determine whether the project is a mono-repo or single-repo per the do-tech-docs skill (mono-repo indicators: workspaces in package.json, pnpm-workspace.yaml, lerna.json, Cargo.toml with [workspace], go.work, multiple pyproject.toml files, nx.json, rush.json). This controls documentation placement.
Enumerate all components, services, subsystems, and cross-cutting concerns. Prioritise:
For each identified area, write documentation following the do-tech-docs skill standards (document structure, writing style, token budget, Mermaid diagrams).
Create docs/technical/index.md listing all documents with one-line descriptions. For mono-repos, also create <package>/docs/index.md for each documented package.
Run the do-tech-docs validation checklist against every document produced.
Once docs have been written and validated, record that tech-docs scaffolding has run on this project:
uv run maverick integration set tech_docs_scaffolded true
This commits the milestone into .maverick/config.json. Skip this step in update mode (which is incremental and does not represent a scaffolding milestone) — only greenfield and refactor modes flip this flag.
Bring existing non-compliant documentation up to standard.
Same as Greenfield step 0.
Same as Greenfield step 1.
Check all documentation locations based on repository type:
docs/technical/ and docs/product/docs/technical/, root docs/product/, and <package>/docs/ for every packageRead every existing document. For mono-repos, flag product/business docs found inside <package>/docs/ — these should move to root docs/product/.
Classify each document:
| Status | Action |
|---|---|
| Compliant and accurate | Leave unchanged |
| Accurate but non-compliant | Rewrite to match do-tech-docs structure and standards |
| Outdated or inaccurate | Update with verified information from current codebase |
| Redundant or overlapping | Consolidate into a single document |
Identify gaps — areas of the codebase with no documentation coverage.
Update or create docs/technical/index.md (and package-level indexes for mono-repos).
Run the do-tech-docs validation checklist against every document changed or created.
Refactor mode produces a compliant docs scaffold, so set the flag:
uv run maverick integration set tech_docs_scaffolded true
Incrementally update documentation after code changes. This is the narrowest mode — only touch what the diff affects.
Accept a diff or changed file list. Determine which existing documents are affected by the changes:
Update docs/technical/index.md only if new documents were created.
Run the do-tech-docs validation checklist against every document changed or created.
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.
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.
Install the maverick CLI tool system-wide from the plugin directory.