sergdort/opencode-extensions/plan-feature

Operate in the main thread as Architect. Create or update the implementation plan for the active workflow. Use any path accompanying the invocation as the plan target.

Do not delegate planning to another agent. Use read-only explorers and advisors only for bounded evidence or review.

Resolve The Plan

• A named Markdown file is the plan path.
• A named directory resolves to <directory>/plan.md.
• With no path, use plan.md in the current repository or working directory.
• Read an existing target before updating it.
• Read decision-brief.md next to the plan when present.
• Use the current Architect conversation with the brief as the architecture

source of truth.

• Do not require handoffs, ADRs, or other hidden or additional state.

If the architecture context is missing, ambiguous, or conflicts with repository reality, stop and ask the user. Do not invent a decision.

Output

Create or update exactly one temporary artifact: the resolved plan.md. Do not create behavior files, ADRs, or extra planning artifacts unless the user explicitly asks.

Use this shape unless the feature needs a small adjustment:

# Plan: <feature>
 
## Goal
 
One or two sentences describing the intended outcome.
 
## Constraints
 
Only implementation-relevant constraints. Omit if empty.
 
## Execution Sketch
 
Pseudo-code-level structure showing key types, interfaces, functions,
ownership boundaries, and composition.
 
## Call Flow
 
Representative happy path and important failure path call stacks.
 
## Change Map
 
Compact file-tree diff of expected additions, modifications, and removals,
with key symbols and ownership where useful.
 
## Work Steps
 
Ordered vertical slices. The first behavior slice produces the smallest
runnable or directly observable end-to-end path.
 
## Behavioral Contract
 
Gherkin scenarios for observable behavior.
 
## Verification
 
Checks for important scenarios and risks, including runtime touchpoints and
fail-before/pass-after evidence where required.
 
## Human Review
 
Workflow profile, reviewer, tracer checkpoint, high-risk checkpoints, and
final review.
 
## Review Notes
 
Review status, feedback incorporated, or why review was unavailable.

Keep the artifact concise, executable, and action-oriented.

Program-Design Baseline

• Execution Sketch is the reviewed authority for shared interfaces.
• Call Flow traces entrypoints, modules, state or data changes, failures, and

result handling without enumerating every branch.

• Change Map is a design-review aid, not a promise that no neighboring file

will change.

• Work steps are vertical and touchable, not database/service/API/UI layers.
• Prefer a browser path, CLI command, API call, integration point, or public

API test as the first feedback point.

• The tracer normally materializes only the interfaces it needs.
• Use a separate contract-only predecessor only for a narrow, genuinely stable

external or shared boundary that consumers require first.

• If tracer feedback disproves a planned seam, update the plan before later

work builds on it.

Behavioral Contract

Write observable Gherkin scenarios. Prefer these tags when useful:

@must
@edge
@failure
@migration
@observability
@manual
@deferred
@tdd

Every @must scenario must include or imply one verification mode:

test-first
implementation-first
characterization-first
manual-verification

Choose the cheapest reliable strategy. For bug fixes and test-first scenarios, require credible fail-before/pass-after evidence. Allow a recorded exception when a pre-change failure cannot be run safely or meaningfully. Do not add elaborate test infrastructure only to satisfy TDD.

Review

• Pressure-test the plan before calling it ready.
• For high-risk work, use oracle when available and incorporate material

findings.

• Use contrarian for one load-bearing program-design seam that has not

already faced a serious stress test. Do not ask it to review the whole plan.

• Use plannotator-visual-explainer only when it is installed and a visual

explanation would materially improve review. It is optional and never replaces plan.md.

• Otherwise self-review against the goal, constraints, design, behavioral

contract, and verification.

• Confirm the workflow profile and checkpoints from the brief.
• Assign an available user or peer to pre-acceptance checkpoints.
• Record whether final review happens locally or in the eventual pull request.
• Agent review and Codex's built-in /review never replace human checkpoints.
• Present the plan to the user for confirmation and record the outcome in

Review Notes.

Do not turn review into a rigid approval state machine. The user decides when to proceed.

plan.md remains uncommitted temporary workflow state. Never stage or commit it, and never remove workflow artifacts.

Final Response

Report the resolved path, whether the plan was created or updated, review status, open questions, and the next explicit invocation: $decompose (with the plan path when non-default).