Planning Skills for Agents and Humans

Turn a fuzzy feature into a selected, testable, vertically sliced implementation packet—without letting the agent invent scope.

These skills help product and engineering teams preserve intent from raw evidence through implementation. They are most useful for strategically important feature work with a bounded appetite, usually a 2–6 week bet for a small launch team.

New here? Start with the 10-minute guide.

Interactive documentation portal

The repository includes a self-contained documentation portal at site/index.html. Download that one file and open it in a modern browser; it does not need a web server, package install, or network connection at runtime.

The portal includes the workflow explorer, searchable skills catalog, full guide reader, canonical skill references and templates, and example artifact trails. Its content is generated from this repository's canonical Markdown files and works offline after download. See site/README.md for browser support, rebuild, and validation commands.

See it work in practice

If you would rather watch the method operate than read its parts, follow How Planning Skills works in practice. It takes one plain grocery-list idea from messy notes and a sketch through /plan, framing, shaping, a code spike, breadboarding, visual reconciliation, human selection, bounded build context, implementation, and reflection. It also shows when not to invoke an advanced skill. The walkthrough is illustrative, not a required sequence.

Get Planning Skills into your agent

Do not paste this entire repository into every prompt. Make the reusable skills available to your agent once, then do the real planning inside the product repository you are building. Project-specific artifacts normally live under planning/ beside the code they govern.

The shortest current paths are:

Codex workspaces can also import this repository as a GitHub plugin marketplace; other agents can consume the canonical SKILL.md files directly. See Install Planning Skills, then use them in your product repo for the complete setup and the distinction between installation, invocation, and project context.

When should I use these skills?

You do not have to begin your idea inside this repo.

Start wherever it is easiest to think: a conversation, whiteboard, document, Claude Design, Codex, rough prototype, pile of notes, a set of requirements, or a solution already in your head.

Use these skills when the idea becomes important enough that you do not want its meaning to live only inside a conversation or disappear between prompts. This repo is the bridge between playing with an idea and building it deliberately.

That usually happens when:

• there are several plausible ways to solve the problem
• you already have a solution idea but do not yet know which needs or constraints it truly serves
• a prototype looks promising, but you do not yet understand how it should behave
• an agent is about to modify a real codebase
• the work will take days or weeks rather than minutes
• several people or agents need to share the same understanding
• important requirements, boundaries, or decisions could easily be forgotten
• you need to hand the work from exploration into implementation
• implementation may be drifting away from the original intent

The core principle

Start where the useful thinking already is. Exploration is fluid. Commitment is gated.

During collaborative shaping, you can start from requirements (R-first), a proposed solution (S-first), a prototype, current-system evidence, a fit question, or an unknown worth spiking.

Requirements, shapes, fit checks, focused spikes, sketches, and candidate breadboards may inform one another in any useful order while they remain working material:

requirements (R) ↔ shapes (S) ↔ fit checks
      ↑                ↕             │
      └── discoveries ← spikes / candidate breadboards / sketches

What stays strict is promotion:

• working requirements must be accepted before they judge final selection
• Appetite and cut line must be accepted before shape selection
• a human explicitly selects the direction
• candidate evidence does not become selected-design intent without reconciliation
• selected-design intent is accepted before slicing
• a human-selected slice bounds implementation

If a team, CI harness, or multi-agent planner needs deterministic prerequisites, use the gated/orchestrated profile in .agent-orchestration.yaml. The formal route remains available; it is no longer the only legal order for exploration.

It is a mode switch, not necessarily a tool switch

You can use the same agent for exploration, planning, and implementation. What changes is what you ask it to do:

• Explore: “Help me think through this idea. Show me possibilities.”
• Shape collaboratively: “Capture what I have, separate requirements from mechanisms, and move among R, S, fit, spikes, and candidate breadboards as useful. Do not select for me.”
• Shape with strict gates: “Use the gated profile and enforce each prerequisite before the next controlled step.”
• Build: “Implement only this selected slice. Preserve these requirements and verify it against the breadboard.”

A practical workflow is:

1. Start with whatever you actually have: R, S, evidence, or a prototype.
2. Use the smallest move that resolves the current uncertainty.
3. Let working R and S revise one another through fit checks, spikes, sketches, and candidate breadboards.
4. Accept requirements and Appetite when they are good enough to constrain a real decision.
5. Make the human decisions about direction and scope.
6. Reconcile the selected direction into accepted behavior.
7. Give the coding agent a bounded slice and compact context packet.
8. Check drift as implementation evolves.

For example, you might begin in Claude Design with a rough interface or in Claude Code with a solution idea. Capture that as candidate Shape A, extract provisional requirements from it, run a working fit check, spike the uncertain parts, breadboard only the behavior that is still hard to judge, then accept the judging criteria and Appetite before choosing a direction.

