# GoMad Documentation (Full)

> Complete documentation for AI consumption
> Generated: 2026-04-27
> Repository: https://github.com/xgent-ai/gomad

<document path="index.md">
GoMad is an agentic workflow framework for AI-driven agile development. It ships eight opinionated agent personas, a library of composable skills, and an installer that lays them into your AI IDE so you can drive a structured Analysis → Planning → Solutioning → Implementation cycle without hand-rolling prompts.

## What is GoMad?

GoMad is a lean, properly-credited hard fork of [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) that we own end-to-end. It distills the four-phase agile workflow into a small, predictable surface: each phase has a small set of `gm-*` skills, agents invoke those skills, and the installer copies them into the directories your IDE already reads.

Eight `gm-agent-*` personas cover the recurring roles in software delivery — analyst, tech-writer, pm, ux-designer, architect, scrum-master, dev, and solo-dev. They are invoked from your IDE as `/gm:agent-*` slash commands and load their persona body from your install root at runtime.

GoMad is published on npm as `@xgent-ai/gomad` and adds zero new runtime dependencies on top of BMAD's original stack. The installer is copy-only with manifest-driven upgrade cleanup, `--dry-run` previews, and timestamped backup snapshots.

## Get started

The fastest path is the install tutorial, which walks through running the interactive installer and pointing it at your project.

- [Install GoMad](./tutorials/install.md) — End-to-end installation walkthrough.
- [Quick start](./tutorials/quick-start.md) — Run your first GoMad workflow once GoMad is installed.

## Browse the docs

