Skip to content

mattlane66/planning-skills-for-agents-and-humans

v1.7.1MIT

Planning workflows with evidence-gated research, fluid collaborative shaping, explicit promotion gates, breadboarding, bounded implementation handoffs, and reflection.

Changelog

Unreleased

v1.7.1 — CodeQL generated-bundle false-positive remediation — 2026-10-21

Security assurance

  • Investigate CodeQL PR #175 alerts #105–107. All three point to UUID hexadecimal string concatenation in the checked-in, third-party-bundled standalone portal; the flagged additions do not perform arithmetic on random numbers.
  • Restrict CodeQL's input-scope exception to generated site/index.html and keep authored site/src plus Python and JavaScript/TypeScript sources under analysis. Keep browser smoke, generated-portal consistency, dependency audit and release-install checks active.
  • Add a CI regression test that rejects a wider code-scanning exclusion and document the audit finding.
  • Synchronize portable, Claude, Codex and MCP release versions for v1.7.1.

v1.7.0 — Guided whiteboard capture — 2026-10-21

Added

  • Add an optional rough screenshot plus spoken/transcribed/typed guided-tour entry path for shaping and candidate breadboarding, with a clear routing recipe, ID-stable canonical tables, a deliberately spatial visual, and matching structured prose.
  • Explain a continuous CAD-style change loop using the existing sketch and planning-change reconciliation skills: private model-first proposals, semantic/visual review diffs, and explicit human acceptance gates.
  • Add a complete fictional whiteboard → guided tour → candidate breadboard → narrated review example and regression tests for provenance, authority, ID stability, mirroring, and discovery.

Compatibility

  • No new canonical skill or alternate source of truth. Audio is optional. Preserve all existing human selection, Appetite, promotion, and implementation gates.
  • Coordinate portable, Claude, Codex, MCP package, and lockfile metadata for v1.7.0.

v1.6.0 — Post-kickoff planning change reconciliation — 2026-10-14

  • Add a post-kickoff planning-change skill with provenance, deduplication, human gates, and downstream ripple review.
  • Add a read-only semantic-inventory/Markdown diff mode to Planning Publisher, with source-hash guards and tests.
  • Expose the skill through agent routing, MCP metadata, commands, templates, and a small example.

v1.5.4 — Product ontology viewer — 2026-10-09

Added

  • Add an optional self-contained, read-only product ontology view generated from the existing accepted PlanningPackage with --ontology-output; no additional product authority, code execution, or source of truth.
  • Show accepted and working requirements, explicit selected-design rationale, declared verification targets, and missing coverage without falsely claiming the product passed checks.
  • Publish a grocery-list example derived from the canonical accepted planning example through GitHub Pages, with a discoverable README entry.
  • Extend the real-browser smoke tests to exercise the compiled six-requirement example, decision reasoning, filtering, keyboard interaction, and mobile layout.

Scope

  • This is an optional product-intent viewer, not live GitHub drift monitoring, a separate product engine, or an alerting service. The existing protected-baseline product-intent gate remains responsible for behavioral assessments.
  • Keep portable, Claude, Codex, and MCP package versions synchronized for the 1.5.4 release.

v1.5.3 — Reviewer walkthrough metadata — 2026-10-07

Fixed

  • Add the reviewer-accessible walkthrough URL required for OpenAI public MCP plugin review.
  • Keep the portable, Claude, Codex, MCP package, and MCP lockfile versions synchronized for the 1.5.3 release.

v1.5.2 — Public plugin listing readiness — 2026-10-06

Fixed

  • Move OpenAI public-listing metadata into the portable root manifest, with a 30-character-safe name and subtitle, three bounded conversation starters, and a primary app icon.
  • Publish project-owned Privacy Policy and Terms of Service pages through the Planning Skills GitHub Pages site, and use the repository Issues page for support.
  • Add the required initial MCP review test cases and declare that the plugin does not support commerce.

v1.5.1 — Explicit execution-appetite authority — 2026-09-29

Fixed

  • Require explicit human acceptance of every run-level execution appetite before implementation can begin; agents may propose the appetite but cannot approve or silently enlarge their own bet.
  • Make that acceptance machine-verifiable in the orchestration/integrity contracts and context packet, with regression coverage for the build gate.
  • Document how the portable execution-appetite method compiles into runtime-specific controls, using current Claude Messages API, Agent SDK, and Managed Agents mechanisms only as non-canonical examples.

v1.5.0 — Inference appetite and bounded agent execution — 2026-09-29

