Keystone · roadmap — strategic project planning
Create and maintain a high-level project roadmap with major milestones in docs/roadmap.md. A milestone is a goal worth many
tasks; one task is /keystone:intent or /keystone:plan. This skill plans only — it never edits code.
Arguments: $ARGUMENTS.
Output rendering. Report and summary templates in code blocks below show structure only. Render them as Markdown —
headings, tables, bold labels, bullet lists — never wrapped in a code block (it shows as a monospace wall); keep paths
and commands in inline code. The closing Blocked on me: / Changed: / Found: lines become three bullets with bold labels.
Next step (mandatory). End the answer with a Next: line that names the step in a few words, then put the exact
command on its own, on the following line(s), inside a fenced code block with no language tag — the app shows a
copy button on a code block. Never tag it ```bash: a /keystone:* command is not a shell command, and the bash tag
adds a Run button that would fail. When nothing runs now, write Next: nothing now — waiting for <event> and put the
later command in that fenced block. Never end on a caveat or an open-ended question. A path in that command must open
from the session's working directory, because the next session (after /clear) starts there: a file inside it →
its path relative to it; a file you wrote in another repository or folder (after cd) → its absolute path.
Choice at the end (menu). When the stage leaves more than one sensible next step, end with one AskUserQuestion
menu instead of a single command, as AI Factory does: 2–4 options, the recommended one first with (Recommended),
and Stop here last. Print the report and the summary first, then ask. On a pick, carry it out: an option that
continues in this session runs now — for another Keystone skill, read ${CLAUDE_SKILL_DIR}/../<skill>/SKILL.md and
follow it with the chosen arguments; an option that needs a clean session (/clear first), an irreversible external
step (push, deploy, production) or a human action outside the chat is not run — it becomes the Next: command. With
one sensible next step, or when AskUserQuestion is unavailable (claude -p, CI), skip the menu. The Next: line
always closes the answer.
Status colors. In the chat (not in files other tools parse) mark statuses so they scan at a glance: ✅ ok / done · ⚠️ not proven / warn / partial · ❌ missing / wrong / fail · ⏸️ BLOCKED · 🔄 in progress · ⏳ pending; verdicts and gates 🟢 PASS / pass · 🟡 PASS-UNPROVEN / warn / not proven · 🔴 FAIL / fail · ⚪ n/a; severity and risk 🔴 critical / High · 🟠 high · 🟡 medium / Medium · 🟢 low / Low. The marker goes before the word; the word stays.
File links. Every file you write or point the user to lives inside the session's working directory
(the folder Claude Code runs in — in a worktree, the worktree, never the main checkout), and its link is relative to
that directory: [intent.md](wordpress-plugin/x/docs/keystone/<task>/intent.md), not relative to a nested repo or a
subproject. Check the link before showing it: the app opens links only from the working directory. A file outside
it (Claude's memory under ~/.claude, another repository, a temp folder) is never a link — the app cannot open
it and shows "file not found", and a path in code becomes such a link too: give its absolute path as plain
text, without backticks. Link only a file you checked exists.
Step 0 — project context
Read, in this order, what exists: CLAUDE.md and .claude/CLAUDE.md; docs/architecture.md; .claude/rules/**/*.md; AGENTS.md.
Take the stack, architecture and non-functional requirements from there. MUST/MUST NOT
lines are project rules. Standalone use is fine: the user's own words replace missing files.
Step 1 — determine the mode
- Argument is
check→ Mode 3: Check progress (needsdocs/roadmap.md). - Otherwise
docs/roadmap.mddoes not exist → Mode 1: Create; exists → Mode 2: Update.
File format — docs/roadmap.md
# Roadmap
> <project vision — one line>
## Milestones
- [ ] M-1 <name> — <outcome: what is true when it is done>
- [ ] M-2 <name> — <outcome>
- [x] M-3 <name> — <outcome>
## Completed
| Milestone | Date |
|-----------|------|
| M-3 <name> | YYYY-MM-DD |
IDs are stable. M-<n> is assigned once, in creation order, and never renumbered, reused or reordered by number — an intent,
a plan or a commit may already point at it. Reordering priorities changes the line order only. A removed milestone keeps its ID
as a struck-out tombstone: - [ ] ~~M-4 <name>~~ — dropped YYYY-MM-DD: <reason>.
Mode 1 — create
1.1 Gather input. If $ARGUMENTS holds a vision or requirements, use it as the primary input. Otherwise ask once
(AskUserQuestion): "What are the major goals for this project?" — 1. Let me describe the vision · 2. Analyze the codebase and
suggest milestones · 3. Both: I describe, you add what is missing. For 1 and 3 collect the description, then ask: "Any priorities
or deadlines?" — 1. Yes, let me specify · 2. No, order by logical sequence · 3. Skip, I will reprioritize later.
1.2 Explore the codebase. Scan what is already built: Glob for the structure (key directories, modules), Grep for implemented
features (routes, models, services), git log --oneline -20 for completed work. Also list docs/keystone/*/intent.md — intents
with Status: accepted and a verified plan are evidence of done work.
1.3 Draft. Build the file in the format above.
- Each milestone is a high-level goal, not a granular task (that is
/keystone:plan). - 5–15 milestones is the sweet spot — fewer is too vague, more is too granular.
- Order by logical sequence, dependencies first.
- Mark already-completed milestones
[x], add them to the Completed table with today's date.
1.4 Confirm. Show the draft and ask: 1. Looks good — save it · 2. Add more milestones · 3. Remove/modify some · 4. Rewrite — I will give better input. Apply changes, show again, write only after "1" (see Writing).
Mode 2 — update
2.1 Read the current state: docs/roadmap.md, the project context, a brief look at the codebase for what changed since the
last update.
2.2 Determine the action. Arguments with new milestones or changes → apply them directly. No arguments → ask: 1. Review progress — check what is done, tick completed milestones · 2. Add new milestones · 3. Reprioritize · 4. Rewrite — major revision.
- Review progress → run the check logic of Mode 3 below, interactively.
- Add → ask the user to describe them; give each the next free
M-<n>; insert in logical order. - Reprioritize → show the current order, take the user's new order, move lines; IDs stay as they are.
- Rewrite → new vision/milestones allowed, but existing IDs keep their meaning; replaced ones become tombstones.
2.3 Save (see Writing), then print: Total milestones: N · Completed: X/N · Next up: M-<n> <name> and
To start on it: /keystone:intent <milestone outcome> (put Roadmap: M-<n> into the intent) or /keystone:plan <milestone> for a
small one.
Mode 3 — check progress (check)
Read-only scan; proposes ticks, changes nothing until confirmed. Requires docs/roadmap.md — if absent, tell the user to run
/keystone:roadmap first.
3.1 Read the roadmap and project context. 3.2 Collect evidence for every - [ ] milestone:
- Task folders:
docs/keystone/*/intent.mdthat carry a lineRoadmap: M-<n>, and theplan.mdbeside each. Read the plan headerStatus:.verified= done for that task;implementing/approved/draft= in progress. A milestone is done when every task folder pointing at it isverified(anabandonedone does not block if the rest are verified) and at least one of them isverified— abandoned-only means not done. A checked task box alone is not evidence — only the Status counts. - Code and git: what files, routes, models, configs or tests would prove the outcome?
Glob/Grepfor them;git log --oneline --all -30for related commits. Milestones with no task folder rely on this evidence alone — say so.
Score each milestone: done (strong evidence), partial (some work started), not started.
3.3 Report, in this shape:
## Roadmap progress check
✅ Done (ready to tick):
- M-1 <name> — evidence: docs/keystone/2026-10-01-auth/plan.md verified; src/auth/ exists
🔨 In progress:
- M-2 <name> — docs/keystone/2026-10-09-payments/plan.md implementing; Stripe webhook handler missing
⏳ Not started:
- M-3 <name>
Tick the done milestones? (1)
3.4 Apply (only if confirmed): mark the done ones [x] and add them to the Completed table with today's date. Partial and not
started stay unchanged. Print Completed: X/N · Next up: M-<n> <name>.
Writing — diff first, then yes
Every write to docs/roadmap.md (create, update, tick) goes through the same gate:
- Show the full text (new file) or a unified diff (update).
- Ask for an explicit yes. Changes requested → redraft, show again. No answer = nothing written.
- After the yes:
mkdir -p docs, write; on update use Edit and touch only the changed lines.
Closing note: /keystone:intent can record Roadmap: M-<n>; when a task bound to a milestone is accepted in /keystone:verify, this
skill's check mode is how the milestone gets ticked.
Critical rules
- Milestones are high-level — each is a major feature or capability, not a task.
docs/roadmap.mdis the source of truth — always read it before modifying.- Never remove milestones silently — always confirm with user before removing (and leave the tombstone, the ID stays taken).
- Completed table tracks history — every ticked milestone gets a date entry.
- IDs never change — no renumbering, no reuse.
- NO implementation — this skill only plans;
/keystone:planstarts a task,/keystone:implementexecutes it. - Ownership boundary — this skill owns the roadmap's structure and content; other skills may only propose a tick.