git:20260828.ef5a176 to git:20260830.f866774

46 added, 35 removed. Audit A to A.

---

name: masterplan-detect

- description: Suggest `/masterplan import` when legacy planning artifacts (PLAN.md, TODO.md, ROADMAP.md, pre-v3 superpowers plans/status files, branches without merged PRs, draft PRs with task lists) exist in the repo. Surfaces a one-line suggestion only — never auto-runs.

+ description: Suggest `/masterplan import` only when legacy masterplan bundle state files (`docs/masterplan/<slug>/state.yml` at schema 5.x) exist without a matching v8 run. Generic planning artifacts (PLAN.md, TODO.md, ROADMAP.md, design docs, PR task lists) are NOT importable — no `/masterplan import` can ingest them; mention them only as context that a fresh `/masterplan brainstorm` would be the path to bring ideas under the schema. Surfaces a one-line suggestion only — never auto-runs.

---

## Central agent policy

AUQ, Serena, Hindsight, context-mode, and agent policy is centralized in `AGENTS.md` (routing resolves from `policy/workflow-map.json`; fleet policy at `/srv/workflows/policy/dispatch.md`). This skill must not duplicate or override dispatch rules. User-facing choices must use `ask_user_question` / `AskUserQuestion`, never prose questions.

- # Suggesting /masterplan import for legacy planning artifacts

+ # Detecting legacy masterplan bundles for /masterplan import

- This skill **suggests**, it does not act. The user must explicitly run `/masterplan import` to convert anything.

+ This skill **suggests**, it does not act. The user must explicitly run `/masterplan import` (or, for non-importable artifacts, a fresh `full`/`brainstorm`) to act.

+ `/masterplan import` is **not** a generic legacy-document importer. It maps to `mp migrate-bundle`, which ingests

+ only a **legacy masterplan bundle's `state.yml`** (schema_version 5.x) and re-freezes it into a v8 run. It cannot

+ convert arbitrary planning markdown (`PLAN.md`, `TODO.md`, `ROADMAP.md`, design/RFC docs, PR task lists). Those have

+ no import path — the honest suggestion for them is a fresh `/masterplan brainstorm` seeded from the repo context,

+ never a claim that import will ingest them.

## When to fire

The user is in a git repo and at least one of these is true:

+ - A legacy masterplan bundle exists at `docs/masterplan/<slug>/state.yml` whose `schema_version` is **5.x** (or

+ predates 5.0, which import will refuse) and there is no matching already-migrated v8 run for the same `<slug>`.

+ That is the entire importable surface. The following are **not** importable, so they do not by themselves warrant

+ an import suggestion:

- A planning-shaped file lives at the repo root or in a common docs directory:

- `PLAN.md`, `TODO.md`, `ROADMAP.md`, `WORKLOG.md`, `NOTES.md`

- `docs/plans/*.md`, `docs/design/*.md`, `docs/rfcs/*.md`, `architecture/*.md`, `specs/*.md`

- A pre-v3 masterplan artifact exists under `docs/superpowers/{plans,specs,retros,archived-plans,archived-specs}` and there is no matching `docs/masterplan/<slug>/state.yml`.

- - A plan exists at `docs/superpowers/plans/*.md` with **no** sibling `*-status.md` (orphan from pre-v3 masterplan runs).

- An open feature branch (not yet merged into the trunk) has descriptive name + commit history that suggests a tracked feature, but no masterplan status file exists for it.

- A draft PR's body contains a task list (`- [ ]` / `- [x]` / numbered steps).

+ For any of these, the actionable masterplan step is a fresh `full`/`brainstorm` run seeded from the repo context —

+ not `/masterplan import`.

Fire at **natural break points**: a fresh conversation in this repo, a user asking "what should I work on?", a user about to start a new feature. Don't interrupt unrelated work.

## What to surface

A short message — no prose, no editorialization. Format:

- > I see <N> existing planning artifact(s) in this repo:

- > - `<path>` — last modified <date>

+ > I see <N> legacy masterplan bundle(s) in this repo not yet migrated to a v8 run:

+ > - `<path to state.yml>` — schema_version <v>

- > If you'd like to bring them under the `/masterplan` schema (`docs/masterplan/<slug>/state.yml` + bundled spec/plan/events, so already-done tasks aren't redone), run `/masterplan import`. Successful v3 completions archive verified legacy/orphan state by default after migration. This is a suggestion only — no action taken.