Fixed

  • Complete the execution-appetite orchestration contract by defining its hard-gate semantics, updating contract tests, and bundling the referenced guide in the Claude plugin.

  • Refresh transitive npm locks for newly disclosed undici, fast-uri, and ip-address advisories, including moving the existing fast-uri override to patched 3.1.8, before publishing v1.5.0.

  • Preserve product-repository AGENTS.md references in the Claude plugin, rewrite nested support paths, and check all bundled Markdown links.

  • Surface default hook reminders as runtime-visible JSON and recognize absolute planning/documentation paths without false build reminders.

  • Make Lead User validation read-only, support completed empty evidence passes and explicit brief-field provenance, and require canonical Phase H delivery in all modes.

  • Bind Evidence Freeze to content, reject overlapping independent lineages and selected concepts with failed requirement fit, and redact escaped withheld URLs.

  • Run assurance validation from integrity-checked host code; supply explicit trusted synthetic human decisions and retain failed artifacts with bounded subprocesses.

  • Correct MCP routing at exclusion, realized-fit, and negated-scope boundaries; serve bounded, skill-local support resources through MCP.

  • Reconcile artifact authority against the orchestration manifest, bring examples and stable IDs up to the skill contracts, and complete the Gemini/Claude command surfaces.

  • Reject untrusted Host headers on the loopback viewer, align the site's Node floor with its dependencies, test that floor in CI, and separate major dependency updates.

Added

  • Add a future-proof Agent Execution Appetite model that keeps human attention and useful-by time primary while treating tokens, spend, turns, and compute as replaceable runtime guardrails.

  • Extend context packets and orchestration with run-level Worth / Needed by / Protect / Cut first / Stop when boundaries so agents work to outcomes rather than exhaustion.

  • Extend canonical agent run logs with actual human cost, runtime evidence, figuring-it-out versus executing-down effort, shaping signals, and explicit continue/reshape/new-bet decisions.

  • Add stable criterion lineage from evidence-backed R candidates through Working/Accepted authority, selected mechanisms, implementation context, and realized-fit assessment.

  • Add inverse requirement coverage and selected-design requirement realization maps so every Accepted R can be traced to the concrete behavior that claims to embody it.

  • Separate implementation verification from realized fit, with outcome-evidence-only realized-fit statuses and regression cases for supported, unassessed, and contradicted criteria.

  • Add an explicit x / y / f() routing diagnostic so current-situation, desired-outcome, and solution uncertainty lead to different next moves.

  • Add semantic public-web need–solution mining as a complementary discovery lane while keeping popularity/interest metrics as discovery signals only.

  • Add independent discovery-branch coverage checks for pivotal needs and an optional enabler/discontinuity scan for high-altitude opportunity work.

  • Add explicit need transferability assessment as the sixth Concept Generation Gate check.

  • Add layer-preserving rejection records so technical/economic/safety objections to a mechanism or implementation part do not silently invalidate the need, principle, or requirement.

  • Make the discovery-signal/decision-evidence boundary explicit across the Lead User protocol, prompts, state contract, portable workflow, and validator.

v1.4.0 — Lead User research and assurance — 2026-08-31

Added

  • Added deterministic Lead User next-phase routing, a /lead-user start/resume controller, and focused Phase A–H wrappers for Claude Code and Gemini CLI.
  • Added an explicit research-to-frame handoff template and human acceptance gate.
  • Added a complete synthetic Lead User v1.7 reference study with qualified, derivative, contradictory, concept-shaping, operational-action, and privacy-safe drill-down state.
  • Added a blind real-runtime assurance harness that scores generated study artifacts independently of adapter self-report, plus a manual GitHub Actions workflow.

Improved

  • Integrated Lead User Research into the planning router, orchestration contract, cross-platform invocation guidance, and optional upstream planning flow without making research a mandatory predecessor to framing.
  • Made source content explicitly UNTRUSTED_DATA, persisted instruction-risk handling, and added a malicious-source regression fixture.
  • Strengthened structural validation for source, evidence, trends, lineage, findings, concept gates, sufficiency dimensions, decision status, completion, and cross-format privacy/state markers, including a deterministic brief-to-state fingerprint.
  • Replaced narrative action strings with evidence-oriented A## execution contracts and made the Decision Brief action-first, evidence-linked, and privacy-safe by default.
  • Made Lead User assurance cover every authoritative registry, explicit synthetic-fixture isolation, falsification/observability ledgers, pyramiding, lineage conflicts, transitive concept/ACT evidence, shaping-frame output, and human selection provenance.

Fixed

  • Ignored repository-local Python virtual environments during Markdown link checks and version-control discovery so third-party package documentation cannot create false failures.
  • Made Node health stages stop immediately on install, build, test, or audit failure so a later successful command cannot mask an earlier verification failure.
  • Prevented empty negative interpretations and completed insufficiency repairs from looping forever by persisting explicit interpretation and repair transitions.
  • Refused non-empty initializer targets, required adversarial and discovery registries, required evidence bases, and rejected unsafe outward URLs and Markdown injection.
  • Made private-identity detection token-aware, prevented derivative lineage from also counting as independent, and enforced evidence-backed trend/LU paths at decision gates.
  • Rewrote every Lead User support path in the generated Claude plugin to a resolvable bundle-local path and added bundle regression checks.
  • Rendered accepted shaping frames, real candidate/selected mechanism states, human selection provenance, rotated parts, and prominent synthetic-fixture warnings.

