pm-templates

What this skill does

# PM Templates

Issue templates indexed by **type tag**. One canonical template per tag. Every other PM skill that touches issue bodies (`pm-issues`, `pm-review`, `pm-improve`, `pm-agent`) resolves through this registry — so when you change a template, every downstream skill picks it up.

## Why a registry

The old `pm-issues` skill hard-coded Bug / Feature / Task as inline markdown. That made the templates invisible to the reviewer (it had nothing to validate against) and impossible to extend without forking the skill. Putting them in a registry means:

- Reviewer compares the issue body against the template for the issue's tag and flags missing sections.
- Projects can override a single tag (`feature.md`) without touching the rest.
- Adding a new type (e.g. `spike`, `refactor`, `chore`) is a one-file change, not a skill edit.

## Where templates live

Two layers — repo first, plugin defaults as fallback. The PM config principle is "all config in one place" (`<repo>/.claude/pm/`); a per-machine template overlay would split the config dir, so v0.20.0 drops it.

```
<repo-root>/.claude/pm/templates/        ← canonical, checked into git
├── _manifest.json
├── bug.md
├── feature.md
├── task.md
└── spike.md            # any tag the project uses
```

| Layer | Path | When it applies |
|---|---|---|
| 1. **In-repo (canonical)** | `<repo-root>/.claude/pm/templates/<tag>.md` | Project has opted into customization (`/pm-setup` initializes this) |
| 2. Plugin defaults | `${CLAUDE_PLUGIN_ROOT}/skills/pm-templates/templates/<tag>.md` | Bundled starters — applied when the in-repo file doesn't exist |

First file that exists wins. Never merge bodies across layers.

If an operator wants a one-off personal tweak that they don't want to commit, they edit the in-repo file and leave it uncommitted (or stash it). v0.20.0 deliberately doesn't offer a "user overlay" file location — the result is fewer places to look, less confusion about which file is authoritative.

## The manifest

The manifest at `<repo-root>/.claude/pm/templates/_manifest.json` defines:

- which tags this project recognizes
- what each tag *means*
- which `## Section` headings are required vs optional per tag (the reviewer reads the same file)
- the tracker labels that map to each tag

**The in-repo manifest fully replaces the plugin manifest if present** — projects can drop tags they don't use and add tags the plugin doesn't ship with. Lookup order for the manifest:

1. `<repo-root>/.claude/pm/templates/_manifest.json` (if present, authoritative)
2. `${CLAUDE_PLUGIN_ROOT}/skills/pm-templates/templates/_manifest.json` (plugin defaults)

This means a project that wants only `bug` and `feature` can ship a 2-tag manifest, and `pm-review` will refuse to classify anything as `task` or `spike` for that project — taxonomy drift is structurally prevented.

**Why replacement, not overlay.** Most config systems merge — but merging is wrong here. If a project intentionally drops a tag (say, removes `spike` because they never run time-boxed investigations), an overlay would re-introduce it the next time the plugin updates and adds a new tag the project wants. Worse, the operator can't tell which tags came from where, so deciding "is this in my taxonomy?" requires reading two files and reconciling. Replacement keeps the rule simple: the in-repo manifest **is** the project's taxonomy, full stop. The plugin defaults are a *starter*, not a *floor*.

## Workflow

### Resolve a template body

When another skill asks "give me the bug template":

```bash
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
TAG=bug

for path in \
  "${REPO_ROOT}/.claude/pm/templates/${TAG}.md" \
  "${CLAUDE_PLUGIN_ROOT}/skills/pm-templates/templates/${TAG}.md"
do
  if [ -f "$path" ]; then
    echo "$path"; break
  fi
done
```

First hit wins. If no file matches **and** the tag isn't in the active manifest, the tag is unknown — report it and offer to register one (next section). Do not silently fall back to a generic template; that hides taxonomy drift.

### Resolve the manifest

```bash
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
REPO_MANIFEST="${REPO_ROOT}/.claude/pm/templates/_manifest.json"
PLUGIN_MANIFEST="${CLAUDE_PLUGIN_ROOT}/skills/pm-templates/templates/_manifest.json"

if [ -f "$REPO_MANIFEST" ]; then
  cat "$REPO_MANIFEST"
else
  cat "$PLUGIN_MANIFEST"
fi
```

The in-repo manifest is *replacement*, not overlay — see "The manifest" section above for why.

### List available tags

Read the active manifest (resolved as above). `tags` is an array of `{ tag, description, required_sections, optional_sections, priority_hint?, hitl_default_hint?, labels? }`. Show a one-line summary per tag when asked "what templates are available?".

### The `hitl_default_hint` field

Optional per-tag string: `"hitl"` or `"afk"`. Indicates the **default execution mode** for issues of this tag — whether the work typically needs a human-in-the-loop (`hitl`) or can run away-from-keyboard by an agent (`afk`).

This is a *hint*, not a requirement. When `pm-issues` drafts an issue of a given tag, it pre-fills the HITL/AFK label with this hint, and the operator confirms or overrides during create. The labels themselves (`hitl` and `afk`) are tracker-level — the manifest just suggests which one fits this category of work.

Sensible defaults:
- **bug** → `hitl` — bugs usually need a human to verify the fix worked
- **feature** → `hitl` — design decisions and acceptance-criteria validation belong with a human
- **task** → `afk` — refactors, cleanups, and infra work are often agent-completable end-to-end
- **spike** → `hitl` — the outcome of a spike is a decision, which is a human's call

If a tag has no `hitl_default_hint`, `pm-issues` asks the operator without a pre-fill.

### Classify an issue's tag

Given a user description like *"the login button crashes when..."* or an existing issue body:

1. Read the active manifest.
2. Look for explicit signals first — a leading `[bug]` / `[feature]` prefix, a Linear/GitHub label that matches an entry's `labels.<tracker>` array, or the user saying "this is a feature."
3. Otherwise, match against each tag's `description` field and propose the best fit. Confirm before treating it as classified — do not silently pick one.

The reviewer skill (`pm-review`) uses this classifier too; keep the logic here so both skills agree.

## Modifying templates — guided workflows

When the user wants to add, edit, or remove a template, your job is to **guide them through the design decisions** — not just point at files and call it done. Walk one question at a time, surface the trade-offs, show a diff before writing. New users get the full walkthrough; after two or three rounds they know the routine and you can drop the coaching.

The three flows below cover every modification. Each one is a sequence of decisions, not a single command.

### Adding a new tag

Triggered by phrases like *"add a template for migrations"*, *"we need a tag for X"*, *"can you register a new issue type"*. Walk the user through 9 steps in order.

**Step 0 — Make sure the project has an in-repo manifest.** *(First-time customizers only.)*

Before anything else, check whether `<repo>/.claude/pm/templates/_manifest.json` exists.

- **If it exists:** skip to Step 1; the project is already set up for customization.
- **If it doesn't:** the project is currently running on plugin defaults, and adding a tag means committing to the in-repo layout. Bootstrap by copying the plugin manifest as a starting point — it gives the project the default 4-tag taxonomy as the floor, which the operator can then trim or extend:

  ```bash
  mkdir -p <repo-root>/.claude/pm/templates
  cp "${CLAUDE_PLUGIN_ROOT}/skills/pm-templates/templates/_manifest.json" \
     <repo-root>/.claude/pm/templates/_manifest.json
  ```

  Also copy any default template bodies the project will use (`bug.md`, `feature.md`, etc.) so the in-repo manifest's tag set has matching bodies on disk. Tell th