// Create or update a structured JSON gameplan for a codebase change, including patch sequencing, dependency graph, acceptance criteria, and formal per-patch and final-state specs. Use when the user asks for a gameplan, implementation plan, milestone plan, or structured change plan.
| name | write-gameplan |
| description | Create or update a structured JSON gameplan for a codebase change, including patch sequencing, dependency graph, acceptance criteria, and formal per-patch and final-state specs. Use when the user asks for a gameplan, implementation plan, milestone plan, or structured change plan. |
Create a structured, machine-readable gameplan for a complex codebase change. The gameplan is a JSON object with typed sections, and each patch includes a formal specification articulating the invariants that must hold after that patch is applied. A final-state spec describes what must be true when the entire gameplan is complete.
Core principle: It should be 5-10x easier to review a gameplan than the code it produces.
A gameplan is, by definition, a bundle of work with two non-negotiable properties:
dependencyGraph. No human is in the loop between patches.The following structures are therefore prohibited inside a single gameplan:
If you find yourself drafting any of those — stop and use [[write-workstream]] instead. The work you are describing is a multi-milestone workstream, not a gameplan. Each side of the pause/decision/observation becomes its own milestone with:
It is expected and healthy that real projects contain soaking, observation, flag flips, and judgement calls. The error is not that those things exist; the error is trying to encode them inside a gameplan. They live at milestone boundaries.
Practical test, applied while drafting: read your patch sequence and ask, "could a fully autonomous orchestrator execute every one of these back-to-back, with no human pause and no run-time choice, and would the outcome still be correct?" If the answer is no — for any reason — you are looking at a workstream, not a gameplan. Stop drafting and switch to /write-workstream.
Every gameplan pertains to exactly one repository on a git forge (GitHub, GitLab, Gitea, etc.), declared by the required top-level owner and repo fields. The orchestrator (e.g. onton) clones that repo and runs every patch's agent inside isolated worktrees off of it — so paths in patches[].files[].path and requiredChanges[].file are resolved relative to the repo root and may not escape it (e.g. ../other-repo/x.ts is disallowed; the worktree has no notion of "next to my checkout").
owner and repo are forge-agnostic at this layer — the schema only checks that they are non-empty strings. The forge backend the orchestrator is configured for will enforce any format rules it requires (for example, GitHub rejects handles longer than 39 characters); that validation happens at session start, not at gameplan-authoring time.
If the change spans multiple repositories, write multiple gameplans — one per repo — each with a distinct projectName (e.g. auth-shared and auth-app) and the appropriate owner/repo. If the gameplans coordinate (one must merge before another can be implemented), express that coupling at the workstream level: name each gameplan as a separate milestone in the workstream and use priorMilestones / unlocks to capture the ordering. Never bundle cross-repo work into a single gameplan and never use repo-relative ../sibling-repo/... paths.
The user may provide a path to a specification file (typically a .pant file or any text file) containing behavioural invariants that apply to the overall gameplan. These are pre-written formal or informal constraints the implementation must satisfy.
If a spec file is provided:
spec field by restating any referenced domains, predicates, or rules inside that patch's spec module, then encoding the invariant as a precondition or postcondition the patch must preserve. Per-patch specs are verified standalone — do not merely cite or import external invariants; all referenced declarations must be self-contained within the patch's specfinalStateSpecIf no spec file is provided, generate specs from first principles as usual.
A gameplan can be standalone or part of a workstream (a larger project spanning multiple gameplans as milestones).
If the user provides a workstream reference (URL, file path, or name):
Established Precedents section (plus any milestone-scoped precedents). For each precedent, identify the specific patches in this gameplan that consume it — touch its API, implement its algorithm, depend on its invariants — and attach it to those patches' precedents arrays. Do not blanket-copy workstream precedents onto every patch; only the ones that actually use the technique. See Leveraging Established Precedents for the per-patch shape.If no workstream is provided, treat this as a standalone gameplan.
MANDATORY FIRST STEP: Before writing any JSON, read references/gameplan-schema.json (relative to this skill's directory). It is a formal JSON Schema (draft 2020-12) defining every required field, its type, constraints, and structure. Do NOT generate JSON from memory — the schema is the sole source of truth for the output shape.
The gameplan is a JSON object written to gameplans/<project-name>.json. Every section is a named attribute.
All of these fields are required and must be present in every gameplan:
| Field | Type | Description |
|---|---|---|
projectName | string | Kebab-case, used in branch names and PR titles |
owner | string | Repository owner on the git forge (user, org, group). Non-empty; forge-specific format rules are enforced by the orchestrator at session start. See One Repo Per Gameplan |
repo | string | Repository name on the git forge (paired with owner). All file paths in this gameplan are interpreted relative to this repo's root |
specFile | string | null | Path to the specification file the user provided, if any |
workstream | object | null | { name, milestone, priorMilestones, unlocks } — null if standalone |
problemStatement | string | 2-4 sentences: what problem, why it matters |
solutionSummary | string | 3-5 sentences: high-level approach |
currentStateAnalysis | string | Where the codebase is now vs. where it needs to be |
operationalConsiderations | object | { externalSystemAccess, crossRuntimeContracts, failureBehavior, concurrencyAndIdempotency, rollbackStrategy } — see Operational Considerations |
mergabilityStrategy | object | { featureFlagStrategy, featureFlags, patchOrderingStrategy } |
requiredChanges | array | [{ file, line, description, signature }] |
functionalChanges | array | [{ id, description, ownedBy }] — exhaustive, every entry assigned to exactly one patch. See Functional Change Ownership. |
contextResources | array | [{ id, kind, paths, why, consumedBy }] — authoritative context specific patches must read before editing. See Context Resources. |
acceptanceCriteria | string[] | Each is a "done" condition |
openQuestions | string[] | Decisions for the team (empty array if none) |
explicitOpinions | array | [{ opinion, rationale }] |
patches | array | See Patch Object in schema |
testMap | array | [{ testName, file, stubPatch, implPatch }] |
dependencyGraph | array | [{ patch, classification, dependsOn }] |
mergabilityChecklist | object | boolean fields including gameplanIsAtomicAndAutonomous (see schema for full list) |
mergabilityInsight | string | E.g. "X of Y patches are INFRA/GATED…" |
finalStateSpec | string | Formal specification source for the completed gameplan |
Each patch object must have: number, classification (INFRA|GATED|BEHAVIOR), complexity (1|2|3), title, files (array of { path, action, description }), changes (string array), requiredContext (string array), testStubsIntroduced (string array or null), testStubsImplemented (string array or null), spec (string). Patches may also include an optional precedents array citing established libraries, algorithms, or patterns the patch should adopt — see Leveraging Established Precedents.
The inline spec and finalStateSpec string fields in the JSON are the sole source of truth for formal specifications. Do not maintain separate spec files alongside the gameplan. For verification, extract the strings and validate them with the spec language's toolchain (see Specification Language below). Do not persist the extracted files.
contextResources names authoritative context that an implementing patch agent must read before editing. This is for existing code, contracts, docs, tests, or predecessor surfaces that constrain implementation. It is not a dumping ground for general background.
Allowed kind values:
existing-implementation — current code path or helper whose behavior should be reused or preserved.contract — API, protocol, schema, interface, spec clause, or cross-runtime contract the patch must honor.predecessor — old surface being retired, replaced, or migrated away from.reference-doc — repo documentation or canonical maintainer docs describing the intended behavior.test-or-static-check — tests, fixtures, evals, linters, or static checks that define expected behavior.external-reference — external URL, standard, or vendor document that is authoritative for this patch.Each resource has id, kind, paths, why, and consumedBy. Each patch has requiredContext, an array of resource IDs. The routing must match in both directions: if contextResources[].consumedBy includes patch 3, then patch 3 must include that resource ID in requiredContext, and vice versa. Attach resources only to patches that actually consume them.
Require context resources for patches that:
Docs, evals, and reference patches must name the implementation or contract they describe. Adapter/replacement patches must name the predecessor and the target contract. If a context resource defines a contract that a patch preserves, the relevant per-patch spec should cite that contract in its invariants.
Each gameplan includes two levels of formal specification. The spec language is pluggable (see Specification Language), but the structural requirements are fixed:
finalStateSpec)A spec module describing the invariants that must hold when ALL patches have been applied. This is the "acceptance criteria" expressed formally. It should capture:
spec on each patch)Each patch has a spec module describing the invariants that must hold after THAT patch is applied. These are incremental — they describe the delta, not the full system. They should capture:
Spec-writing guidance: Use progressive disclosure (top-down structure). Never guess domain details — if something is unclear, note it in openQuestions.
Every functional change should map to at least one per-patch or final-state spec clause when the chosen spec language can express it. If a context resource defines a contract the patch preserves, name that contract in the spec prose/invariant so implementers and reviewers can trace the resource to the code obligation.
Each patch includes a classification field:
INFRA — No observable behavior change. Types, schemas, helpers, test stubs, feature flag additions. Safe to merge anytime.GATED — New behavior behind a feature flag. Observable behavior unchanged until flag is enabled.BEHAVIOR — Changes observable behavior. Requires careful review. Should be as small as possible.Goal: Maximize INFRA and GATED patches. Minimize BEHAVIOR patches.
A gameplan whose patches share responsibility for a behavioral change vaguely fails in a predictable way: each patch implementer reads the prose narrative, sees the change mentioned, and assumes a different patch owns it. The change falls through the cracks. The whole point of decomposing a gameplan into mergeable patches is defeated when a behavior is described as a gameplan-level concept that has no single named owner.
The functionalChanges array prevents this. It is an exhaustive enumeration of every functional or behavioural delta the gameplan introduces, with each entry assigned to exactly one owning patch.
What does not go here:
patches[].changes as implementation steps).requiredChanges).Each functionalChange has id (FC-1, FC-2, …), a single-outcome description, and an ownedBy patch id. The mapping is:
If the same behavior is co-implemented by two patches, the change description is too coarse — split it into two changes (one per patch), each describing the slice that patch delivers.
Downstream consumers (notably onton's patch prompt renderer) read functionalChanges and inject the subset ownedBy each patch into that patch's agent prompt as an explicit "Functional Changes You Own" section. The implementing agent therefore sees the precise list of user-visible behaviors it is responsible for delivering, separate from its changes implementation steps. This is what closes the loophole — there is no longer prose-only behavior that no patch acknowledges.
patches[].changes.problemStatement, solutionSummary, and acceptanceCriteria: every behavioral promise made there must correspond to at least one functionalChange entry. If you cannot point at the owning patch for a sentence in the problem statement, the gameplan has a gap.finalStateSpec: every behavioral invariant in the spec should map to a functional change that introduces it (the spec says what is true at the end; the functional change says which patch made it true).Beyond what changes, a gameplan must engage with how the system behaves operationally under the change. These concerns share a failure shape: vague descriptions get scattered across patches, every patch author assumes some other patch owns the decision, and the question surfaces in production. The operationalConsiderations schema field is required and contains five sub-fields — each is a required string. The schema enforces presence; the rubric below makes each response substantive. A sub-field may state "not applicable" with a brief justification when the gameplan genuinely does not touch that surface, but it must be present and engage with this gameplan's actual code.
externalSystemAccessWhen a gameplan newly depends on an external system (object storage, database the runtime doesn't currently reach, third-party API, queue, secret store, internal service), the runtime executing the new code must be able to reach it in production. Audit the existing access posture of that runtime (direct SDK with ambient IAM, presigned URL handed in by another service, broker proxy, VPC endpoint, etc.), pick an access mode, and assign one patch to own the wiring — IAM grant, new endpoint, presigned-URL minting path, network policy, secret rotation. Be especially suspicious of newly-invented *Client / *Transport interfaces — they are where an undecided access-mode question hides. Sentinel classes whose existence encodes a lack of access (e.g. a PresignedOnly* adapter) are signals that the runtime cannot hold the underlying credentials. The chosen capability should appear as a functionalChange owned by that patch, not just as an interface parameter.
crossRuntimeContractsAny data format crossing a runtime boundary (queue payloads, DB rows read or written by separate services, S3 object schemas, RPC return types, event payloads) is a contract. When the gameplan changes one side, identify the producer and consumer runtimes, name which side this gameplan touches, and explain how the other side stays in sync — patched in the same gameplan, or made forward/backward-compatible with an explicit migration plan. Failure mode: producer ships, consumer breaks silently, and the gap is not visible from any single patch's files array.
failureBehaviorFor each new dependency or runtime path, describe behavior under realistic failure: dependency slow/throttling/5xx/garbage, retry storms, partial writes, timeouts, oversized inputs, expired credentials. State which failures are handled deliberately (documented recovery path or error surface) and which are intentionally left to the caller or operator. Failure mode: only the happy path is tested against a fake, and production discovers the rest.
concurrencyAndIdempotencyAny new code path entered concurrently or under retry (queue workers, scheduled jobs, race-able write paths, parallel access to the same DB row or S3 key) has a concurrency contract: locking, idempotency keys, ordering guarantees, deduplication. State it explicitly. Failure mode: a quiet double-write or deadlock that only manifests under production load.
rollbackStrategyFor stateful changes (DB schema, data writes, materialized artifacts, mutations to external systems), describe the rollback story: if a patch must be reverted after data is written, what's the recovery path? Expand/contract migrations, backfill plans, opt-in flags that wind down gracefully, compensating writes. Failure mode: assuming forward-only and stranding data in a half-migrated state.
Each patch includes a complexity field — an integer in 1/2/3 estimating how hard the patch is to implement correctly. This is used by orchestrators (e.g. onton's --model auto) to route harder patches to stronger models.
1 — Mechanical / shallow / well-precedented. A rename, a single-call-site signature change, adding a field that already has an obvious default, copy-pasting a pattern that already exists nearby. Could be done by reading only the patch description and a few surrounding lines.2 — Moderate. Requires reading the surrounding code to understand context, designing a small abstraction, writing non-trivial tests, or coordinating two or three files. The shape of the solution is clear once you've read the relevant code, but a careless implementation would miss something.3 — Deep. Requires reasoning about subtle invariants, concurrency, distributed state, novel algorithms, performance trade-offs, security boundaries, or unfamiliar third-party APIs whose contracts must be researched. Implementations that "look right" can still be wrong.When in doubt, choose the higher value. Under-estimating complexity costs more than over-estimating it: a too-weak model on a complex patch silently produces broken code, while a too-strong model on a simple patch only costs extra tokens. The bias is intentional.
Do not assign complexity from the patch title alone. Before scoring:
files and any code the patch touches transitively. If the patch modifies a function with many callers, scan the callers.WebFetch against the library's reference) so you know whether the integration is mechanical or has gotchas.If after reading you cannot tell whether something is 2 or 3, it is 3. If you cannot tell whether something is 1 or 2, it is 2.
Most non-trivial engineering problems have well-known solutions: a CS algorithm with a name, a library that already solves the hard part, a design pattern with documented trade-offs, an RFC that pins down the wire format. When a patch is solving a problem that has established prior art, identify the precedent and attach it to that patch via the optional precedents field. Prefer proven, robust techniques over rolling our own — and give the implementing agent enough of a reference that it can fetch more detail when it needs to.
A patch likely has a precedent worth citing whenever it touches an area with mature, named solutions. Common examples (not exhaustive):
A patch may have zero precedents. Bespoke project glue (wiring two existing modules together, renaming a field, adding a config flag) usually does not warrant any citation. Do not manufacture references where none apply.
Each precedent entry has four fields:
kind — one of library, algorithm, pattern, paper, rfc-spec, documentation, blog-post. Pick the most specific kind that fits.name — the most precise identifier a reader will recognise. "Tarjan 1972 strongly connected components" is better than "a graph algorithm"; "RFC 7519 JSON Web Tokens" is better than "JWT spec".url — the canonical link (library homepage or repo, paper DOI or arXiv, RFC URL, official docs page). Required for kinds where a URL is the durable reference (paper, rfc-spec, documentation, blog-post); strongly preferred for libraries. Do not guess URLs — fetch the real one (e.g. WebFetch) or leave it null.whyApplicable — 1-2 sentences explaining what part of this specific patch the precedent informs and the concrete shape it imposes. Not generic praise: name the API call, the algorithm step, or the invariant that the precedent supplies. The implementing agent reads this to decide whether to fetch the reference, so be specific.algorithm) with the recommended library named in whyApplicable. Conversely, if the value is the specific library's API design, the precedent is the library.Attach precedents at the patch level, on the specific patches the precedent informs — typically the patch that introduces a new dependency or implements the named technique, plus any consumers that need to call its API. A precedent that drives the whole gameplan should still be replicated on each patch that depends on it, so an implementing agent picking up Patch N alone has the reference in hand.
When a gameplan introduces new behavior, there are three possible gating strategies — and which one is right is a decision for the programmer, not an assumption for you to make:
Do not default to "create a new flag." Creating a new flag is one option among three, not the presumed answer. Reflexively minting a new flag for every gameplan litters the codebase with dead toggles, fragments rollouts that should share a flag, and gates changes that never needed gating.
Before deciding, investigate and clarify:
openQuestions (e.g. "Gate behind a new flag, reuse existing flag X, or ship ungated?") so it is resolved with the programmer during Resolving Open Questions, presenting the three options with the tradeoffs you found. Only treat the decision as settled when the user has stated it or the codebase makes it unambiguous.Once the strategy is decided, implement the mechanics:
Runtime flag service (percentage rollout / allowlist):
Configuration flag (global on/off, simple cases only):
Record the chosen strategy in the featureFlagStrategy field — naming whether the flag is new or reused, or stating plainly why no flag is needed — and populate featureFlags accordingly (an empty array when ungated).
Order patches to ship non-functional changes early:
INFRA): Types, schemas, helpers, test stubs, migrationsGATED): Business logic behind flags, new gated endpointsBEHAVIOR): Wire up UI/API, enable flags, remove old codeCo-location: Any patch that modifies a database schema must also include generating/writing the corresponding migration in that same patch. Never defer migration generation to a later patch — each patch must leave the DB schema and migration files in sync so it is independently mergeable.
Sequential execution: Patches that include database migrations MUST be ordered sequentially in the dependency graph — they cannot be parallelized. Migration files typically have sequential numbering, and parallel branches that each generate migrations will produce numbering conflicts that cause merge failures. This negates the benefit of parallelization.
Practical guidance: If a gameplan requires multiple schema changes, either:
Reserve parallelization for patches that don't touch database schemas/migrations.
Different projects may use different migration tools and workflows. When planning patches that involve schema changes, research how migrations work in the relevant part of the codebase and include explicit migration instructions (commands to run, files to create/generate) in those patches. The implementing agent will follow the gameplan as-written — do not assume it will discover the migration workflow on its own.
Write test stubs with skip/pending markers BEFORE implementation:
Stub patches (INFRA):
.skip in JS test runners, @pytest.mark.skip in Python, [@tags "pending"] in OCaml ppx_inline_test, #[ignore] in Rust)PENDING: Patch N)Implementation patches (GATED or BEHAVIOR):
Run the validator before finalising:
python3 scripts/validate.py <path/to/gameplan.json>
It exits 0 on PASS and 1 with explicit error lines on FAIL. Fix every reported error; do not ship a gameplan that has validator failures or WARNs.
Soft dependencies — install both so nothing is skipped:
jsonschema (pip) — enables JSON Schema shape validation. Without it, only semantic checks run.pant 0.22+ — enables Pantagruel spec parsing. Install: brew tap subsetpark/pantagruel https://github.com/subsetpark/pantagruel && brew install pantagruel.The validator covers everything mechanisable: schema shape, spec parsing, context-routing reciprocity, functional-change ID and ownership integrity, dependency-graph DAG correctness and classification consistency, testMap consistency, and repo-relative path safety. See scripts/validate.py for the exact set.
The rest is human judgement. Walk these before setting the relevant mergabilityChecklist booleans to true:
Functional-change coverage (functionalChangesOwnedByExactlyOnePatch) — the validator confirms each FC has a single resolving ownedBy. It cannot confirm the set of FCs covers every observable change. Re-read problemStatement, solutionSummary, acceptanceCriteria, and finalStateSpec; every behavioural promise there must map to an FC.
Context-resource fit — the validator confirms routing is bidirectional and references resolve. Manually confirm that docs/evals/reference patches actually name the implementation or contract they describe — a resource attached to a patch that never reads it is dead weight.
Spec/evidence completeness — for each functional change, confirm a spec or acceptance criterion expresses it, a patch implements it, the required context (if any) is attached, and a test/static check is expected to prove it.
Operational considerations are substantive (operationalConsiderationsSubstantive) — every operationalConsiderations sub-field is required by the schema, but presence ≠ engagement. Confirm each sub-field names concrete surfaces in this gameplan (specific runtimes, formats, code paths, stateful writes) rather than platitudes. "Not applicable" only with a brief gameplan-specific justification. See Operational Considerations.
Atomicity (gameplanIsAtomicAndAutonomous) — re-read Atomicity Constraint and walk the patch list. Confirm no patch is conditional on another's outcome, no changes step expects a human between patches (flag flip, manual script, dashboard check, decision branch), and no patch implies an observation/soak window. If any slipped in, re-decompose as a multi-milestone workstream via [[write-workstream]].
Remaining checklist booleans — once the items above hold, set every other mergabilityChecklist boolean honestly based on the gameplan content and the validator's PASS.
After the gameplan is written and verified, automatically proceed to this step without waiting for an additional prompt — work through the openQuestions array with the programmer one question at a time until the array is empty.
Why this step is mandatory:
openQuestions array is non-empty. Leaving questions unresolved blocks the entire plan.For each open question, in order:
changes, spec, files, signatures), acceptanceCriteria, finalStateSpec, dependencyGraph, and any other fields the decision touches.explicitOpinions — an object with non-empty opinion (the chosen resolution) and rationale (why it was chosen) keys — so the reasoning is preserved in the gameplan itself.openQuestions.After the last question is resolved, re-run scripts/validate.py since edits made during this dialogue may have introduced regressions.
The end state is a gameplan with openQuestions: [] and an explicitOpinions array that captures every decision made during the dialogue.
The handoff from [[write-workstream]] is one-directional by default: this skill reads the workstream's Established Precedents and the milestone's Definition of Done. But the gameplan brings the milestone sketch into executable detail — and per the workstream skill's "don't over-plan" principle, later milestones are deliberately left thin until they are unpacked. The knowledge that unpacking produces (resolved questions, discovered prior art, real scope) must flow back up to the workstream, or the downstream milestones that would benefit never see it.
This matters because the two artifacts have different lifespans. A workstream is always persisted — locally, in Notion, or both — and outlives the whole project. A gameplan often is not: once its patches land, the JSON has served its purpose and may be discarded. So the write-back is not merely a convenience that mirrors knowledge into a second place; for anything learned while planning this milestone, the workstream is frequently the only lasting home. Capture the substance in the workstream prose itself — do not write a workstream entry that says "see the gameplan for details," because the gameplan may be gone.
This step applies only when the gameplan is part of a workstream (the workstream field is non-null). For a standalone gameplan, skip it entirely.
After the gameplan is finalised, validated, and its openQuestions are resolved, propose a write-back to the workstream and wait for the programmer's approval before applying it. Do not mutate the workstream silently: it is a shared planning artifact and may live in an external system (e.g. Notion via [[upsert-notion-gameplan]]). Present the intended edits as a diff or a tight summary, get sign-off, then apply them in place — updating existing entries rather than appending duplicates, and never pushing milestone-local detail up to the workstream level.
The list below is not a sequence or priority order. Treat these four categories as independent; collect every applicable item before presenting the write-back summary, regardless of category.
Propose write-backs for:
Decisions from the open-question dialogue. Every entry added to explicitOpinions during Resolving Open Questions that answers a workstream-level question or constrains a later milestone. Add it to the workstream's Decisions Made and close the corresponding row in its Open Questions. This is the highest-value write-back — workstream open questions are frequently the ones that can only be resolved once a milestone is actually planned.
Cross-cutting precedents discovered during planning. The inverse of Handoff to write-gameplan: if planning surfaced prior art absent from the workstream's Established Precedents and it spans multiple milestones, promote it up using the workstream's four-field shape (kind, name, url, why applicable). Inherit the same discipline as the downward handoff — a precedent scoped to this one gameplan stays on its patch and does not go up.
Scope and Definition-of-Done reconciliation. The finalised gameplan rarely matches the milestone's original Definition of Done exactly — work gets deferred, pulled forward, or split out. Reconcile the milestone record so its Definition of Done, Unlocks, and (if the milestone ends GATED) Operator Actions Before Next Milestone describe what the gameplan actually commits to. Now that flag names and gated state are concrete, fill in placeholder operator actions with the real flag name and the actual signals to watch. If planning revealed follow-on work that does not fit this milestone — a deferred cutover, a flag flip and old-code removal, a newly-discovered dependency — propose adding it as a new or later milestone (with a Definition of Done and dependency edges), rather than letting it evaporate. This is the one write-back permitted to suggest structural changes to the workstream; flag it as such so the programmer can weigh it deliberately.
Status, and a pointer if one is durable. Mark this milestone as planned so the workstream stays a live index of which milestones are unplanned, planned, or executed. You may add a link to the artifact (gameplans/<project-name>.json, or the Notion URL if it was synced) as a convenience, but treat it as potentially dangling — the gameplan may not survive once its patches land. The status itself, and the substance captured in write-backs 1–3, must stand on their own without the link resolving.
The spec and finalStateSpec fields contain source code in a formal specification language. The language is a project-level choice — the gameplan structure is the same regardless of which language you use.
We use Pantagruel — a language for writing formal specifications with domains, rules, and invariants organized into progressive-disclosure chapters.
https://raw.githubusercontent.com/subsetpark/pantagruel/refs/heads/master/REFERENCE.md — fetch this for syntax detailsscripts/validate.py (see Verification). Bare pant <file.pant> type-checks; exit 0 = well-formed; on 0.22, success is silent.pant --check <file.pant> runs SMT-based invariant/precondition checks (requires z3 or cvc5). Use this to catch contradictions, unreachable states, and violated invariants — not a replacement for the parse check. --bound N sets the domain-element bound (default 3); --solver z3|cvc5 picks a solver. The validator does not run --check; invoke it manually when you want SMT coverage.<PROJECT_NAME> (e.g., EXTRACT_DECISION); per-patch specs use <PROJECT_NAME>_PATCH_<N>Patch, Disposition); lowercase identifiers are rules/values (disposition, skip), optionally suffixed with ? or !skip => Disposition. (not Skip => Disposition. — uppercase rule names will not parse)inline-decisions rf: RunnerFiber, p: Patch => Nat0. (not rf: RunnerFiber -> Patch => Nat0.)--- separator; if a patch introduces no new invariants, redeclare the prior chapter's domains/rules so the module is self-containedIf your project uses a different specification language (TLA+, Alloy, Z, etc.), write specs in that language instead. The structural requirements remain:
spec field must be a valid, self-contained spec in the chosen languagefinalStateSpec must cover all invariants from all patchesV2 JSON gameplans are consumed programmatically via the patches and dependencyGraph arrays. Orchestrators like onton can parse the dependency graph directly to identify parallelizable patches and execute them concurrently in isolated git worktrees.
references/gameplan-schema.json — Formal JSON Schema (draft 2020-12)references/example.json — Complete real-world example (uses Pantagruel for specs)scripts/validate.py — End-to-end validator (schema + pant + routing + DAG + testMap + paths). Run python3 scripts/validate.py <gameplan.json> before finalising.