v1.3.1 — Routing safety and reproducible releases — 2026-08-11

Fixed

  • Made MCP workflow recommendations honor explicit skill exclusions, negated prerequisite states, and clearly labeled untrusted quoted material.
  • Required an accepted breadboard before recommending Statechart and added regression coverage for routing, prompt-injection, and source-trust boundaries.
  • Derived the MCP server version from its package manifest so runtime metadata cannot drift from coordinated plugin versions.
  • Defined active_scope as the canonical machine-readable alias for either one selected slice or one selected Dumplink task group.

Added

  • Added deterministic release tooling for all Claude upload ZIPs, the Claude Code plugin bundle, and a SHA256SUMS manifest.
  • Added success-gated automatic version tagging after Repo health passes on main; existing tags are never moved or recreated.
  • Added CodeQL analysis, weekly Dependabot updates, Python dependency auditing, and an opt-in blind real-runtime behavior-evaluation workflow.
  • Added contribution, security, conduct, issue, and pull-request guidance plus Dumplink source attribution.

Security

  • Separated trusted routing instructions from untrusted transcripts, issue bodies, web content, pasted files, quoted text, and tool output across canonical and packaged skill surfaces.
  • Pinned every GitHub Action to a full commit SHA, applied least-privilege workflow permissions, disabled persisted checkout credentials, and added bounded workflow timeouts and concurrency.
  • Documented that non-loopback visualizer hosting has no authentication and is appropriate only on trusted networks.

Changed

  • Hardened tag releases to require exact stable SemVer, coordinated versions, an exact changelog section, ancestry on main, a passing full health suite, and prebuilt checksummed assets before publication.
  • Isolated npm verification in a task-scoped cache so health checks do not depend on a writable user-level npm cache.
  • Updated the MCP SDK and tsx within their existing major-version compatibility boundaries.

v1.3.0 — Fluid shaping, Wayfinding, and verifiable breadboards — 2026-08-11

Improved

  • Made collaborative shaping fluid by default: teams can start R-first, S-first, evidence-first, or uncertainty-first and move among requirements, shapes, fit checks, focused spikes, sketches, and candidate breadboards while material remains Working.
  • Reframed human gates as promotion/commitment gates rather than navigation locks; Accepted requirements and Appetite still constrain selection, candidate evidence still requires reconciliation, and selected behavior/scope still gate implementation.
  • Added explicit collaborative and gated orchestration profiles so interactive human shaping can stay flexible while automation and policy-controlled workflows retain deterministic prerequisites.
  • Allowed collaborative candidate-shape breadboarding to use Working requirements or Unset/Working Appetite while keeping final fit/Appetite claims provisional and build scope forbidden.
  • Updated Claude Code, Codex, Gemini CLI, Claude Design, MCP integration guidance, runtime adapters, README/start-here/workflow docs, quality rubric, eval corpora, and health checks to describe the same profile behavior.
  • Declared the MIT license in every canonical skill and split breadboarding's detailed notation and slicing material into an on-demand reference.
  • Separated portable Agent Skills metadata from Claude Code, Codex, Gemini CLI, Claude Design, and MCP adapter behavior.
  • Made Claude human-gate aliases manual-only, hid alias-backed generated skills from duplicate slash-menu discovery, and added operational metadata to direct-only Claude skills.
  • Added native Gemini skill installation guidance, Codex skill-only boundary checks, Claude Design example packaging, and shared activation fixtures across all skills.
  • Replaced ad hoc frontmatter parsing with YAML validation and added runtime adapter regression tests.
  • Added CI validation for every generated Claude upload package, including ZIP roots, metadata, cross-skill references, and required local resources.
  • Clarified when Claude Design should invoke a skill directly and when repository-aware work must return to Claude Code.
  • Made custom package-output cleanup non-recursive and fail closed around protected paths, unrelated content, directories, and symlinks.
  • Expanded repository health checks to run packager tests and dependency audits.
  • Unified root, Claude upload, and MCP skill descriptions behind skill-metadata.json, with parity and boundary regression checks.