The docs follow the [Diataxis](https://diataxis.fr/) structure. Pick the section that matches what you are trying to do.

- [Agents reference](./reference/agents.md) — Catalog of the eight `gm-agent-*` personas and how to invoke them.
- [Skills reference](./reference/skills.md) — Catalog of the `gm-*` skills each agent can invoke.
- [Architecture](./explanation/architecture.md) — How agents, skills, and the installer fit together.
- [Contributing](./how-to/contributing.md) — Sending changes back to the GoMad repo.

## Project status

GoMad is on the v1.3 milestone (docs site, story-context skill, agent-directory relocation). Earlier v1.1 and v1.2 milestones are shipped on npm.

:::note[Live roadmap]
The authoritative roadmap lives in the repo at [.planning/ROADMAP.md](https://github.com/xgent-ai/gomad/blob/main/.planning/ROADMAP.md). It is updated as phases land and reflects the actual delivery state of the project.
:::

## Credits

GoMad is a hard fork of [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD), MIT-licensed by Brian (BMad) Madison. The full attribution and the canonical non-affiliation disclaimer live in the repository [LICENSE](https://github.com/xgent-ai/gomad/blob/main/LICENSE) and [README](https://github.com/xgent-ai/gomad/blob/main/README.md).
</document>

<document path="tutorials/install.md">
Install GoMad in your project in five minutes using `npx`. By the end you'll have the persona library, knowledge packs, and slash-command launchers wired into your repo.

## What you'll learn

- Install `@xgent-ai/gomad` from npm (or run it directly via `npx`).
- Run the interactive `gomad install` flow and pick sensible defaults.
- Understand the directory layout the installer produces under `<installRoot>/_config/`.
- Verify the install by inspecting the `files-manifest.csv` and the on-disk tree.

## Prerequisites

:::note[Prerequisites]
Node.js 20+, npm 10+, and an AI IDE that supports slash commands (Claude Code, Cursor, etc.).
:::

## Quick path

:::tip[Quick path]
`npx @xgent-ai/gomad install` — accept defaults — done.
:::

## Step 1: Choose how to install

You have two options. Pick the one that matches how committed you are to keeping GoMad in this project.

**Option A — One-shot via `npx`.** Use this when you want to try GoMad without committing it to your `package.json`. Each invocation downloads the latest version.

```bash
npx @xgent-ai/gomad install
```

**Option B — Add as a dev dependency.** Use this for projects that need a pinned version. The package lives in your lockfile and the same invocation can run repeatedly via the local binary.

```bash
npm install --save-dev @xgent-ai/gomad
npx gomad install
```

Either option drops you at the same interactive installer.

## Step 2: Run the interactive installer

The installer walks through three prompts:

- **Choose install root.** The default is `_gomad`. This is the directory where persona bodies, knowledge packs, and the manifest live. Pick something else if your project conventions require it; nothing else hardcodes this path.
- **Confirm IDE target.** Claude Code, Cursor, Codex, and any other slash-command-capable IDE you have installed are auto-detected. The installer writes launcher stubs into the matching IDE directory.
- **Confirm agent selection.** Defaults to all 8 personas (analyst, tech-writer, pm, ux-designer, architect, sm, dev, solo-dev). Deselect any you don't want.

Once you confirm, the installer copies files into your repo. The artifacts it writes are:

- Persona body files at `<installRoot>/_config/agents/<shortName>.md` — the runtime source of truth for each persona.
- Domain knowledge packs at `<installRoot>/_config/kb/<slug>/` — retrieval-friendly markdown bundles.
- Slash command launcher stubs at `.claude/commands/gm/agent-*.md` — thin entry points your IDE picks up.
- The install manifest at `<installRoot>/_config/files-manifest.csv` — the record of every file the installer wrote, used for safe upgrades.

## Step 3: Verify the install

After the installer exits cleanly, the tree under your install root should look roughly like this:

```text
_gomad/
├── _config/
│   ├── agents/
│   │   ├── analyst.md
│   │   ├── architect.md
│   │   ├── dev.md
│   │   ├── pm.md
│   │   ├── sm.md
│   │   ├── solo-dev.md
│   │   ├── tech-writer.md
│   │   └── ux-designer.md
│   ├── kb/
│   │   ├── architecture/
│   │   └── testing/
│   └── files-manifest.csv
└── _backups/   # populated on subsequent installs
```

If your IDE supports slash commands, type `/gm:` to see the launcher list.

## Common questions

**Where do persona files live?** Each persona body is at `<installRoot>/_config/agents/<shortName>.md`. The launcher stubs at `.claude/commands/gm/agent-*.md` reference these bodies at runtime.

**Can I customize a persona without losing changes on upgrade?** Yes. Place a `.customize.yaml` next to the persona file; the installer respects customization fragments during cleanup. See the contributing guide for the merge contract.

**How do I upgrade?** Re-run `npx @xgent-ai/gomad install`. The cleanup planner snapshots replaced files under `<installRoot>/_backups/<timestamp>/` before writing new ones, so you can always roll back.

## Where to next

Once the install completes, run a real workflow in the [quick start tutorial](./quick-start.md) — invoke your first persona and produce a tangible artifact in five minutes.
</document>

<document path="tutorials/quick-start.md">
Run your first GoMad workflow end-to-end. You'll invoke the Product Manager persona, draft a PRD, and see how the launcher-form slash command + persona body resolution actually works. Plan on five minutes from slash command to inspecting the artifact on disk.

## What you'll learn

- Invoke a `gm-agent-*` persona via slash command.
- Understand how the launcher loads the persona body at runtime.
- Produce your first artifact (a draft PRD).
- Know where to find the agents reference and where to go next.

## Before you start

:::note[Before you start]
You've completed the [install tutorial](./install.md). The `_gomad/` directory exists with `_config/agents/` populated.
:::

## Step 1: Pick a persona

GoMad ships 8 personas grouped across the four phases of work — analysis, planning, solutioning, and implementation. Each persona has a slash command you trigger from your IDE, a body file the launcher loads at runtime, and a set of skills it knows how to invoke.

For this walkthrough, pick `gm-agent-pm` — John, the Product Manager. He's a planning-phase persona whose primary skill (`gm-create-prd`) produces a PRD draft, which is exactly the kind of small, tangible artifact we want from a five-minute tour. The two files that matter for John on disk are:

```text
<installRoot>/_config/agents/pm.md       # persona body (loaded at runtime)
.claude/commands/gm/agent-pm.md          # launcher stub (slash command target)
```

Browse the full catalog in the [agents reference](../reference/agents.md) when you're ready to pick a different persona.

You don't need to memorize the file paths. They're shown here so you can confirm the install actually wired things up; once you trust the install, the slash command is all you'll touch day-to-day.

## Step 2: Invoke the persona

Trigger John from your IDE's slash-command palette:

```text
/gm:agent-pm
```

The launcher stub at `.claude/commands/gm/agent-pm.md` resolves the slash command, then loads the persona body from `<installRoot>/_config/agents/pm.md` on each invocation. That indirection is the contract: launchers stay tiny and IDE-friendly while the persona body remains the single source of truth, even after upgrades.

When John picks up, he greets you in character, lists his capabilities (PRD creation, validation, edits, brainstorming, brief authoring), and waits for direction. He won't break character or jump ahead — every step is yours to drive.

## Step 3: Drive your first workflow

Now ask John for an artifact. Type a prompt that names the skill and gives a tiny scope so the demo finishes inside five minutes:

> Use the `gm-create-prd` skill to draft a PRD for a daily-summary email feature.

John loads `gm-create-prd` and walks the PRD interview. `gm-create-prd` is a task skill, not a persona — it has no slash command of its own. You invoke it through the persona that owns it, which is exactly the pattern you'll use for every implementation skill.

Answer his questions briefly. The prompt scope you gave (daily-summary email) is small enough that the interview wraps up quickly. When John finishes, he writes the PRD draft to the path your project's planning convention dictates — typically a markdown file under your project's planning directory.

If a question doesn't apply, say "skip" or "not in scope" and John moves on. If you don't know an answer, say so plainly — he'd rather have an explicit "unknown" in the PRD than a fabricated detail.

## Step 4: Inspect the artifact

Open the PRD draft John produced. It's a regular markdown file, sectioned into goals, functional requirements (FR-NN format), Given/When/Then acceptance criteria, and an explicit `## Out of Scope` block. Nothing magical — just plain markdown that downstream skills (and humans) can read.

The artifact is the merge of three inputs: the persona body's instructions, the skill's template, and your prompt. See the [architecture explainer](../explanation/architecture.md) for how the runtime resolves all three on each invocation.

The PRD also doubles as the input contract for the rest of the workflow. Downstream skills like architecture, epic-and-story creation, and implementation readiness checks all consume the same FR-NN requirements and Given/When/Then acceptance criteria you just produced.

## What you got

In one short session you produced:

- Your first persona invocation — a slash command resolved through the launcher to the persona body.
- Your first task skill loaded — `gm-create-prd`, invoked through the persona that owns it.
- Your first artifact written — a draft PRD in markdown, ready to feed the rest of the workflow.

## Where to next

Three good follow-ups, in increasing depth. Browse the [skills reference](../reference/skills.md) for the full catalog of task skills you can invoke through any persona. Read the [architecture explainer](../explanation/architecture.md) to understand the 4-phase lifecycle and how launchers, persona bodies, and skills compose at runtime. When you're ready to extend GoMad with your own skills or persona tweaks, see [contributing](../how-to/contributing.md).
</document>

<document path="how-to/contributing.md">
Use the standard fork-and-PR workflow to contribute to GoMad. This page covers the test expectations every PR must meet before merge.

## When to use this guide

- You're proposing a new persona, skill, or domain knowledge pack.
- You're fixing a bug in the installer, in a tool under `tools/`, or in an existing skill.
- You're improving documentation or translations.

## Prerequisites

:::note[Prerequisites]
Node.js 20+, npm 10+, a GitHub account, and read access to the existing `CONTRIBUTING.md` at the repo root for the canonical PR template.
:::

## Step 1: Fork and clone

Fork [`xgent-ai/gomad`](https://github.com/xgent-ai/gomad) on GitHub (use the **Fork** button in the top-right of the repo page), then clone your fork and install dependencies:

```bash
git clone git@github.com:<your-username>/gomad.git
cd gomad
npm install
```

GoMad is a hard fork of BMAD Method, not a continuously-merged downstream — there is no upstream sync to keep in lockstep. Treat your fork as a working copy of `xgent-ai/gomad`.

## Step 2: Branch from main

Create a feature branch off `main` using a conventional prefix:

```bash
git switch -c feat/your-feature-name
```

Use `feat/` for new features, `fix/` for bug fixes, `docs/` for documentation changes, and `chore/` for tooling or config updates. Keep the branch name short and descriptive.

## Step 3: Make your change

Source-of-truth content lives under `src/gomad-skills/`, `src/core-skills/`, and `src/domain-kb/`. The installer copies these into the user's `<installRoot>/_config/` at install time — that's the generate-don't-move pattern, so always edit under `src/`, never under an installed copy.

For a new persona, add a `src/gomad-skills/<phase>/gm-agent-<short>/` directory containing `SKILL.md` (frontmatter `name:` plus `description:`) and `skill-manifest.yaml` (`displayName`, `title`, `icon`). For a new task skill, use the same directory layout under the appropriate phase, with only `SKILL.md` (no `skill-manifest.yaml` is needed for task skills). For documentation changes, edit files under `docs/` — the Starlight site picks up changes automatically.

See the [architecture explainer](../explanation/architecture.md) for how installer + workflow + launcher fit together at runtime.

## Step 4: Run the quality gate

Run the full quality chain locally before opening a PR:

```bash
npm run quality
```

The chain (defined in `package.json`) runs Prettier format check, ESLint, markdownlint, the docs build (link check + Astro build), the install + integration tests, file-reference validation, skills validation, the inject-reference-tables test, KB license validation, and the orphan-reference test. The gate must exit 0 before you open a PR.

:::caution[If a check fails]
Run the failing script in isolation (e.g., `npm run lint` or `npm run docs:build`) for focused output. Don't bypass the gate — the PR template asks you to confirm `npm run quality` passes locally.
:::

## Step 5: Open the PR

Push your feature branch to your fork, then open a pull request against `main` of `xgent-ai/gomad`. Reviewers will pull your branch, re-run `npm run quality`, and leave feedback on the diff.

PR title convention: `<type>(<scope>): <summary>` — for example, `feat(skills): add gm-domain-skill`. The PR body should reference any related issue or roadmap entry so reviewers can connect the change to its motivating context.

## What you get

- PR review feedback, typically within a few days.
- Once merged, your change ships in the next `@xgent-ai/gomad` npm release per the milestone schedule.
- Attribution in `CONTRIBUTORS.md` if your change is non-trivial.

## Where to learn more

For the runtime model — how the installer, skills, and launcher slash commands fit together — read the [architecture explainer](../explanation/architecture.md). For catalog examples, browse the [agents reference](../reference/agents.md) and the [skills reference](../reference/skills.md) to see how existing personas and skills are structured.
</document>

<document path="explanation/architecture.md">
GoMad is a fork of BMAD Method that ships an opinionated agile workflow as agents and skills loaded into your AI IDE.
This page explains how its three pillars fit together — the 4-phase workflow, the manifest-driven installer, and the launcher-form slash command contract.

## Overview

GoMad is a markdown-driven agentic workflow for AI-assisted software development.
It ships a coordinated set of personas, task skills, and knowledge packs that an AI IDE loads at runtime to drive a project through analysis, planning, solutioning, and implementation.

Three pillars carry the runtime story.

- The **workflow** decides *what* you do and *when* — a sequential pipeline of phases that each consume the previous phase's output.
- The **installer** decides *how* files land in your workspace — a manifest-driven copy step that emits agent personas, task skills, and launcher stubs into a user-chosen install root.
- The **launcher** decides *how* your IDE invokes a persona — a thin slash command stub that loads the persona body fresh on every invocation.

The design constraint behind all three is deliberate: zero new runtime dependencies.
The whole system is plain markdown plus a minimal Node.js installer.
There is no hosted service, no daemon, no plugin runtime.
Your IDE's existing skill-loading machinery does the work.

## The 4-phase workflow

GoMad's workflow runs as a sequential pipeline through four phases — Analysis, Planning, Solutioning, Implementation.
Each phase consumes the artifacts of the previous one, so the order is load-bearing rather than aspirational.

**Analysis** produces discovery artifacts.
The analyst persona walks the team through brainstorming, market research, and project documentation.
The output is a set of briefs and research notes that frame the problem before any product decisions are made.

**Planning** produces requirements.
The PM and UX-designer personas turn the analysis output into a Product Requirements Document and supporting UX design specs.
These artifacts name the functional requirements (FR-NN), the acceptance criteria (Given/When/Then), and the explicit out-of-scope contract that the next phase will consume.

**Solutioning** produces an implementation plan.
The architect persona drafts an architecture document, decomposes work into epics and stories, and runs an implementation-readiness check.
That check confirms downstream skills can act on the plan without further human translation.

**Implementation** produces code, code review, and retrospectives.
The dev and SM personas drive story execution, plus the new domain knowledge framework that lets a persona retrieve curated reference material on demand.
This is where the upstream phase artifacts finally turn into committed work.

The pipeline shape matters because each phase's output is the next phase's input.
A partial brief produces a partial PRD, which produces partial architecture, which produces stuck stories.
See the [skills reference](../reference/skills.md) for the full per-phase skill catalog.

## The manifest-v2 installer

GoMad follows a generate-don't-move principle.
The source directories — `src/gomad-skills/`, `src/core-skills/`, and `src/domain-kb/` — are the canonical content.
Nothing in those directories is what the user runs against.
Instead, `gomad install` reads them and *emits* a fresh tree into the user's chosen `<installRoot>` (the project convention is `_gomad`, but the path is configurable).

Every emitted file is recorded in a manifest.
The manifest lives at `<installRoot>/_config/files-manifest.csv` and uses the v2 schema: a `schema_version` row plus per-file rows carrying `install_root`, `path`, and content metadata.
The manifest is the source of truth for what is installed — not the filesystem, not the package version, the CSV.

Subsequent `gomad install` runs are manifest-driven.
The installer reads the prior manifest, snapshots every file it is about to replace into `<installRoot>/_backups/<timestamp>/`, then writes the fresh outputs and rewrites the manifest.
If a re-install ever produces an unexpected result, the snapshot directory holds a reversible record — see the [upgrade recovery guide](../upgrade-recovery.md) for the restore procedure.

User overrides survive across reinstalls.
A `.customize.yaml` file in your install root marks specific paths as user-owned.
The installer's custom-file detector treats matching `.md` files as out-of-bounds and skips them during cleanup, so your edits are not silently overwritten.

The v1.3 install layout is deliberately flat:

```text
<installRoot>/
├── _config/
│   ├── agents/<shortName>.md
│   ├── kb/<slug>/
│   └── files-manifest.csv
└── _backups/<timestamp>/
```

## The launcher-form slash command

GoMad personas ship as three artifacts per persona, not one.

- The **persona body** at `<installRoot>/_config/agents/<shortName>.md` is the actual instructions the IDE follows when the persona is active.
- The **launcher stub** at `.claude/commands/gm/agent-<shortName>.md` is a tiny file the IDE binds to the slash command surface.
- The **slash command surface** itself, `/gm:agent-<shortName>`, is what you type.

The runtime sequence is intentionally short.
You type `/gm:agent-pm`.
Your IDE locates the launcher stub at `.claude/commands/gm/agent-pm.md`.
The launcher instructs the IDE to load the persona body fresh from `<installRoot>/_config/agents/pm.md`.
The persona greets you and lists its capabilities.
Each invocation re-reads the persona body, so updates from `gomad install` take effect on the next slash command, no restart required.

The reason this is launcher-form rather than bundled-form is decoupling.
The persona body changes whenever you re-run `gomad install` (new prompts, refined instructions, updated capability lists).
The launcher stub stays stable — it is a pointer, not a copy.
That decoupling means the user-facing slash command does not change shape across upgrades; only the content the IDE loads on the other side does.

The agent catalog is documented in the [agents reference](../reference/agents.md), which lists every persona with its slash command and primary phase.

Note that **task skills** — the per-step skills the personas use, catalogued in the [skills reference](../reference/skills.md) — are loaded by the persona, not invoked directly.
There is no `/gm:create-prd` slash command in v1.3; a task skill is triggered when an active persona's instructions tell the IDE to load it.
The slash command surface is reserved for personas only.

## How they fit together

Walk through a single concrete flow to see the three pillars cooperate.

A developer runs `gomad install` against a fresh project.
The installer emits agent personas, task skills, and launcher stubs into the v1.3 layout — `<installRoot>/_config/agents/pm.md`, `<installRoot>/_config/kb/<slug>/`, `.claude/commands/gm/agent-pm.md`, and the manifest at `<installRoot>/_config/files-manifest.csv`.

The developer types `/gm:agent-pm`.
The IDE loads the launcher stub, which tells it to load the persona body fresh.
The PM persona greets the developer and offers to drive the Planning phase.
The persona's instructions invoke task skills as needed, producing a PRD draft.
That PRD becomes the input artifact for the Solutioning phase, where the architect persona — invoked the same way — turns it into an architecture document and a story decomposition.

The pillars are independently testable but designed together.
The installer lays files.
The launcher binds slash commands to those files.
The workflow gives the slash commands a sequence to run in.
Remove any one of the three and the system fails: no installer means files never land at predictable paths; no launcher means the IDE has nothing to invoke; no workflow means the personas have no shared script for what to do next.
</document>

<document path="reference/agents.md">
GoMad ships eight agent personas spanning the four workflow phases — Analysis, Planning, Solutioning, and Implementation. Each persona is invoked from a launcher-form slash command (the table below shows the exact form) whose stub lives at `.claude/commands/gm/agent-<shortName>.md` and whose persona body is loaded fresh at runtime from `<installRoot>/_config/agents/<shortName>.md`. The persona body is never bundled into the command stub; it is read from disk on every invocation, which means edits to the persona file take effect on the next call without rebuilding or reinstalling.

## All personas

<!-- AUTO:agents-table-start -->
| Persona | Slash command | Phase | Purpose |
| --- | --- | --- | --- |
| Mary | `/gm:agent-analyst` | Analysis | Strategic business analyst and requirements expert. Use when the user asks to talk to Mary or requests the business analyst. |
| Paige | `/gm:agent-tech-writer` | Analysis | Technical documentation specialist and knowledge curator. Use when the user asks to talk to Paige or requests the tech writer. |
| John | `/gm:agent-pm` | Planning | Product manager for PRD creation and requirements discovery. Use when the user asks to talk to John or requests the product manager. |
| Sally | `/gm:agent-ux-designer` | Planning | UX designer and UI specialist. Use when the user asks to talk to Sally or requests the UX designer. |
| Winston | `/gm:agent-architect` | Solutioning | System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect. |
| Amelia | `/gm:agent-dev` | Implementation | Senior software engineer for story execution and code implementation. Use when the user asks to talk to Amelia or requests the developer agent. |
| Bob | `/gm:agent-sm` | Implementation | Scrum master for sprint planning and story preparation. Use when the user asks to talk to Bob or requests the scrum master. |
| Barry | `/gm:agent-solo-dev` | Implementation | Elite full-stack developer for rapid spec and implementation. Use when the user asks to talk to Barry or requests the quick flow solo dev. |
<!-- AUTO:agents-table-end -->

## Choosing a persona

Reach for an Analysis-phase persona when you are still framing the problem space. The Analyst drives early discovery, market research, and brainstorming. The Tech Writer is the right hand once you need to capture findings, draft documentation, or polish prose for the docs site.

Move to Planning-phase personas once the problem is understood and you need to commit to a shape. The PM authors PRDs and product briefs that downstream coding agents can act on directly. The UX Designer covers user-experience work — flows, surface specs, and interaction notes that the PRD references.

Use a Solutioning-phase persona when the requirements are settled and the next question is "how should we build this?". The Architect produces system designs, decomposes the PRD into epics and stories, and runs implementation-readiness checks before any code lands.

Switch to an Implementation-phase persona when sprint mechanics begin. The Scrum Master creates and refines stories. The Dev executes them — read story, write code, write tests, raise PRs. The Solo Dev, Barry, is the eighth persona — added post-fork as a single-developer-mode hybrid that compresses the Scrum Master and Dev loop for solo workflows where ceremony overhead outweighs role separation.

## How invocation works

Every persona is invoked through the same launcher-form contract. A slash command of the shape shown in the table above loads a thin stub at `.claude/commands/gm/agent-<shortName>.md`. The stub is generated by `gomad install` from the persona's `skill-manifest.yaml`; it carries metadata (display name, title, icon) so Claude Code can surface the persona in its UI.

When the slash command fires, the stub instructs the assistant to read the persona body from `<installRoot>/_config/agents/<shortName>.md`. That file is the canonical source of truth for the persona's behavior, voice, and constraints — the stub never duplicates it. Reading the body fresh on each invocation means a persona edit takes effect immediately, with no rebuild step.

For the deeper architectural picture — how launcher-form slash commands fit alongside skills, the manifest-v2 installer, and the four-phase workflow — see [GoMad architecture](../explanation/architecture.md).

## Customizing personas

Persona files at `<installRoot>/_config/agents/*.md` are owned by the installer. A subsequent `gomad install` (for example, an upgrade) regenerates them from `src/gomad-skills/*/gm-agent-*/SKILL.md` and may overwrite local edits.

:::note[User overrides]
Persona files at `<installRoot>/_config/agents/*.md` are regenerated by `gomad install`.
To customize a persona without losing changes on the next install, see the
customization guide in `<installRoot>/_config/files-manifest.csv` and the
`.customize.yaml` user-override semantics.
:::
</document>

<document path="reference/skills.md">
GoMad skills are atomic capabilities, organized by the four workflow phases — Analysis, Planning, Solutioning, and Implementation — plus a Core layer of cross-cutting utilities. Eight of the catalog entries are agent personas (full slash-command launchers); their full purpose and invocation are documented in [Agents](./agents.md). The task skills and core skills below are invoked via the persona that owns them, not directly.

## How to read this catalog

Each phase section below is a table generated from the source SKILL.md files. The `Skill` column is the canonical skill name (matches the directory under `src/gomad-skills/<phase>/` or `src/core-skills/`). The `Description` column comes from the SKILL.md frontmatter. The `Invoked by` column documents the contract — task skills and core skills are not standalone slash commands; a persona loads them as part of its workflow.

:::note[Source of truth]
The tables below are auto-generated from `src/gomad-skills/*/SKILL.md` and
`src/core-skills/*/SKILL.md` at build time. To add or rename a skill, edit
the source SKILL.md and re-run `npm run docs:build`.
:::

## 1. Analysis

<!-- AUTO:skills-table-analysis-start -->
<!-- section: Analysis -->
| Skill | Description | Invoked by |
| --- | --- | --- |
| `gm-document-project` | Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-domain-research` | Conduct domain and industry research. Use when the user says wants to do domain research for a topic or industry | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-market-research` | Conduct market research on competition and customers. Use when the user says they need market research | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-prfaq` | Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-product-brief` | Create or update product briefs through guided or autonomous discovery. Use when the user requests to create or update a Product Brief. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-technical-research` | Conduct technical research on technologies and architecture. Use when the user says they would like to do or produce a technical research report | Invoked by `gm-agent-*` or any persona via the skill loader |
<!-- AUTO:skills-table-analysis-end -->

Analysis-phase skills focus on early discovery, market research, and requirements gathering.

## 2. Planning

<!-- AUTO:skills-table-planning-start -->
<!-- section: Planning -->
| Skill | Description | Invoked by |
| --- | --- | --- |
| `gm-create-prd` | Create a PRD from scratch. Use when the user says "lets create a product requirements document" or "I want to create a new PRD" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-create-ux-design` | Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-edit-prd` | Edit an existing PRD. Use when the user says "edit this PRD". | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-validate-prd` | Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation" | Invoked by `gm-agent-*` or any persona via the skill loader |
<!-- AUTO:skills-table-planning-end -->

Planning-phase skills produce PRDs, UX design specs, and validated planning artifacts.

## 3. Solutioning

<!-- AUTO:skills-table-solutioning-start -->
<!-- section: Solutioning -->
| Skill | Description | Invoked by |
| --- | --- | --- |
| `gm-check-implementation-readiness` | Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness". | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-create-architecture` | Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-create-epics-and-stories` | Break requirements into epics and user stories. Use when the user says "create the epics and stories list" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-generate-project-context` | Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context" | Invoked by `gm-agent-*` or any persona via the skill loader |
<!-- AUTO:skills-table-solutioning-end -->

Solutioning-phase skills cover architecture design, epic + story decomposition, and implementation-readiness checks.

## 4. Implementation

<!-- AUTO:skills-table-implementation-start -->
<!-- section: Implementation -->
| Skill | Description | Invoked by |
| --- | --- | --- |
| `gm-checkpoint-preview` | LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change". | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-code-review` | Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-correct-course` | Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-create-story` | Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-dev-story` | Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-discuss-story` | Use when the user wants to crystallize gray areas for a planned story BEFORE running gm-create-story. Produces {planning_artifacts}/{{story_key}}-context.md with 5 locked sections (domain, decisions, canonical_refs, specifics, deferred) that gm-create-story auto-loads. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-domain-skill` | Use when a coding agent or another skill needs to ground itself in reference material from an installed domain-knowledge-base pack. Takes {domain_slug} and optional {query}; on a strong BM25 match the skill loads the single best-matching .md file into the agent''s working context as authoritative domain guidance and returns only a one-line citation (read-as-skill, not stdout dump). With no query, returns a file listing. Supports typo fallback via Levenshtein "did you mean" suggestions. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-epic-demo-story` | Create a demo/verification story for a completed epic that defines a walkthrough flow and validates it via Chrome DevTools. Use when the user says "create epic demo story", "create demo story for epic [N]", "create verification story for epic", or wants to demonstrate and verify a completed epic through browser interaction. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-qa-generate-e2e-tests` | Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-quick-dev` | Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-retrospective` | Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-sprint-agent` | Autonomous sprint orchestrator that drives the full story lifecycle: create story, develop, code review, summary, and commit — looping through stories automatically. Use when user says "start sprint agent", "auto sprint", "run Elon", or wants hands-free story execution. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-sprint-planning` | Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan" | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-sprint-status` | Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status" | Invoked by `gm-agent-*` or any persona via the skill loader |
<!-- AUTO:skills-table-implementation-end -->

Implementation-phase skills drive sprint mechanics — story creation, dev execution, code review, retrospectives, and the new domain knowledge framework.

## Core

<!-- AUTO:skills-table-core-start -->
<!-- section: Core -->
| Skill | Description | Invoked by |
| --- | --- | --- |
| `gm-advanced-elicitation` | Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-brainstorming` | Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-distillator` | Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-editorial-review-prose` | Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-editorial-review-structure` | Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-help` | Analyzes current state and user query to answer GoMad questions or recommend the next skill(s) to use. Use when user asks for help, gomad help, what to do next, or what to start with in GoMad. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-index-docs` | Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-party-mode` | Orchestrates group discussions between installed GOMAD agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-review-adversarial-general` | Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-review-edge-case-hunter` | Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs. | Invoked by `gm-agent-*` or any persona via the skill loader |
| `gm-shard-doc` | Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document | Invoked by `gm-agent-*` or any persona via the skill loader |
<!-- AUTO:skills-table-core-end -->

Core skills are cross-cutting utilities — review helpers, brainstorming, document sharding, and elicitation primitives — usable by any persona in any phase.
</document>

<document path="404.md">
The page you're looking for doesn't exist or has been moved.

[Return to Home](./index.md)
</document>

<document path="upgrade-recovery.md">
Starting with gomad v1.2, every `gomad install` that removes files takes a snapshot of those files into a timestamped directory under `_gomad/_backups/<YYYYMMDD-HHMMSS>/`. This document explains how those snapshots are structured and how to restore from them.

## Backup directory layout

When `gomad install` performs a manifest-driven cleanup, it creates:

```
_gomad/_backups/<YYYYMMDD-HHMMSS>/
├── metadata.json           # machine-readable backup manifest
├── README.md               # auto-generated recovery instructions (co-located)
├── .claude/                # snapshots of files that were installed under .claude/
│   └── commands/gm/agent-pm.md
├── _gomad/                 # snapshots of files that were installed under _gomad/
│   └── gomad/agents/pm.md
└── .cursor/                # snapshots from any IDE-target install_root
    └── ...
```

Each top-level directory under `<YYYYMMDD-HHMMSS>/` corresponds to an `install_root` value from `_gomad/_config/files-manifest.csv`. Inside each, the relative-path structure mirrors the original workspace layout.

## metadata.json schema

```json
{
  "gomad_version": "1.2.0",
  "created_at": "2026-04-20T14:30:52.123+09:00",
  "reason": "manifest_cleanup",
  "files": [
    {
      "install_root": ".claude",
      "relative_path": "commands/gm/agent-pm.md",
      "orig_hash": "<sha256 from files-manifest.csv, or null>",
      "was_modified": false
    }
  ],
  "recovery_hint": "Restore with: cp -R $(pwd)/_gomad/_backups/20260420-143052/* ./"
}
```

| Field | Purpose |
|-------|---------|
| `gomad_version` | The gomad version that produced this backup. Recovery should verify compatibility with your current install. |
| `created_at` | Full ISO 8601 timestamp with timezone — disambiguates among same-second installs. |
| `reason` | One of `manifest_cleanup`, `legacy_v1_cleanup`. |
| `files[]` | Per-file record. `was_modified` is `true` when the file on disk differed from the stored manifest hash, `false` when it matched, `null` for v1.1 legacy backups (no hash was stored). |
| `recovery_hint` | One-line shell command that restores from this backup. |

## How to restore

### Quick recovery

From the workspace root:

```bash
cp -R $(pwd)/_gomad/_backups/<YYYYMMDD-HHMMSS>/* ./
```

Replace `<YYYYMMDD-HHMMSS>` with the directory name of the backup you want.

### Restore file content only (skip metadata.json and README.md)

```bash
rsync -a --exclude=metadata.json --exclude=README.md \
  $(pwd)/_gomad/_backups/<YYYYMMDD-HHMMSS>/ ./
```

### Before restoring — version compat check

Compare `metadata.json.gomad_version` to your currently-installed gomad version:

```bash
cat _gomad/_backups/<YYYYMMDD-HHMMSS>/metadata.json | grep gomad_version
npx gomad --version
```

If the versions differ, the install_root semantics may have changed. Recovering a v1.2-vintage backup onto a v1.3+ install should still work for file content, but paths may land in locations the new installer no longer manages — you may end up with orphaned files. When in doubt, copy a single file at a time.

## Identifying which backup to restore

Each `_gomad/_backups/<YYYYMMDD-HHMMSS>/` directory is sortable chronologically (lexicographic order matches chronological order by construction of the D-37 timestamp format). Two installs within the same second produce `<ts>` and `<ts>-2` suffixes.

Each backup directory also contains an auto-generated `README.md` with the exact `cp -R` command for that specific snapshot.

## Pruning backups

Backups are user-managed in v1.2 — the installer never deletes or rotates old snapshots. Each backup directory is a self-contained tree you can safely remove:

```bash
rm -rf _gomad/_backups/20260401-*   # remove all April-1st backups
```

Automated rotation is deferred to a future gomad release.

## When backups are NOT produced

No backup is created when:

- `gomad install` runs on a fresh workspace (nothing to snapshot)
- The new install set is identical to the prior — idempotent re-install
- A manifest corruption is detected (`MANIFEST_CORRUPT` logged) — cleanup is skipped entirely as a safety measure

In these cases, `_gomad/_backups/` may remain empty or contain only earlier backups.

## v1.2 → v1.3 recovery

When upgrading from v1.2.0 to v1.3.0, the installer relocates persona body
files from `_gomad/gomad/agents/<shortName>.md` to
`_gomad/_config/agents/<shortName>.md`. The 8 old files are snapshotted
into `_gomad/_backups/<YYYYMMDD-HHMMSS>/_gomad/gomad/agents/` before removal.

The v1.3 cleanup planner detects v1.2 layouts via the presence of both a
`_gomad/_config/files-manifest.csv` (v2 schema) AND at least one persona
file at `_gomad/gomad/agents/`. When detected, the migration emits a
verbose banner naming the move, the backup location, and this recovery
document.

### Rollback to v1.2 layout

If `/gm:agent-*` invocation fails after upgrade, or you need to roll back to
v1.2.0:

1. Re-pin the v1.2 release globally:

   ```bash
   npm install -g @xgent-ai/gomad@1.2.0
   ```

2. Restore the snapshotted persona files (substitute the actual timestamp
   from `_gomad/_backups/`):

   ```bash
   cp -R _gomad/_backups/<YYYYMMDD-HHMMSS>/_gomad/gomad/agents/ _gomad/gomad/
   ```

3. Re-run `gomad install` against the v1.2 binary — the installer will
   regenerate launcher stubs (`/gm:agent-*`) pointing at the restored
   `_gomad/gomad/agents/` location:

   ```bash
   gomad install
   ```

### Forward recovery

If only the launcher stubs are stale (the persona body files are at the
new `_config/agents/` location but `/gm:agent-*` 404s), re-run
`gomad install`. The `writeAgentLaunchers` step overwrites launcher stubs
unconditionally and will regenerate them with the v1.3 path.

```bash
gomad install
```

### What the .customize.yaml semantics look like

User overrides at `_gomad/_config/agents/.customize.yaml` are preserved
across the v1.2→v1.3 upgrade. The custom-file detector treats the 8
generated persona `.md` files as installer-managed and leaves
`.customize.yaml` and any non-matching `.md` files untouched.
</document>