Claude
opencode
Skill
plan
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".
Virus-scanned
Reviewed automatically before listing.
Download
boshu2-agentops-skills_plan-c3fe161.zip · 9 KB
Install
skills CLI
npx skills add https://github.com/boshu2/agentops/tree/main/skills/plan
Claude Code
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install boshu2-agentops@llmmart
Git
git clone https://github.com/boshu2/agentops.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole boshu2/agentops collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Plan
Own discovery from the caller's question to one actionable slice. Shape only missing intent. Prefer the caller's tracker, if any; otherwise use the conversation or supplied text. Planning produces no AgentOps packet. A clear change can proceed directly. Use established domain names throughout intent, examples, code and validation. Load a specialist only for the question it can answer; none is a required planning stage.
Workflow
- Read accepted intent, the compact existing plan or native handoff, and the relevant source owners and active constraints. On replacement or resumption, use Resume discovery before choosing a next action. Identify the caller-visible outcome and classify only uncertainty that could change the next slice using Route uncertainty.
- Describe the intended observable behavior before implementation. Reuse acceptance already supplied in the conversation or bead; clarify only what prevents action or judgment. Name the actor or caller, the event and the observable result. One example often suffices; use Given/When/Then for branching behavior and consequential boundaries. Include non-goals only where they prevent a plausible scope mistake in that existing source. If the caller requests both code and a retrospective, distinguish code acceptance, delivery facts and the later analysis in that same intent. Code judgment consumes acceptance and checks; the retrospective consumes the known outcome and judgment. Keep both requested deliverables required for the overall goal without making either depend on its own conclusion. Scope includes the hand-edited owners, affected tests/live consumers and generator-owned companions as a class; it is authority, not a predicted file count. A consequential assumption deserves an early discriminating check, not a general checklist or exhaustive survey.
- Refine one narrow but complete vertical slice, including its affected layers,
live consumers and useful check. It must produce an independently observable
result, not just a schema, interface or plan for another layer. Keep later
work coarse in the existing intent; sharpen it only when new evidence makes
the next slice actionable. For a mechanical cross-cutting migration that
cannot stay working slice by slice, preserve compatibility with an
expand/migrate/contract approach and state where integration is required.
Include recapture of affected bound evidence where necessary; use
ao provenance evidence-orphanswhen applicable, not a mandatory ledger. - When evidence disproves an approach, briefly retain the failed assumption, evidence and revised check in the existing intent or handoff. Approach changes within accepted outcome and scope need no new permission; acceptance or scope expansion requires caller authority. Never relabel a failed acceptance condition as a caveat to obtain green.
- Give another context exact intent references and the evidence it needs to act, its write scope and who owns integration and final review. Keep approach notes separate from frozen acceptance. Pass the next decision and relevant source references, not the entire research history. A new goal does not clear an existing conversation, and a fresh context can still have large startup instructions, tool catalogs and retrieved inputs.
Stop planning once the implementer can act and the validator can judge. More research, decomposition or review must resolve a named remaining uncertainty. An optional probe or prototype can test a named assumption. An optional challenge can examine consequential uncertainty that survives source checks and relevant observations. Memory recall is useful only when prior evidence could change the next action.
Route uncertainty
Keep these distinctions in the existing intent only where they affect action; they are not four required worksheets or successive stages.
| Uncertainty | Next action |
|---|---|
| Source-answerable fact | Inspect the smallest authoritative source and cite it. Research owns deeper tracing and evidence synthesis; Domain owns ambiguous vocabulary and rule boundaries. Do not ask the caller to recite a retrievable fact. |
| Consequential caller choice | Recover existing authorization first. Ask one focused question only when goal, behavior, preference or authority still needs the caller. Include the concrete tradeoff; an agent cannot supply the caller's answer. |
| Assumption requiring a probe | State the competing predictions and smallest observation that distinguishes them. Use the optional probe method; a persuasive design or agent vote cannot settle unobserved behavior. |
| Safely deferred decision | State why it does not block this slice and the event or evidence that would make it relevant. Keep it coarse; deferral cannot hide an unanswered acceptance condition. |
Resolve reversible implementation details within accepted scope. Mark inference and missing evidence explicitly; do not promote either into a source fact or a settled caller choice. An optional challenge returns advice or a next discriminator, never permission or acceptance.
Resume discovery
Recover the current outcome, accepted examples and source identity from the existing plan or native handoff. Reuse settled domain terms and caller choices with their source pointers; do not repeat an interview or load the full transcript. Read details on demand only if a missing fact or new contradiction can change the next decision. Before reusing inherited prototype evidence, follow Reuse after source drift.
Check active assignments, write scopes and integration/review ownership against the native tracker or runtime before suggesting more work. Handoff facts are recovery pointers, not a second authoritative assignment or status ledger. If the native source is unavailable or contradicts the handoff, report that gap and resolve it before dependent dispatch or overlapping writes; independently safe discovery can continue.
Leave a compact update in that same source when interruption or replacement would otherwise lose a decision: accepted outcome/reference; settled choices and evidence; active assignment references and scopes; the one open question and next discriminator; deferred decisions and their revisit triggers. Include known failed assumptions and relevant contrary evidence. An unchanged recovery needs no duplicate artifact. Preserve native ownership and original evidence; new observations amend the approach within scope, while changed acceptance still needs the caller.
Behavior and naming
An example can be plain text; BDD does not require a .feature file or an
interview. For example, in a repository that calls queued work a Job:
Given a Job has already completed, when the worker receives it again, then its completed result is returned and its side effect is not repeated.
Use the actual domain term instead of inventing a parallel label such as "task item." Identify what the caller can observe and the smallest check that distinguishes the desired behavior from the current failure. Keep the accepted example available to Implement and Validate. Tests added after coding may supplement it; they cannot redefine what was promised.
For uncertain designs, probe the assumption that could change the approach. For product planning, distinguish demonstrated behavior from aspiration and refine the existing product owner only within the request. A product document is not required for an ordinary feature.
Decision cost and stopping
Use real undo cost, affected users and existing authority when choosing who must decide. Resolve reversible implementation details within accepted scope. A material irreversible choice outside that authority needs the caller; prior authorization remains valid. Reviewer agreement is evidence, not permission to replace the caller's intent. Explain a consequential disagreement and its support rather than silently changing acceptance.
A proposed process artifact earns its cost only with a concrete consumer, subject or release decision, observed defect and retirement condition. If the next action adds only ceremony or repeats settled evidence, omit it. Stop when the implementer can act and the validator can judge, reserving capacity for implementation, integration and repair.
Decision pointers and coarse future work adapt ideas from Matt Pocock's Wayfinder; complete slices and compatibility migrations adapt To Tickets. AgentOps keeps the caller's existing intent and native work authority.
Identity and scope
Use runtime-derived source identity and digest. If conversation intent needs
an exact snapshot, existing ao provenance snapshot-intent --source - --evidence-root <explicit-root> uses caller-selected protected external
non-Git storage. Missing routing permits neither workspace fallback nor a
second planning artifact. Preserve legacy proof.
Use normalized repository-relative scope patterns. An uncovered live consumer needs a concise exact-file amendment to the caller; continue independent in-scope work meanwhile. Generated companions already in scope need no extra permission. Boundaries keep work/status in the caller's tracker and delivery under repository policy.
Files (agentops)
-
references
-
challenge.md 3.4 KB
# Optional challenge Plan owns this shared method. Load it for consequential uncertainty that survives the available source checks and relevant observations. Clear tasks and known repairs proceed directly. Source facts need sources, empirical unknowns need observations, and caller choices need the caller. ## One bounded exchange 1. Frame the accepted outcome, disputed claim, relevant source pointers and the decision at stake. Preserve acceptance and scope unchanged. Use the author's proposal plus one fresh challenger by default, with distinct native context identity and only the inputs needed for this question. Follow [model-dispatch](../../agent-native/references/model-dispatch.md) for actual authorization, same-family default, explicit cross-model selection and real remaining bounds. Method selection itself grants no dispatch authority. 2. The challenger gives the strongest counterexample or contrary evidence, identifies the assumption it attacks, and names what would change its view. Unsupported possibilities remain hypotheses; seek a concrete defeating construction when possible. 3. The author answers once with a source, corrected proposal, bounded probe or admitted uncertainty. This is one targeted exchange, not a loop until agents agree. A replacement reply context gets the disputed claim, cited evidence and question/answer delta only; its reply is not a new independent vote. 4. Stop when a correction resolves the defect, a source settles the fact, a caller-owned choice is isolated, a test is the remaining discriminator, no useful novelty remains, or the actual limit is reached. Retain disagreement when it survives. Further investigation needs a named unanswered question and room within existing authority and bounds, never a renewed allowance. Record the supported decision or unresolved choice, strongest counterevidence, reason to revise or retain the approach, and next check in the existing intent or native handoff. Pass this compact delta to the implementer; do not load the full debate transcript. More extensive evidence is only for a concrete consumer or requested audit under the existing storage rules. ## Other selected strategies When independent alternatives themselves matter, two sealed positions may be selected: each author receives the same accepted question and source evidence without seeing the other's proposal. Compare only after both initial positions are fixed; later replies are peer-informed and no longer independent. Give both the same newly discovered decisive source, or disclose the unequal evidence. An independent derivation can also be compared with an already fixed proposal. [Premortem](../../premortem/SKILL.md) owns a requested plan-failure examination, including evidence shape, reversibility and concrete defeat attempts. [Council](../../council/SKILL.md) remains a caller-selected broader strategy. Neither is required for this method. Explicitly required review legs remain required; a cheaper challenge cannot replace them. Challenge produces advisory evidence. Agreement is neither caller approval nor independent confirmation of correctness. It cannot issue acceptance, change work ownership, admit context, close work or replace fresh author-distinct Validate over exact content and unchanged acceptance. No general improvement in outcomes or resource use is claimed without comparable task evidence. -
ground-truth-routing.md 3.7 KB
# Optional probes and prototypes Use this method only when an observation could change a consequential approach or clarify the caller's reaction to concrete behavior. First inspect existing evidence: a clear task or already answered question needs no prototype, stock quickstart, control experiment or deviation ledger. Before running anything, state in the existing intent or handoff: 1. The question and assumption under test, including the accepted behavior that must remain true. 2. The discriminator: competing predictions and the observation that would distinguish them. A mock-up may elicit a caller preference; it cannot prove runtime behavior, durability or integration that it does not exercise. 3. The disposable scope, authorized inputs/destination and real time or cost bound. Use the smallest safe construction; do not touch production or widen write authority to make a prototype realistic. 4. The stop: sufficient distinguishing evidence, an inaccessible prerequisite, no useful new observation, or the existing resource limit. A stopped or inconclusive probe leaves the assumption unresolved; it does not justify retrying until the preferred answer appears. Choose relevant ground truth, not a compulsory sequence: | Question | Useful evidence or discriminator | |---|---| | Does an external substrate already provide the needed behavior? | Current vendor documentation and pinned stock behavior; run a vanilla quickstart only when it answers the named uncertainty. Compare proposed additions with native capabilities before rebuilding them. | | Can the repository's existing approach satisfy the example? | Trace its relevant behavior and try the simplest acceptance-relevant change or test. Retain evidence if it cannot meet the example. | | Can a new path work end to end? | A walking skeleton through the uncertain boundary, with an observable result. | | Which interaction does the caller want? | A small concrete mock-up and the caller's response; only the caller settles that preference. | Return the observation, its source/configuration, limitations, and the decision or next question it supports. Preserve failed predictions as evidence. If a documented native path needs a deviation, retain its reason and support in the existing intent. Keep only decision-relevant details and pointers in the existing handoff, not the whole experiment transcript. Disposable work is not a production implementation; retain or remove it under the caller's ownership and storage policy. New proof uses the existing protected external storage boundary when applicable. ## Reuse after source drift Before reusing inherited prototype evidence when discovery resumes, check the current referenced interface and relevant environment assumptions against the observation's recorded source/configuration. Check what could change the named result; a purely unrelated source change does not require repetition. If a changed assumption could affect the result, preserve the earlier observation with its original context and repeat only the smallest discriminating probe against the current subject before declaring that empirical question resolved. Record the new observation and its limitations in the existing intent or handoff; do not replay the broader research. If relevant assumptions cannot be checked or required execution is unavailable, leave that empirical question explicitly unresolved. Continue only independent ready work that does not rely on the result. A prototype cannot change intent, authorize implementation or establish acceptance. Even promising results require implementation checks and fresh exact-content judgment. No new tracker, control ledger or automatic context admission follows from the experiment. -
plan.feature 1.2 KB · in bundle
-
-
scripts
-
validate.sh 1.5 KB
#!/usr/bin/env bash set -euo pipefail skill_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" grep -q '^name: plan$' "$skill_dir/SKILL.md" # Static contract regression checks, not proof of a live planner's behavior. # test_no_model_authored_packet grep -Fq "Prefer the caller's tracker, if any" "$skill_dir/SKILL.md" grep -Fq 'Planning produces no AgentOps packet' "$skill_dir/SKILL.md" if grep -Fq 'plan-packet.v1' "$skill_dir/SKILL.md"; then echo 'plan contract references a model-authored plan packet' >&2 exit 1 fi # Selective method links must ship their source owners. for reference in ground-truth-routing.md challenge.md; do grep -Fq "references/$reference" "$skill_dir/SKILL.md" test -s "$skill_dir/references/$reference" done # test_optional_discovery_methods: reject the original mandatory-control rule. if grep -Eiq 'Every plan needs a ground truth|run the stock control|mandatory deviation ledger' \ "$skill_dir/references/ground-truth-routing.md"; then echo 'plan routing restores a mandatory control or ledger' >&2 exit 1 fi # test_native_handoff_boundary: factual native references are legal. The old # blanket prohibition would prevent recovery; it was not a lifecycle guard. if grep -Eq 'contains no owner, ready, claim, priority, attempt, wave, queue, lease, admission, next action' \ "$skill_dir/references/plan.feature"; then echo 'plan scenarios forbid factual native handoff recovery' >&2 exit 1 fi echo 'plan static contract checks: PASS (live behavior not evaluated)'
-
-
SKILL.md 10.3 KB
--- name: plan description: 'Define intended behavior, review write scope and assess reversible decisions. Use when: discovery needs clarification or resumption before one complete slice; stop once actionable.' 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, resume_discovery] effects: [update_intent_source] canonical_status: canonical disposition: keep --- # Plan Own discovery from the caller's question to one actionable slice. Shape only missing intent. Prefer the caller's tracker, if any; otherwise use the conversation or supplied text. Planning produces no AgentOps packet. A clear change can proceed directly. Use established domain names throughout intent, examples, code and validation. Load a specialist only for the question it can answer; none is a required planning stage. ## Workflow 1. Read accepted intent, the compact existing plan or native handoff, and the relevant source owners and active constraints. On replacement or resumption, use [Resume discovery](#resume-discovery) before choosing a next action. Identify the caller-visible outcome and classify only uncertainty that could change the next slice using [Route uncertainty](#route-uncertainty). 2. Describe the intended observable behavior before implementation. Reuse acceptance already supplied in the conversation or bead; clarify only what prevents action or judgment. Name the actor or caller, the event and the observable result. One example often suffices; use Given/When/Then for branching behavior and consequential boundaries. Include non-goals only where they prevent a plausible scope mistake in that existing source. If the caller requests both code and a retrospective, distinguish code acceptance, delivery facts and the later analysis in that same intent. Code judgment consumes acceptance and checks; the retrospective consumes the known outcome and judgment. Keep both requested deliverables required for the overall goal without making either depend on its own conclusion. Scope includes the hand-edited owners, affected tests/live consumers and generator-owned companions as a class; it is authority, not a predicted file count. A consequential assumption deserves an early discriminating check, not a general checklist or exhaustive survey. 3. Refine one narrow but complete vertical slice, including its affected layers, live consumers and useful check. It must produce an independently observable result, not just a schema, interface or plan for another layer. Keep later work coarse in the existing intent; sharpen it only when new evidence makes the next slice actionable. For a mechanical cross-cutting migration that cannot stay working slice by slice, preserve compatibility with an expand/migrate/contract approach and state where integration is required. Include recapture of affected bound evidence where necessary; use `ao provenance evidence-orphans` when applicable, not a mandatory ledger. 4. When evidence disproves an approach, briefly retain the failed assumption, evidence and revised check in the existing intent or handoff. Approach changes within accepted outcome and scope need no new permission; acceptance or scope expansion requires caller authority. Never relabel a failed acceptance condition as a caveat to obtain green. 5. Give another context exact intent references and the evidence it needs to act, its write scope and who owns integration and final review. Keep approach notes separate from frozen acceptance. Pass the next decision and relevant source references, not the entire research history. A new goal does not clear an existing conversation, and a fresh context can still have large startup instructions, tool catalogs and retrieved inputs. Stop planning once the implementer can act and the validator can judge. More research, decomposition or review must resolve a named remaining uncertainty. An optional [probe or prototype](references/ground-truth-routing.md) can test a named assumption. An optional [challenge](references/challenge.md) can examine consequential uncertainty that survives source checks and relevant observations. [Memory recall](../memory/references/recall.md) is useful only when prior evidence could change the next action. ## Route uncertainty Keep these distinctions in the existing intent only where they affect action; they are not four required worksheets or successive stages. | Uncertainty | Next action | |---|---| | Source-answerable fact | Inspect the smallest authoritative source and cite it. [Research](../research/SKILL.md) owns deeper tracing and evidence synthesis; [Domain](../domain/SKILL.md) owns ambiguous vocabulary and rule boundaries. Do not ask the caller to recite a retrievable fact. | | Consequential caller choice | Recover existing authorization first. Ask one focused question only when goal, behavior, preference or authority still needs the caller. Include the concrete tradeoff; an agent cannot supply the caller's answer. | | Assumption requiring a probe | State the competing predictions and smallest observation that distinguishes them. Use the optional probe method; a persuasive design or agent vote cannot settle unobserved behavior. | | Safely deferred decision | State why it does not block this slice and the event or evidence that would make it relevant. Keep it coarse; deferral cannot hide an unanswered acceptance condition. | Resolve reversible implementation details within accepted scope. Mark inference and missing evidence explicitly; do not promote either into a source fact or a settled caller choice. An optional challenge returns advice or a next discriminator, never permission or acceptance. ## Resume discovery Recover the current outcome, accepted examples and source identity from the existing plan or native handoff. Reuse settled domain terms and caller choices with their source pointers; do not repeat an interview or load the full transcript. Read details on demand only if a missing fact or new contradiction can change the next decision. Before reusing inherited prototype evidence, follow [Reuse after source drift](references/ground-truth-routing.md#reuse-after-source-drift). Check active assignments, write scopes and integration/review ownership against the native tracker or runtime before suggesting more work. Handoff facts are recovery pointers, not a second authoritative assignment or status ledger. If the native source is unavailable or contradicts the handoff, report that gap and resolve it before dependent dispatch or overlapping writes; independently safe discovery can continue. Leave a compact update in that same source when interruption or replacement would otherwise lose a decision: accepted outcome/reference; settled choices and evidence; active assignment references and scopes; the one open question and next discriminator; deferred decisions and their revisit triggers. Include known failed assumptions and relevant contrary evidence. An unchanged recovery needs no duplicate artifact. Preserve native ownership and original evidence; new observations amend the approach within scope, while changed acceptance still needs the caller. ## Behavior and naming An example can be plain text; BDD does not require a `.feature` file or an interview. For example, in a repository that calls queued work a **Job**: > Given a Job has already completed, when the worker receives it again, > then its completed result is returned and its side effect is not repeated. Use the actual domain term instead of inventing a parallel label such as "task item." Identify what the caller can observe and the smallest check that distinguishes the desired behavior from the current failure. Keep the accepted example available to Implement and Validate. Tests added after coding may supplement it; they cannot redefine what was promised. For uncertain designs, probe the assumption that could change the approach. For product planning, distinguish demonstrated behavior from aspiration and refine the existing product owner only within the request. A product document is not required for an ordinary feature. ## Decision cost and stopping Use real undo cost, affected users and existing authority when choosing who must decide. Resolve reversible implementation details within accepted scope. A material irreversible choice outside that authority needs the caller; prior authorization remains valid. Reviewer agreement is evidence, not permission to replace the caller's intent. Explain a consequential disagreement and its support rather than silently changing acceptance. A proposed process artifact earns its cost only with a concrete consumer, subject or release decision, observed defect and retirement condition. If the next action adds only ceremony or repeats settled evidence, omit it. Stop when the implementer can act and the validator can judge, reserving capacity for implementation, integration and repair. Decision pointers and coarse future work adapt ideas from Matt Pocock's [Wayfinder](https://github.com/mattpocock/skills/blob/main/skills/engineering/wayfinder/SKILL.md); complete slices and compatibility migrations adapt [To Tickets](https://github.com/mattpocock/skills/blob/main/skills/engineering/to-tickets/SKILL.md). AgentOps keeps the caller's existing intent and native work authority. ## Identity and scope Use runtime-derived source identity and digest. If conversation intent needs an exact snapshot, existing `ao provenance snapshot-intent --source - --evidence-root <explicit-root>` uses caller-selected protected external non-Git storage. Missing routing permits neither workspace fallback nor a second planning artifact. Preserve legacy proof. Use normalized repository-relative scope patterns. An uncovered live consumer needs a concise exact-file amendment to the caller; continue independent in-scope work meanwhile. Generated companions already in scope need no extra permission. [Boundaries](../rpi/references/boundaries.md) keep work/status in the caller's tracker and delivery under repository policy.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.