Added

  • Added /spike focused shaping wrappers for Claude Code and Gemini CLI; spikes can originate from R, S, fit, sketches, candidate breadboards, or implementation reality and return explicit R/S/fit/Appetite implications without deciding the product direction.
  • Added Gemini /shape and /breadboard wrappers for parity with the collaborative Claude shaping surface.
  • Added a solution-first shaping walkthrough showing rough Shape A → Working R → Working fit → spike/candidate breadboard → Accepted judging inputs → explicit human selection → selected-design reconciliation.
  • Added workflow and activation eval cases for S-first shaping, Working fit checks, provisional candidate breadboarding, focused spikes, gated-profile prerequisites, and hard selection gates.
  • Added the wayfinding skill and /wayfind wrappers for coordinating dependent planning decisions across sessions without creating a second source of product truth.
  • Added portable local-Markdown and optional issue-tracker adapters, Wayfinding map and ticket templates, MCP routing, and cross-runtime activation coverage.
  • Added a Claude and Claude Design workflow that separates canonical skills from Claude Code command wrappers.
  • Added uploadable Claude skill ZIP generation with optimized trigger metadata and bundled supporting resources.
  • Added positive, automatic-selection, near-neighbor, negative-trigger, command-wrapper, and cross-surface fallback tests for Claude skill invocation.
  • Added packager safety tests and regression coverage for hidden support files and malformed visualizer paths.

Fixed

  • Removed the implicit requirement that ordinary interactive shaping must proceed through criteria → Appetite → shapes before useful solution exploration can occur, while preserving the same strict selection and build gates.
  • Preserved dot-prefixed support-file references in generated Claude skill packages and made piped CI failures propagate correctly.
  • Reconciled frame, appetite, shape-selection, kickoff-authority, context-feeding, and breadboard-reflection rules across canonical artifacts and adapters.
  • Removed task grouping and slicing from shaping, separated descriptive and normative breadboarding, and made Dumplink ingest one selected project, create its vertical task-group slices, then stop for human plan approval and active-group selection.
  • Upgraded repository-health Actions to their Node 24-based major versions and added manual workflow dispatch for explicit CI verification.
  • Removed moderate-or-higher MCP dependency vulnerabilities and made the visualizer return a bounded 400 response for malformed encoded paths.

v1.2.0 - Planning gates, visual reconciliation, and live planning views

Added

  • Added the sketch-reconciliation skill and /reconcile-sketch wrappers for Claude Code and Gemini CLI.
  • Added a durable sketch-reconciliation template with observation, mapping, delta, decision, fit-impact, and ripple sections.
  • Added a local Mermaid viewer that watches one or more planning Markdown files and hot-reloads every diagram in the browser.
  • Added exact MCP routing for R x A, A x R, spike, shape-update, sketch-reconciliation, slicing, slice-planning, and execution-verification shorthand.
  • Added an explicit appetite gate plus /appetite wrappers for Claude Code and Gemini CLI.

Improved

  • Extended the tool-neutral orchestration contract with an explicit visual-reconciliation gate.
  • Added regression coverage for the conversational prompts used in an end-to-end shaping session.
  • Extended repository health checks to validate the new skill, command surfaces, visualizer package, and viewer documentation.
  • Made the generated Claude bundle self-contained for skill, agent-instruction, template, documentation, orchestration, and hook references.
  • Synchronized context-packet requirements and cross-platform installation guidance for product-repository use.

v1.1.0 — Release integrity

Fixed

  • Added the MIT license text referenced by the plugin manifests.
  • Established root skill folders as the canonical source and synchronized all packaged skills/ copies.
  • Added byte-for-byte packaged-skill parity checks.
  • Fixed broken artifact references in .agent-orchestration.yaml.
  • Aligned drift-check authority order with Dumplink task-group precedence.
  • Unified Claude, Codex, and MCP package versions.

Improved

  • Added the optional Statechart skill across packaged skills, templates, commands, MCP routing, documentation, examples, and health checks.
  • Reworked the README around a 10-minute entry path and the Frame → Shape → Breadboard core workflow.
  • Updated Claude, Codex, Gemini, MCP, and invocation documentation to cover the complete skill set.
  • Made the generated Claude bundle self-contained, removed duplicate command/skill names, and updated command permissions to current Claude tool names.
  • Made MCP artifact tools read canonical template files instead of hard-coded duplicates.
  • Made MCP skill and template exposure track the canonical inventory and orchestration manifest.
  • Replaced the MCP workflow recommender's default Dumplink step with prerequisite-aware routing.
  • Added reproducible MCP installs, compilation tests, recommendation tests, and package locking.
  • Made lifecycle hooks executable and non-blocking by default, with explicit strict mode for blocking behavior.
  • Strengthened repository health checks for manifests, references, generated bundles, docs, and MCP verification.
  • Clarified that evals/ contains structural contract fixtures, not behavioral model benchmarks.

v0.1.0 — Initial public release

Initial reusable release of Planning Skills for Agents and Humans.

Included

  • Framing, shaping, breadboarding, kickoff, context-feeding, and reflection skills.
  • Root canonical skill folders and packaged plugin copies.
  • Tool-neutral AGENTS.md instructions and Claude, Codex, Gemini, and MCP adapters.
  • A small grocery-list walkthrough and canvas-export guidance.