Skip to content

README.md

Latest commit

 

History

History
229 lines (188 loc) · 20.6 KB

README.md

File metadata and controls

229 lines (188 loc) · 20.6 KB
Raw

planning

A Claude Code plugin for the pre-implementation planning pipeline: everything between a rough idea and approved, executable work. Eleven pipeline skills covering charting a too-big, foggy effort as a decision map, divergence, product intent, the engineering contract, contract validation, hand-off of a decision another person holds, goal authoring, design exploration, the design→plan gate, adversarial review, and the implementation plan itself, plus a re-runnable setup action that settles where artifacts land in the consuming repo.

Skill Stage What it does
/planning:wayfind Chart Charts a too-big-AND-foggy effort as a shared decision map on the work-item tracker, then works its frontier one decision at a time, routing each to the right skill until the fog clears and a Brief / PRD / PLAN can be handed onward. An escalation from an interview that outgrew one session, never the first step.
/planning:brainstorm Diverge Turns a rough problem into codebase-grounded candidate approaches ordered cheapest→most ambitious; the user reacts, then work routes onward scoped.
/planning:prd Product intent Produces a Product Requirements Document (problem, users, success metrics) in three tiers (one-pager, consumer-feature, B2B-internal) with a synthesize path and a review mode. Acceptance-criteria capture asks once about missing unwanted-behavior and state-driven cases (skipped and reported unexamined on the synthesize path).
/planning:interview Engineering contract Locks a task contract (goal, constraints, acceptance criteria, named assumptions) into a PLAN.md Brief, synthesizing when intent is clear, running frontier-rounds Q&A when it isn't, or interviewing relentlessly on request. Acceptance-criteria capture asks once about missing unwanted-behavior and state-driven cases, and emits EARS-tagged criteria when the team's convention selects that format. The surface option can render rounds on a local page the session watches. The product action interviews a product idea against product principles and ends in a verdict.
/planning:audit-answers Contract validation Independent adversarial validation of a completed /planning:interview's answers, over any filled ledger, hand-answered or auto-accepted. Fresh-context validators re-examine each answer with its rationale withheld and return one verdict per answer: confirmed, challenged, or reclassified. Only the challenged and reclassified answers, plus every user-reserved decision, return as real human questions. Open branches are accept-filled first, holding the never-auto floor.
/planning:questionnaire Person hand-off Turns a decision another person holds into a discovery questionnaire delivered async. It interviews the user about the send only (recipient, what's needed back), writes the document to the topic's memory slice, and leaves delivery out-of-band.
/planning:draft-goal-condition Goal authoring Crafts a paste-ready /goal completion condition from a stated intent. It reads the current official /goal docs live for the condition shape and character limit (nothing hardcoded), drafts a transcript-demonstrable condition, and proves it fits the limit with a deterministic character counter instead of model guesswork, with a branch that builds a checkable condition for goals no metric can measure; a lever-fit gate routes interval-shaped, cloud/sessionless, orchestration-only, and multi-window / multi-ticket work elsewhere. Standalone.
/planning:design Design space Explores types, contracts, module boundaries, and package topology through collaborative discussion rounds, producing capability-matrix / type-inventory / design-threads / topology artifacts; its handoff action delegates to /planning:design-handoff. Its data, integration, and system artifacts are typed: each carries a scope + dialect label and a fenced block in the dialect the diagram_dialect convention key resolves to (mermaid erDiagram or DBML for data; mermaid sequenceDiagram plus an OpenAPI 3.1 sketch for integration; a LikeC4 or C4-PlantUML container view for system, and no C4 view at all when that key is unset). library and module emit no typed artifact.
/planning:design-handoff Design→plan gate Gates a finished design for /planning:plan. The gate is a binary check that every design-threads.md thread is RESOLVED, directional, or TAGGED-DEFERRED. Then it packages the plan-ready summary and resume prompt, or FAILs and routes back to /planning:design. On PASS and FAIL alike it also emits an advisory six-dimension coverage table (what, how, where, who, when, why) that never contributes to the verdict; uncovered dimensions ride along in the handoff summary and the resume prompt.
/planning:devils-advocate Adversarial review Stress-tests plans via assumption extraction, evidence checks, failure scenarios, and operational-gotcha sweeps. Every finding evidence-backed, never generic warnings. An incumbent mode turns the same lens on the status quo: an Alternatives Sweep that stress-tests keeping an incumbent tool/approach against alternatives (native > official > vetted ladder, coupling priced, KEEP / MIGRATE / RESEARCH verdict), exploring the incumbent first-hand in a fresh sub-agent.
/planning:plan Implementation plan Produces a structured plan (goal, approach, test strategy, blast radius, parallelism analysis, tagged unilateral decisions) with a mandatory fresh-context plan-reviewer stress-test and a user approval gate, persisted to PLAN.md.
/planning:setup Configuration check inspects the standards index read-only; apply interviews the consumer and bootstraps the standards index (idempotent; re-run to reconfigure).

The pipeline composes end-to-end. wayfind charts the fog upstream when an effort is too big to hold at once, then brainstorm → prd → interview → design → design-handoff → plan with devils-advocate attacking the plan before approval, while /domain-driven-design:curate-language is invoked whenever those workflows resolve vocabulary, when the domain-driven-design plugin is enabled; without it, resolved terms are recorded in the design artifacts themselves. Every skill also works standalone.

Workflows

  • /planning:plan-panel (workflows/plan-panel.js). A multi-angle plan panel that /planning:plan launches, opt-in, for a hard or wide plan: one planner per angle (MVP-first, risk-first, reuse-first and testability-first by default), independent judges that score every draft on goal fit, blast radius, test strategy and reversibility, and one synthesizer that builds the plan from the winner and grafts runner-up ideas. Its args carry task (required; without it the run dispatches nothing), context, angles, judges (default 3), roles and maxConcurrent (default 4). roles is the map /multi-agent:route all prints. Without it, built-in fallbacks run planners on opus at medium effort and judges on opus at high, and the synthesizer inherits the session model at high. It returns the plan, the scores, the grafted ideas, the dissent and every draft; the synthesized plan goes through the skill's reviewer and approval gate. When the Workflow tool is absent, /planning:plan formulates the single plan as before.

Works in any repo

  • Reads your conventions, assumes none. Project rules, naming conventions, review checklists, domain-vocabulary files, and commit policy come from your own project's CLAUDE.md and rules; where none exist, the skills apply standard engineering defaults.
  • Graceful degrade. Adjacent capabilities are invoked when enabled: codebase exploration and external research (discovery), test-design guidance (tdd), prototyping (prototype), decision recording (architecture), and session handoff (session-flow). Missing plugins get inline guidance; no step blocks.
  • Self-contained assets. Templates and reference files ship inside the plugin; planning artifacts land in the self-ignoring memory slice <memory_dir>/<topic-slug>/ (default .work/). Never in plugin-internal paths.

Install

/plugin marketplace add melodic-software/claude-code-plugins
/plugin install planning@melodic-software

Configuration

Where artifacts land is set by the plugin's lifecycle artifact protocol (reference/artifact-protocol.md): every working artifact (PRD.md, PLAN.md, design/, checklists, baselines, scratch) goes to the self-ignoring <memory_dir>/<topic-slug>/ (default .work/) and is never committed. Durable content is published to the pull request body and the linked issue. Run /planning:setup check to inspect the standards index read-only, or /planning:setup apply to bootstrap it.

The format acceptance criteria are written in is a separate, optional team-shared choice. /planning:interview and /planning:prd read acceptance_criteria_format from <home>/authoring-formats/README.md, where <home> is the convention home bound by the pointer line in your root instruction file. ears tags every emitted criterion with one of five bracketed patterns (ubiquitous, event-driven, state-driven, unwanted-behavior, optional-feature); free-text is the default and emits prose criteria untagged, exactly as before. Every failure to resolve degrades to free-text with the cause named, whether that is no pointer line, no such document, no such key, or an unrecognized value, so a repo that declares nothing sees no change in output.

Option details

surface. A value other than terminal or page falls back to terminal.

plan_store. A repository sets it for everyone with plan_store: local or plan_store: tracker in docs/conventions/planning.yaml (schema: schemas/planning.schema.json), which wins over this option. Any other value resolves local. tracker needs the work-items plugin and a claimed item.

plan_reader. How much of an approved plan reaches the work item and the pull request paste: step-by-step (default) the whole plan, standard the design plus a phase outline, guardrails the design alone, each reduced copy also keeping the Brief. A reduced depth publishes a derived file and leaves PLAN.md whole. --reader <depth> on /planning:plan overrides it for one run, and the plan records the depth it published at so a later close-out keeps it. A repository sets it for everyone with the plan_reader key in docs/conventions/planning.yaml, which wins over this option. A value outside the three, --reader included, is named and that layer is dropped: a valid higher layer still wins, otherwise the plan publishes step-by-step, never a lower layer's value. /planning:setup apply plan_reader=<value> writes the repository file.

phase_order. Decides the order of a plan's phases after the build technique is chosen. composed removes dead code the change touches first (a bug fix skips this), then builds the integration slice, then the riskiest remaining unknown, then scaffold, then the remaining features. subtraction-first runs dead-code removal, then scaffold, then features. riskiest-first puts the step whose failure would invalidate the most later work first. A repository sets it for everyone with the phase_order key in docs/conventions/planning.yaml, which wins over this option. A value outside the three is named and that layer is dropped; with no valid layer left the plan uses composed. /planning:setup apply phase_order=<value> writes the repository file. All keys and layers: reference/config.md.

scaffold_stubs. Off by default. When on, /planning:design lists each new file the design needs with the signatures it will declare, and /planning:plan turns that list into one stub phase right after the dead-code removal step (first when there is none). Stub bodies use the language's ordinary not-implemented form, and a stub phase that leaves the build or tests red declares it with a **Planned breakage:** line. A repository sets it for everyone with scaffold_stubs: true or scaffold_stubs: false (bare booleans; a quoted "true" is invalid and that layer is dropped) in docs/conventions/planning.yaml, which wins over this option. /planning:setup apply scaffold_stubs=true writes it.

use_emoji_question_markers. On the page surface the anchors sit on the question title and the Recommendation heading; the terminal line they lead is My recommendation:. Q numbering stays the functional handle, and persisted artifacts (ledger, register, Brief) never carry the emoji. A user instruction against emoji wins over this option, and the page is then started with --emoji-markers false so it matches the terminal.

Options reference

Generated from this plugin's .claude-plugin/plugin.json. Every option Claude Code will prompt for when the plugin is enabled, with the environment variable each hook reads it from.

Option Type Default Environment variable Description
surface string "terminal" CLAUDE_PLUGIN_OPTION_SURFACE Where /planning:interview renders its question rounds: terminal (default, inline in the conversation) or page (a local 127.0.0.1 page the session watches, where each question is answered and every save reaches the session). Applies only to /planning:interview.
question_pacing string "round" CLAUDE_PLUGIN_OPTION_QUESTION_PACING How /planning:interview asks a frontier: round (default, every ready question in one message) or single (one per message, largest blast radius first). Asking for the other pacing in a session overrides it there; a repository's planning.yaml in its convention home overrides this value.
use_ask_user_question boolean false CLAUDE_PLUGIN_OPTION_USE_ASK_USER_QUESTION When enabled, the planning skills' question rounds (interview, prd, design, plan) render a round of independent questions that fits one AskUserQuestion call instead of inline prose. Default: inline prose (dictation-friendly).
use_emoji_question_markers boolean false CLAUDE_PLUGIN_OPTION_USE_EMOJI_QUESTION_MARKERS When on, each interview round question leads with a ❓ anchor on its Q line and its My recommendation line leads with ➡️, in the terminal and on the page surface. Purely presentational: persisted artifacts never carry the emoji. Default: plain text.
shared_session_open_browser boolean true CLAUDE_PLUGIN_OPTION_SHARED_SESSION_OPEN_BROWSER When on, starting a /planning:interview shared session opens the owner's page in the default browser. Turn off to open it yourself. Default: on.
tunnel_hostname string (none) CLAUDE_PLUGIN_OPTION_TUNNEL_HOSTNAME Hostname of a named Cloudflare tunnel for /planning:interview shared sessions (such as interview.example.com), so the guest link survives a restart. One session serves it at a time; others get a quick tunnel. Empty (default): a quick tunnel, whose link changes on restart. Setup: shared/README.md.
tunnel_token_file string (none) CLAUDE_PLUGIN_OPTION_TUNNEL_TOKEN_FILE Absolute path, or one starting with ~/, of a file holding the named tunnel's token, readable only by you; cloudflared runs from it. Used only when tunnel_hostname is set. Default: empty.
tunnel_api_token_file string (none) CLAUDE_PLUGIN_OPTION_TUNNEL_API_TOKEN_FILE Absolute path, or one starting with ~/, of a file holding a Cloudflare API token with Cloudflare One Connector: cloudflared Write (it can change every tunnel in the account), readable only by you; sessions check connectors and route the tunnel to their port. Empty: port 8765. See shared/README.md.
plan_store string "local" CLAUDE_PLUGIN_OPTION_PLAN_STORE Where /planning:plan keeps an approved plan: local (default, PLAN.md in the memory slice only) or tracker (also posted as one comment on the claimed work item). A repository's docs/conventions/planning.yaml plan_store key overrides this value.
plan_reader string "step-by-step" CLAUDE_PLUGIN_OPTION_PLAN_READER How much of an approved plan /planning:plan publishes: step-by-step (default, the whole plan), standard (Brief, design, phase outline) or guardrails (Brief and design). A --reader argument overrides it per run; a repository's docs/conventions/planning.yaml plan_reader key overrides this value.
phase_order string "composed" CLAUDE_PLUGIN_OPTION_PHASE_ORDER How /planning:plan orders phases: composed (default: dead-code removal, integration slice, riskiest unknown, scaffold, features), subtraction-first (removal, scaffold, features) or riskiest-first. A repository's docs/conventions/planning.yaml phase_order key overrides this value.
scaffold_stubs boolean false CLAUDE_PLUGIN_OPTION_SCAFFOLD_STUBS When on, /planning:design hands off the stub files and signatures a change needs, and /planning:plan puts one stub phase right after dead-code removal (first when there is none). Default: off. A repository's docs/conventions/planning.yaml scaffold_stubs key overrides this value.
time_units boolean false CLAUDE_PLUGIN_OPTION_TIME_UNITS When on, the planning skills may state an estimate or budget of work in hours, days or weeks; when off they use the work_size levels instead. Practice cadence and measurement windows are not affected. Default: off. A repository's docs/conventions/planning.yaml time_units key overrides this value.

How to set these

Three supported routes:

  1. Interactively. Open this plugin's options dialog (/plugin in a session): /plugin configure planning@<marketplace>.

  2. Headless. Save the values with claude plugin configure, run from the project the plugin is installed in. Replace <marketplace> with the marketplace you installed this plugin from:

    claude plugin configure planning@<marketplace> --values-stdin < values.json

    values.json holds a JSON object of strings, booleans included:

    {"surface": "<value>"}

    This is the preferred headless route in the plugin-reconfiguration convention, which records its limits: the Claude Code version it needs, which install it finds, how it rejects a bad value, and why a session started before the change keeps the old value until a fresh session starts. Do not claude plugin uninstall to reconfigure: see What an uninstall deletes and keeps.

    The fallback the convention names, for a Claude Code release without plugin configure, reruns the install with the new value, passing the scope claude plugin list reports for this plugin:

    claude plugin install planning@<marketplace> -s <scope> --config surface=<value>

  3. By hand, in settings. Add the value under pluginConfigs in your user settings (~/.claude/settings.json):

    {
  "pluginConfigs": {
    "planning@<marketplace>": {
      "options": {
        "surface": <value>
      }
    }
  }
}

    The pluginConfigs entry names the settings scopes Claude Code reads this key from.

Do not set the CLAUDE_PLUGIN_OPTION_* variables yourself; set the value through one of the routes above.

Upstream documentation

License

MIT (SPDX-License-Identifier: MIT).