Keystone · plan — a plan an engineer can implement without this conversation
Chain: intent.md → plan → code → verify (Anthropic AI-native SDLC playbook, adapted: the plan is the spec, there
is no separate spec document). Output: plan.md with Status: draft, then approved on the human's Approve.
Format, template, example task, logging checklist and the Required Detail Gate:
read ${CLAUDE_SKILL_DIR}/references/PLAN-FORMAT.md before writing the plan.
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.
Do not skip a step: re-read the step list before you finish and confirm each applicable one is done.
Step 0: Level, input, project context
Level. Take it from the argument (S / M / L) or from what /keystone:start decided in this conversation.
If it is not set, propose one by the /keystone:start signs and confirm once (AskUserQuestion, recommended first):
Level: <S|M|L> — <one-line reason>. OK / S / M / L? Any single L sign (several user decisions, data/schema/migration,
security/auth/payments, a module owned by others, unclear "done") makes it L.
- S — no plan. Say: "this is S — make the change directly and run the check, or use
/keystone:fixfor a bug", and STOP. Do not write a plan file. - M. Task text in, plan out, in a new folder
docs/keystone/<YYYY-MM-DD>-<slug>/(a new folder only on M). No intent required, no/keystone:check. - L. Intent mode (below). No intent given → recommend
/keystone:intentfirst and stop unless the user says "Plan anyway".
Task folder. docs/keystone/<YYYY-MM-DD>-<slug>/ (slug: lowercase, hyphenated, ≤ 50 characters).
Active plan = the plan.md of the newest task folder under docs/keystone/ — newest by the date prefix of the folder name,
ties broken by the plan.md modification time — whose Status is draft, approved or implementing. A plan elsewhere (an older
task folder outside docs/keystone) is used only when its path is given explicitly as the argument. A new plan always goes
under docs/keystone/ — also when its intent or an older plan lies elsewhere: the gates and the band see only that folder.
Existing plan (one plan per task). If the argument is a path to an existing plan.md (or its folder) with
Status: draft, do not create a folder or rewrite the plan: go straight to § Before approval → § On Approve (used by
/keystone:fix M, /keystone:implement draft-stop, /keystone:check, and a plan with open questions). If a plan for
this intent/task already exists (in the task folder), refine it
instead of creating a second one.
Intent mode — the argument is a path to an intent.md or to a folder that contains one. Always L.
plan.md is written into the SAME folder as intent.md (no new folder). Read intent.md in full; it is an authoritative
source for the gate, the chat is not. If the argument is plain task
text, it is the request (M); an intent file that sits next to it is then not assumed.
Original Request. The text the user gave, after the level token is removed and only outer whitespace is trimmed.
Preserve internal whitespace, line breaks, wording, casing and punctuation exactly. It goes into the plan under
## Original Request; do not rewrite, summarize, translate or normalize it. In intent mode the request is the user's
words that came with the path; if there were none, the intent's Problem line is cited instead and the section says so.
Project context. Read, in this order, what exists: CLAUDE.md and .claude/CLAUDE.md; docs/architecture.md;
.claude/rules/**/*.md (a rule with paths: frontmatter applies only to matching files); AGENTS.md if present.
MUST / MUST NOT lines there are
project rules. Use this context when exploring, writing task text (correct
technologies) and planning file structure (follow project conventions and layer boundaries). Treat explicit rules as
authoritative requirements: more specific area rules override base rules, which override project-wide axioms.
Rules beat the template: if a project rule says "tasks MUST include X" or "plan MUST have section Y", augment the
template accordingly. After generating the plan, verify it against every such rule and fix violations before you
present it — a plan that breaks a project rule is a bug.
Settings — do not ask. Infer from the repo and write one line in the header; the human adjusts it at Approve:
tests— yes if a test runner or test files exist, no otherwise (say which);logging— minimal / standard / verbose from the existing logger and its habits (no logger → minimal);docs— yes ifdocs/or a README with usage sections exists, no otherwise.
The line binds the rest of the work: no test tasks when tests — no; log instructions in tasks follow logging.
Intent status gate (L). Read the Status: line of intent.md. If it is not accepted, emit
WARN [keystone] <file> is <status>, not accepted — the human has not signed it off, ask once (AskUserQuestion:
"Plan anyway" / "Stop — I'll review and run /keystone:intent accept first"; recommend Stop) and continue only on an
explicit "Plan anyway". Record it in the header as (planned from <status> intent — accepted by user at planning time).
Do not edit the intent while planning; if a resolved conflict narrows an outcome, tell the user to update it
(/keystone:intent) and record the narrowing in the reconciliation row. Open questions in the intent that block a
decision you need are user-owned decisions → § Clarifications.
Step 1: Reconnaissance
From the request extract the core functionality, key domain terms and type (feature, enhancement, fix, refactor).
Use the Task tool with subagent_type: Explore to understand the relevant parts of the codebase. It runs as a
subagent and keeps the main context clean. Launch 1-2 Explore agents in parallel:
Task(subagent_type: Explore, model: haiku, prompt:
"In [project root], find files and modules related to [feature domain keywords].
Report: key directories, relevant files, existing patterns, integration points.
Thoroughness: quick. Be concise — return a structured summary, not file contents.")
This is reconnaissance, not deep analysis; deep exploration happens in Step 3. If the project docs already give sufficient context, skip it.
Step 2: Analyze requirements and reconcile them
Identify: core functionality to implement, components/files that need changes, dependencies between tasks, edge cases to handle. If requirements are ambiguous, ask clarifying questions before planning.
Clarifications
If the open user-owned decisions contain a dependency edge (answer B depends on answer A), clarify by the
/keystone:grill contract instead of scattered questions; a single fork or a batch of independent questions stays an
ordinary question. Facts from the codebase are looked up, never asked. Confirmed decisions go to the intent's
## Decisions log only by telling the user to update the intent — the plan does not edit it.
Requirements Reconciliation Gate
For work governed by existing requirements, reconcile them before exploring an implementation:
- Treat roadmap items and task summaries as scope indicators, not detailed behavioral contracts, unless the project explicitly declares otherwise.
- Follow any source-priority hierarchy declared by the user or project context. If no hierarchy exists, do not
silently choose between conflicting sources. With an intent the default is:
intent.mdowns what (Problem, Desired outcome, Constraints); project rules constrain how. A rule that makes an intent line impossible is a conflict. - Record each material behavioral rule with its source path/section. When two sources overlap, state whether they agree, one refines the other, or they conflict. When an unresolved conflict would change the implementation: ask the user and STOP.
- Do not edit source requirements while creating the plan. Report stale or contradictory artifacts and route them to their owner command or the user.
When behavior depends on two or more independent selectors, states, modes, or input shapes, enumerate the supported combinations before writing tasks. Cover only combinations allowed by the requirements, not a speculative Cartesian product. For each material combination specify:
- accepted input and validation;
- persisted state;
- returned output or next transition;
- side effects and invariants;
- one verification scenario. If testing is enabled, make it a test; otherwise provide a runnable/manual verification step without adding a test task.
When repository data, configuration, fixtures, schemas, or content define the real contract, include at least one representative existing artifact in an end-to-end verification path instead of validating only synthetic fixtures.
Keystone rows. Every intent Desired outcome line and every Constraint line is its own row of the table in the
plan's ## Requirements Reconciliation, cited intent — I-n — including "must not break" constraints (prove them with
a check that the protected code/path is untouched). An intent without IDs: cite Desired outcome #n / Constraint #n.
Other material rules cite <path> — <section>. An outcome only a release step can prove (a publish, a deploy, a
production check) gets proved by R<n> as its evidence and a step R<n> with a check: in ## Release. Self-check before saving: every non-struck I-n has a row; an outcome
without evidence is a gap — add a task or a check, do not drop the row. Without an intent, include the section only
when several authoritative sources constrain the work, a conflict was resolved, independent dimensions exist, or a
real artifact is required.
Step 3: Explore the codebase
Before planning, understand the existing code through parallel exploration. Launch 2-3 Explore agents
simultaneously, each on a different aspect (model: haiku):
Agent 1 — Architecture & affected modules:
Task(subagent_type: Explore, model: haiku, prompt:
"Find files and modules related to [feature domain]. Map the directory structure,
key entry points, and how modules interact. Thoroughness: medium.")
Agent 2 — Existing patterns & conventions:
Task(subagent_type: Explore, model: haiku, prompt:
"Find examples of similar functionality already implemented in the project.
Show patterns for [relevant patterns: API endpoints, services, models, etc.].
Thoroughness: medium.")
Agent 3 — Dependencies & integration points (if needed):
Task(subagent_type: Explore, model: haiku, prompt:
"Find all files that import/use [module/service]. Identify integration points
and potential side effects of changes. Thoroughness: medium.")
M: one wave (1-2 agents) is enough. L: as needed, facts only. Use the Step 1 reconnaissance as a starting point and focus
the agents on areas that need deeper understanding. After they return, synthesize: which files to create/modify, what
patterns to follow, dependencies between components, potential risks or edge cases. If Task is unavailable, use
Glob/Grep/Read directly.
Step 4: Write the plan
Create the task folder and write plan.md in the shape of references/PLAN-FORMAT.md, in this order: header
(Level · Mode: feature · Status: draft, Authority: line when an intent exists, Settings: line, then Done means: — verifiable outcomes, on L from I-n, on M from the request) · Original
Request · Design (optional) · Requirements Reconciliation table + Project rules check: line · Risks · Tasks · Commit
Plan (5+ tasks) · Release (only when the change ships: merge, push, deploy, production jobs — never as Tasks).
Task requirements. Every task has a clear deliverable and expected behavior, file paths to change/create, a
verifying check, logging instructions as the logging Settings value asks, dependency notes when applicable, and
requirement source anchors plus applicable behavior combinations when the gate applies. Each task is completable in one
focused session; tasks are ordered by dependency (do X before Y). Run the Required Detail Gate from the reference on
every task: no "handle / support / wire up / as needed / etc."; an undecidable point becomes a blocking open question.
Rules check. One line after the reconciliation table (after Settings: when there is none):
Project rules check: read <files> — MUST violations: none (/keystone:check later adds its Coverage: line directly
after it). Check the text of every task — including its Logging and Testing lines — against each MUST/MUST NOT (e.g. rule
"log only rows/leads/code" vs a task "log { code, message }" is a violation: fix the plan before Approve). List every
MUST/MUST NOT the plan would break as
MUST violations: <rule> — <task>. A MUST violation is a blocker, not a risk: fix the plan or ask the user.
If docs/architecture.md exists, the Rules check includes its layer dependency rules: a task whose files import across a
forbidden direction is a MUST violation like any other.
Risks. ## Risks after the Rules check line: Could break: / Riskiest step: / Rejected alternatives: — three
lines on M, more allowed on L.
L touching security / auth / payments / PII (the L sign from /keystone:start): add a Threats: block to Risks — one
line per threat (what an attacker or a mistake could do, where, and the task that closes it) — and add a task
Run /keystone:security <scope> — files: … — check: Security gate pass|warn before the final verify. Not security → no
block, no task.
Important rules
- No tests if Settings say no — don't sneak in test tasks.
- No reports — don't create summary/report tasks at the end.
- Actionable tasks — each task has a clear deliverable.
- Right granularity — not too big (overwhelming), not too small (noise).
- Dependencies matter — order tasks so they can be done one after another.
- Include file paths — help the implementer know where to work.
- Commit checkpoints for large plans — 5+ tasks need a commit plan with checkpoints every 3-5 tasks.
- Reconcile before planning — do not let a roadmap summary, lower-priority source, or internally consistent implementation override an unresolved behavioral requirement.
- Ownership — this skill writes only the plan file; intent, rules and roadmap belong to their owners.
Before approval
- Answer against the draft and fix it: What could this change break? Which step is the riskiest? What did you reject, and why? Apply the readiness bar: an engineer who never saw this conversation can implement from the plan alone — every task names files, nothing says "as discussed", every reconciliation row has evidence.
- L only — independent check. Invoke the Skill tool with
keystone:checkand the arguments<intent path> <plan path>. It orchestrates fresh-context Opus agents from the main context. Fix everymissing,unrequestedand rule violation it reports and run it again; keep its finalCoverage: … verdictline. Never self-check in this context instead. - Show the user the three answers (2-5 lines) and, on L, the coverage line, plus the
Settings:line (they may change it). Then AskUserQuestion: "Approve plan" / "Adjust". On "Adjust", revise and repeat.
On Approve
Set Status: approved in the plan header. Make the baseline commit of intent and plan by the project's commit
convention (the chain is the audit trail; stage only the task folder). Then tell the user:
Commit scope. If the project has commitlint (.commitlintrc*, commitlint.config.*, or a commitlint key in
package.json) with a scope-enum rule, use only a scope from that list — the closest one (e.g. docs), or no scope
if the rule allows it; never a scope the hook rejects. No scope list → keep the Keystone scope (docs(plan)).
- implement in a fresh session — a new conversation or
/clear(not/compact) — with/keystone:implement <plan path>; Sonnet is enough for a plan this explicit; - finish with
/keystone:verify; - while the plan is
draft, a hook refuses code edits outsidedocs/keystone/; lift it withStatus: abandonedin the header or the env varKEYSTONE_GATES=off.
STOP after planning; the user decides when to implement. If the plan is not ready for implementation (a blocking open
question remains), say so, leave it draft, and list the questions.
Suggest freeing context before implementation: /clear (full reset), not /compact.
Project memory (memlab, optional)
If memlab is available, use it before broad exploration: search_code for the files and symbols the tasks will touch
(then read point-wise at the returned path:line), search_decisions for prior decisions, ADRs and postmortems on the
same area. A prior decision is a source in the Requirements Reconciliation Gate like any other: cite it, and treat a
conflict with it as a conflict (ask and STOP). No memlab — Explore as above.