If you are using Claude Design together with the Planning Skills repository, see Using Claude Design with the Planning Skills Repository.

You can also begin directly in Codex. For a small, obvious task, just make the change. For a larger or ambiguous task, tell Codex to use the relevant planning skill. You can choose collaborative shaping or the gated profile explicitly.

Do not add planning ceremony where it provides no value. A small copy change, contained bug fix, disposable experiment, low-risk script, or already-clear change may not need the full workflow.

Use the smallest planning move that prevents an important misunderstanding.

Use the skills in the repository where the product is being built

Install or reference these skills once, then open the product repository you are actually working on. The Planning Skills repository supplies the method and reusable instructions; project-specific frames, shaping decisions, breadboards, slices, and implementation packets should normally live beside the product code they govern.

Do not replace an existing project AGENTS.md with this repository's file. Prefer an installed plugin, point the agent at the relevant canonical SKILL.md, or selectively merge the planning rules that fit the project. Existing product-specific instructions remain authoritative for that codebase unless the team explicitly changes them.

See Using Planning Skills in a product repository for the practical setup.

Recommended project layout

A simple default is:

planning/
  wayfinding/          # optional multi-session coordination maps and tickets
  frame.md
  shaping.md
  appetite.md          # optional when the appetite needs its own decision record
  candidate-A-breadboard.md  # optional exploratory evidence during shaping
  breadboard.md        # accepted selected-design intent
  sketch-reconciliation.md
  statechart.md
  slices.md
  interface-contracts.md
  executable-breadboard.md
  dumplink.md
  kickoff.md
  context-packet.md
  spikes/
  runs/                # lightweight agent run logs for empirical shaping feedback

This is a convention, not a requirement. Keep one clearly active artifact for each authoritative planning level unless the project intentionally versions them. Candidate breadboards remain subordinate to their named candidate and shaping artifact. Preserve rejected alternatives in shaping, keep tables authoritative over generated diagrams, and treat run logs as audit records rather than product truth.

Choose the handoff artifact by its job

A common controlled path is: accepted criteria and Appetite → candidate shapes ↔ candidate breadboards or focused spikes when needed → human-selected shape and project boundary → accepted selected-design breadboard → optional Dumplink to create sequenced vertical task groups → human-selected active task group or other demoable slice → interface contracts and executable breadboard when needed → optional kickoff reference → context packet → implementation.

That path is useful for automation and teams that want stronger ceremony. Collaborative shaping may enter and move among R, S, fit, spikes, and candidate breadboards before those judging inputs are accepted. The same promotion gates apply before selection and build.

Set Appetite before selecting a shape. Use the Appetite section in the shaping template for a compact decision or the standalone appetite card when ownership, rationale, and revisit conditions need their own record.

An estimate is not a prediction made before the work. It is the output of preliminary design work. First, decide how much the problem or opportunity is worth pursuing. That determines the time budget. Then dig into the problem, reduce the important unknowns, and shape a solution whose scope is commensurate with that budget. You do not first estimate the ideal solution and then decide whether you can afford it. You decide what the opportunity is worth, then design the best solution that fits within that constraint.

Agent execution appetite

Product Appetite answers how much human/team time the product bet is worth. For a meaningful implementation run, derive a smaller execution appetite that answers: what is this run worth in human attention, when is it needed, what MUST be protected, what NICE scope should be cut first, and when should the agent stop or return to planning?

An agent may propose that run-level appetite, but a human must explicitly accept it before implementation begins. Keep model pricing, token accounting, turns, and vendor-specific breakers under the hood as optional runtime guardrails. After meaningful runs, capture a lightweight record under planning/runs/ so future shaping can learn from actual execution rather than estimates.

See Agent Execution Appetite and the run-record template.

Shape the product before you build it. Shape the run before you execute it. Learn from both.

Opportunity underwriting

When the unresolved question is whether a business or market opportunity is worth pursuing at all—rather than what product to build—use the sibling Opportunity Underwriting for Agents and Humans repository.

Its first canonical skill, Market Opportunity Underwriting, uses crux-first research, fatal gates, bottom-up sizing, explicit NOT_KNOWABLE_FROM_DESK_RESEARCH states, reachability rather than arbitrary “percent of TAM” SOM, and adversarial evidence to support a PURSUE / TEST / HOLD / REJECT decision. It is a business-level evidence and economics method, not a mandatory stage of this product-planning workflow.

The relationship is bidirectional rather than a conveyor belt. Opportunity Underwriting may invoke Lead User Research when a load-bearing uncertainty concerns future-facing needs, advanced users, emerging workarounds, or transferability. Lead User Research may in turn hand off to Opportunity Underwriting when it establishes an important need but the remaining question is whether that need constitutes a sufficiently large, reachable, economically attractive market. Neither research method automatically promotes its conclusions into accepted product-planning truth.