+ > Run `/masterplan import` to migrate the 5.x bundle(s) to a v8 run (backs up the original).

+ > Bundles below 5.0 are refused — treat those as read-only and seed a fresh run instead.

+ > This is a suggestion only — no action taken.

- Don't list more than 5 artifacts. If more exist, say "(plus N more — `/masterplan import` will discover them all)".

+ Don't list more than 5 bundles. If more exist, say "(plus N more — check each

+ `docs/masterplan/<slug>/state.yml` for `schema_version: 5.x`)".

+ If the user instead has generic planning markdown (PLAN/TODO/ROADMAP/design docs, PR task lists),

+ say plainly that `/masterplan import` cannot ingest those and suggest a fresh `full`/`brainstorm` run

+ seeded from the repo context.

## What NOT to do

- **Do not** invoke `/masterplan` yourself. Only the user can.

- - **Do not** read or modify the legacy artifacts. Use `Glob` (always-available Claude Code tool) for their existence and stat for last-modified. The shell snippets in **Detection commands** below give richer matching (depth/exclude/ignore-dir semantics) where `fd` is installed; fall back to `Glob` when it isn't. The actual content reading happens during `/masterplan import`.

+ - **Do not** read or modify the legacy bundle files. Use `Glob` (always-available Claude Code tool) for their existence and grep for the `schema_version` line. The shell snippets in **Detection commands** below give richer matching where `fd`/`rg` are installed; fall back to `Glob`/`grep` when they aren't. The actual migration happens during `/masterplan import` (`mp migrate-bundle`).

- **Do not** fire on every conversation in the repo — once per session is enough. If the user has already declined or run import this session, stay silent.

- **Do not** fire if the user is mid-task on something unrelated. Wait for a natural break.

## Detection commands

```bash

- # Local plan files (excluding archives and superpowers state)

- fd -t f -E 'node_modules' -E 'vendor' -E '.git' -E 'legacy' \

- '^(PLAN|TODO|ROADMAP|WORKLOG|NOTES)\.md$' .

- fd -t f -E 'node_modules' '\.md$' docs/plans docs/design docs/rfcs architecture specs 2>/dev/null

- # Orphan superpowers plans

- for plan in docs/superpowers/plans/*.md; do

- [[ "$plan" == *-status.md ]] && continue

- base="${plan%.md}"

- [[ ! -f "${base}-status.md" ]] && echo "$plan"

- done

- # Pre-v3 masterplan artifacts not yet copied into docs/masterplan/<slug>/

- for path in docs/superpowers/plans/*.md docs/superpowers/archived-plans/*.md; do

- [[ -f "$path" ]] || continue

- [[ "$path" == *README.md ]] && continue

- slug="$(basename "$path" .md)"

- slug="${slug#????-??-??-}"

- slug="${slug%-status}"

- [[ ! -f "docs/masterplan/$slug/state.yml" ]] && echo "$path"

+ # Legacy masterplan bundles not yet migrated to a v8 run (the ONLY importable surface).

+ # A bundle is importable when docs/masterplan/<slug>/state.yml exists with schema_version 5.x.

+ for state in docs/masterplan/*/state.yml; do

+ [[ -f "$state" ]] || continue

+ v="$(grep -m1 '^schema_version:' "$state" | sed 's/^schema_version:[[:space:]]*//')"

+ major="${v%%.*}"

+ if [[ "$major" == "5" ]]; then

+ echo "$state (schema $v)"

+ elif [[ -n "$v" && "$major" -lt 5 ]]; then

+ echo "$state (schema $v — BELOW 5.0, import will refuse; seed a fresh run)"

+ fi

done

- # Open branches with no merged PR (requires gh)

- gh pr list --state=all --limit=200 --json=headRefName,state | \

- jq -r '.[] | select(.state != "MERGED") | .headRefName'

```

- Use whichever commands are available; degrade gracefully if `fd` or `gh` aren't installed.

+ Use whichever commands are available; degrade gracefully if `fd`, `rg`, or `gh` aren't installed.

+ Generic planning markdown (PLAN/TODO/ROADMAP/NOTES/design docs, PR task lists) is **not** part of the

+ import surface — do not run import-specific detection over it.