plan · diff
git:20260816.f3c6d0e to git:20260903.10f0277
55 added, 70 removed. Audit A to A.
---
name: plan
- description: 'Shape or refine the existing bead or caller intent without a second planning artifact. Triggers: "plan", "discover and plan", "shape this goal".'
+ description: 'Shape or refine the existing bead or caller intent without a second planning artifact. Triggers: "plan", "discover and plan", "shape this goal", "review write scope", "check scope boundaries", "scope this change".'
practices:
- bdd-gherkin
- design-by-contract
- ddd-bounded-context
hexagonal_role: domain
consumes: []
produces: []
output_contract: 'in-place caller intent update or concise proposed amendment; never an AgentOps planning artifact'
context_rel: []
skill_api_version: 1
user-invocable: true
metadata:
graph_root: true
tier: execution
dependencies: []
capabilities: [shape_intent, define_acceptance, bound_write_scope]
effects: [update_intent_source]
canonical_status: canonical
disposition: keep
---
# Plan
Turn the caller's intent into one bounded, testable behavior in the place that
- already owns the work. Prefer the caller's tracker, if any. When no durable
- tracker or issue reference is available, use the caller's conversation or
- supplied text; the runtime snapshots those resolved intent bytes so later
- contexts can read and hash the same source. Do not make the model restate those
- facts in a packet.
+ already owns the work. Prefer the caller's tracker, if any; otherwise the
+ caller's conversation or supplied text, which the runtime snapshots so later
+ contexts read and hash the same bytes.
+ ## Prompt
+
+ ```text
+ Plan bead ag-1234: "ao gate check lists the probe-coverage row". Shape it in
+ the bead itself: one active behavior, acceptance examples, non-goals, write
+ scope as a class (cli/internal/gates/** plus regen outputs), first check
+ `cd cli && go test ./internal/gates/...`. Update the bead in place.
+ ```
+
+ ## It's working if
+
+ - The bead or issue text itself gains acceptance, non-goals, and write scope;
+ no plan file appears under `.agents/` in the diff.
+ - Write scope names a regen class (`skills/**` plus every output of
+ `scripts/regen-all.sh`), not a hand-enumerated path list.
+ - The plan names one first check as a runnable command, such as
+ `bash scripts/check-x.sh`, and a fresh context given only the source can
+ start Implement.
+
## Workflow
- 1. Resolve the intent source and choose one active behavior. When that source
- is not already durable, have the runtime pass its exact bytes to the
- validate skill's `scripts/validate.py snapshot-intent --source -`, resolved
- relative to wherever that skill package is installed (a repo checkout:
- `skills/validate/scripts/validate.py`; an installed skill package:
- `.agents/skills/validate/scripts/validate.py`), and use the returned
- `intent_ref` for later phases.
- 2. Route the work by type (see **Ground-truth routing**) and name its ground
- truth first. Then inspect only enough real context to make paths, interfaces,
- and evidence concrete: hydrate only the context sources this decision needs
- and carry their citations forward. Existing research and specialist skills
- are advisory inputs, never a merged context store.
+ 1. Resolve the intent source and choose one active behavior. When the source
+ is not durable, have the runtime pass its exact bytes to the validate
+ skill's `scripts/validate.py snapshot-intent --source -` (under
+ `skills/validate/` in a checkout, `.agents/skills/validate/` when
+ installed) and carry the returned `intent_ref` into later phases.
+ 2. Route the work by type (Integrate, Extend, or Greenfield) and name its
+ ground truth, control experiment, and deviation ledger first from
+ [references/ground-truth-routing.md](references/ground-truth-routing.md).
+ Then inspect only enough real context to make paths, interfaces, and
+ evidence concrete, carrying citations forward; research and specialist
+ skills are advisory inputs.
3. Ensure the source contains acceptance examples, important non-goals, and the
allowed write scope. Use lightweight prose or Given/When/Then only where it
- removes ambiguity; do not require both normal and edge ceremony for every
- change.
+ removes ambiguity. Write-scope checks (folded from the retired `scope` skill):
+ - patterns are normalized repository-relative paths;
+ - includes cover the behavior without granting unrelated directories;
+ - excludes do not contradict required changes;
+ - generated companions that must move with the sources are explicit;
+ - no ownership, scheduling, Git, hook, retry, release, or delivery state.
4. Name the first useful acceptance check.
5. If authorized and the source is writable, update that bead or issue in
place. Otherwise return a concise proposed amendment to the caller.
- Planning produces no AgentOps packet. A durable caller-owned source stays in
- place; the runtime carries its reference and the digest of its exact resolved
- bytes to detect later acceptance drift. Only when no durable source exists does
- the runtime store those bytes under their digest as a content-addressed
- snapshot. That fallback is derived automatically and is not another
- model-authored planning artifact.
-
- Bound the work around the caller-visible outcome, not individual files, gates,
- or reviewer comments. Decomposition is useful only when it reduces reasoning
- cost; it must not multiply invocations or proof artifacts.
+ Planning produces no AgentOps packet: the runtime carries the source's
+ reference and digest to detect acceptance drift. Bound the work around the
+ caller-visible outcome, not files, gates, or reviewer comments; decompose only
+ when it reduces reasoning cost.
## Scope admission
- In a repository with generated projections, write scope names generator-owned
- outputs as a class — the hand-edited sources plus all outputs of the owning
- regen commands — never as a hand-enumerated path list. Hand enumeration is
- falsified the first time a regen command rewrites a companion the author did
- not list: the 2026-07-15 heal-skill fold burned two implement lanes and three
- intent revisions (`.agents/ao/intents/sha256/d1db59d4...2b81` superseded by
- `f5fd7c3c...af75` superseded by `26a4f2be...eb48`) before scope was restated
- as a class.
-
- Before freezing acceptance, run a complexity admission: enumerate the
- generated companions, parity twins (for example a `skills-codex/` mirror), and
- test files that assert on the paths being changed. Anything this pass finds
- that the scope does not admit will surface later as an out-of-scope diff or a
- broken gate.
-
- ## Ground-truth routing
-
- Every plan needs a ground truth outside the planner's own reasoning. Before
- freezing acceptance, classify the work and name its ground truth, its control
- experiment, and its deviation ledger from the row below.
-
- | Work type | Ground truth | Control experiment | Deviation ledger |
- |---|---|---|---|
- | Integrate an external substrate, runtime, tracker, or service | the vendor's own docs plus stock behavior | run their vanilla quickstart on pinned versions with zero local code, before designing | each deviation from the documented flow, each justified; and every component you write that has a native counterpart in the substrate |
- | Extend this project | the repo's existing patterns and behavior spec | the simplest version that satisfies acceptance, and why it is insufficient | each novelty introduced — new abstraction, dependency, or pattern |
- | Greenfield | reference experience and domain prior art | a walking skeleton | each deviation from the boring default, ~one novelty per change |
-
- The Extend row is already the repo's default discipline: behavior-first
- acceptance, RED -> GREEN, the smallest real change. The Integrate row is the one
- that is cheap to skip and expensive to have skipped — run the stock control
- experiment *before* you design, or you will re-plumb what the substrate already
- documents and inherit bugs you built yourself.
-
- Trigger: the Integrate-row mechanics — the stock-quickstart control run and the
- deviation ledger from the documented flow — apply only to integration-class work
- (adopting or wiring in an external substrate, runtime, tracker, or service).
- Routine feature work on this project uses the Extend row and does not incur them.
+ At scope, read `boundaries.md` in the rpi skill's `references` directory for
+ what Plan does not own. In a repository with generated projections, write
+ scope names generator-owned outputs as a class (the hand-edited sources plus
+ all outputs of the owning regen commands), because a hand-enumerated list is
+ falsified the first time a regen command rewrites an unlisted companion.
+ Before freezing acceptance, enumerate the generated companions, parity twins
+ such as `skills-codex/`, and tests asserting on the changed paths;
+ anything unadmitted here surfaces later as an out-of-scope diff or a broken
+ gate.
A plan is done only when it passes the fresh-context test: a cold context,
- given the intent source alone, could execute it without the author's
- conversation. If execution needs facts that live only in the planning
- conversation, move them into the source before freezing.
+ given the intent source alone, could execute it. Move any fact that lives only
+ in the planning conversation into the source before freezing.