Lead User research

For future-facing opportunity discovery, use Lead User Research. It applies Eric von Hippel's Lead User Method through a lightweight, phase-gated research workflow with persistent evidence state, pyramiding, advanced analogs, coverage-bias controls, and proportionate SCOUT / STANDARD / FULL modes.

It is designed to work across ChatGPT, Claude, Gemini, Codex, Cursor, and other tool-using AI environments. For the lowest-friction path, copy the portable prompt into the AI platform of your choice and fill in the research brief: domain/problem space, target market, what you want to understand, the human decision the research should inform, desired innovation altitude, optional hypotheses, and mode. You may also provide optional discovery seeds (sources, communities, files, people, experts), candidate-profile hypotheses (types of users or situations worth looking for), and explicit search constraints. Seeds and candidate profiles guide discovery without prequalifying Lead Users or closing the search universe unless the human explicitly imposes a constraint. The quick guide and fill-in research template cover file-backed and no-file workflows. If only the domain and decision are known, Phase A can draft the missing fields as PROVISIONAL rather than silently inventing them. The full protocol stays available for audit without requiring one giant memory-dependent prompt.

Lead User Research is an optional upstream evidence lane, not a mandatory stage before framing. Use it when the opportunity itself depends on future-facing trend and advanced-user evidence. After completion, its implications require explicit human acceptance before they feed framing-doc; the research record remains cited evidence rather than automatically becoming product-planning truth.

Claude Code provides namespaced Lead User command wrappers. Gemini exposes the same repo-local command aliases only when .gemini/commands/ is present in the active project; a native Gemini skill install uses natural-language phase requests instead. Codex and other skill-capable agents likewise invoke the canonical skill and name the phase in natural language. Every phase ends by recommending exactly one next move, looping back when sufficiency fails and skipping concept generation when no need passes the gate.

The core workflow

Collaborative shaping loop

start from R, S, evidence, prototype, fit question, or unknown
  ↕
requirements ↔ shapes ↔ fit checks
      ↕         ↕
  focused spikes / sketches / candidate breadboards
  ↕
accept requirements + Appetite when decision-ready
  → human selection
  → reconcile selected direction into selected-design behavior
  ↔ return to shaping if concrete behavior exposes a consequential conflict
  → optionally model complex state
  → select a demoable slice
  → give the build agent bounded context
  → check drift while building

When future-facing opportunity evidence is the active uncertainty, an optional Lead User study may precede this loop. It hands accepted evidence implications to framing; it does not force research in front of already-concrete product work.

Gated / orchestrated route

accepted frame
  → accepted requirements
  → accepted Appetite
  → candidate shapes
  ↔ candidate breadboards or focused spikes when needed
  → decision-ready fit checks
  → human selection
  → selected-design breadboard
  → selected slice
  → bounded context
  → build

Shaping and breadboarding are distinct but composable. Shaping owns working and accepted requirements, Appetite, comparison, focused spikes, and human selection. Breadboarding maps behavior in one of three modes:

• current-state — descriptive evidence about what exists
• candidate-shape — exploratory evidence about one unselected shape during shaping
• selected-design — accepted normative intent after selection and reconciliation

A candidate breadboard cannot select itself, produce build scope, or automatically become selected-design intent.

When the bounded planning route itself is too large for one session, use Wayfinding as an outer loop around these moves. It keeps a shared frontier of decision, evidence, prototype, and prerequisite tickets while every accepted result still lands in the ordinary canonical artifact.

When the opportunity itself is not yet grounded, the optional upstream move is lead-user-research. It produces an evidence-traceable research decision and a proposed handoff; a human must accept the implications before they feed framing.

The three core moves are:

Start there. Add the advanced moves only when the work needs them.

Advanced workflow

See the sketch reconciliation guide for the visual-to-plan procedure and command examples.

First useful prompt

Use this repository's planning workflow in collaborative mode.

Start from whatever is already concrete in my material: requirements, a proposed solution, a prototype, current-system evidence, or a specific unknown.
During shaping, move among R, S, fit checks, focused spikes, sketches, and candidate-shape breadboards whenever that is the smallest useful move.
Keep working material separate from accepted intent.
Do not force me through a fixed exploration sequence.
Do not select a shape until requirements and Appetite are accepted and the comparison is decision-ready.
Do not treat candidate evidence as selected intent or build scope.
Do not implement until selected-design behavior or an equally clear accepted boundary and a demoable slice are explicitly selected.

Source material:
[paste notes, transcript, request, solution idea, screenshots, or links here]

For deterministic automation, replace “collaborative mode” with “gated/orchestrated mode” and enforce .agent-orchestration.yaml prerequisites.

