| 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. |
Central agent policy
AUQ, Serena, Hindsight, context-mode, and agent policy is centralized in AGENTS.md in the agent-dispatch repo (agent-dispatch where). 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
This skill suggests, it does not act. The user must explicitly run /masterplan import to convert anything.
When to fire
The user is in a git repo and at least one of these is true:
- A planning-shaped file lives at the repo root or in a common docs directory:
PLAN.md, TODO.md, ROADMAP.md, WORKLOG.md, NOTES.mddocs/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).
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 existing planning artifact(s) in this repo:
<path> — last modified <path> — last modified
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.
Don't list more than 5 artifacts. If more exist, say "(plus N more — /masterplan import will discover them all)".
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 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
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
for plan in docs/superpowers/plans/*.md; do
[[ "$plan" == *-status.md ]] && continue
base="${plan%.md}"
[[ ! -f "${base}-status.md" ]] && echo "$plan"
done
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"
done
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.