The tool-neutral operating rules live in AGENTS.md. The machine-readable profiles, modes, promotion gates, allowed outputs, forbidden moves, artifacts, and hooks live in .agent-orchestration.yaml.

Why this exists

AI coding tools can one-shot simple applications. Larger bets fail differently: the agent fills missing product decisions, requirements collapse into mechanisms, rejected ideas return as scope, exploratory evidence gets mistaken for accepted intent, or implementation silently drifts from the selected direction.

This repository makes the planning stack explicit enough for humans and agents to share:

• what problem is being solved
• which dependent planning questions remain open across sessions
• which requirements are working versus accepted
• which shape was selected and which were rejected
• which breadboards are descriptive, exploratory, or selected intent
• how the accepted behavior and state fit together
• what the current slice includes and excludes
• what the implementation agent must preserve
• what proves the slice is complete
• when reality requires the plan to change

The operating philosophy is in The Work Should Get Clearer.

Planning Skills, Spec Kit, and implementation harnesses

These tools address different layers:

Planning Skills is the upstream planning and alignment layer, not a replacement for either downstream category.

imageHuman–Agent Software Factory

Use across agent tools

The method is tool-agnostic. Invocation differs by environment:

See the invocation matrix for exact mappings.

For a complete workflow that combines Claude Code and Claude Design, see Using Claude Design with the Planning Skills Repository.

Claude Code

Clone the repository, build the complete plugin layout, and use the generated bundle:

git clone https://github.com/mattlane66/planning-skills-for-agents-and-humans.git ~/.local/share/planning-skills-for-agents-and-humans
cd ~/.local/share/planning-skills-for-agents-and-humans
bash scripts/build-claude-plugin.sh
claude --plugin-dir dist/claude-code-plugin

Plugin entries are namespaced, for example /planning-skills:frame, /planning-skills:shape, and /planning-skills:spike.

See Claude Code plugin guidance and slash commands.

Codex

For Codex CLI, add this repository as a marketplace and install the plugin:

codex plugin marketplace add mattlane66/planning-skills-for-agents-and-humans --ref main
codex plugin add planning-skills-for-agents-and-humans@planning-skills-marketplace

Start a new task in the product repository, then invoke skills by name in natural language. In managed workspaces, an eligible admin can instead import the repository from Workspace settings → Plugins → Add → Import marketplace and users can select the installed plugin from Sources → Use plugins in supported Codex task views.

See Codex plugin installation and Codex prompt recipes.

Gemini CLI

For real product work, prefer Gemini CLI's native Agent Skills manager:

gemini skills install https://github.com/mattlane66/planning-skills-for-agents-and-humans

Then open the product repository and invoke the installed skills by name. The .gemini/commands/ files in this repository are repo-local convenience wrappers; native skill installation does not copy them into another project. Use those slash commands only when they are actually present, or intentionally copy/adapt them and verify their @{...} includes. Keep the product repository's own instructions authoritative.

See Gemini CLI usage and the Gemini/MCP integration guide.

MCP server

cd mcp-server
npm ci
npm run check
npm start

See the MCP server README for client configuration and exposed tools.

Live Mermaid viewer

Watch the diagrams in one or more planning artifacts and refresh them in a local browser after every save:

bash scripts/watch-planning-diagrams.sh examples/simple-grocery-list/03-breadboard.md

The viewer uses a pinned local Mermaid package, binds to localhost, and uploads nothing. See visual hot reload.

Examples

• simple-grocery-list is a deliberately small walkthrough of the foundational workflow.
• existing-codebase-drift demonstrates how to surface differences between an intended breadboard and implementation reality.
• statechart-retry-workflow shows how to derive a traceable statechart when retries, cancellation, and timeouts make breadboard wiring harder to review.
• sketch-reconciliation shows how a dropped visual becomes mapped observations and accepted planning deltas without silently overriding the selected shape.
• solution-first-shaping shows S-first collaborative shaping: rough Shape A → provisional R → working fit → spike / candidate evidence → accepted judging inputs → human selection.

These are teaching examples, not evidence of comparative model performance.

Repository integrity

The root skill folders are canonical. skill-inventory.txt defines the complete set, and the skills/ directory is generated packaging for plugin consumers.

After changing a canonical skill:

bash scripts/sync-packaged-skills.sh
bash scripts/check-repo-health.sh

The health check verifies packaged-skill parity, manifest and artifact references, version parity, command wrappers, generated plugin output, the visual hot-reload viewer, and the MCP build and tests. See CI health.

The fixtures under evals/ include structural contracts and deterministic behavior-runner checks; real model runs remain runtime-specific evaluations rather than universal benchmarks.

See Contributing for the development and review workflow. Report vulnerabilities through the private process in the Security Policy, not through a public issue.

License

Released under the MIT License.

Optional lightweight demo

For a quick conversational feel before installing the repository, try the Shape to Slice Assistant.