superplan-md/superplan-plugin/superplan-execute

Execute Task Graph

Overview

Move graph-ready work forward without drifting into broad replanning or unnecessary CLI exploration.

This is the main execution control surface once work has been shaped. It should behave more like a scheduler and control plane than a single linear worker.

Execution should be primarily subagent-driven:

• select ready work
• dispatch bounded worker tasks
• dispatch verification in parallel where safe
• collect evidence and runtime signals
• decide continue, block, ask, review, or re-shape

Specific-Owner Rule

Once execution starts, prefer the narrowest execution sub-problem over broad workflow reconsideration.

• use superplan-debug when a failure blocks forward motion
• use superplan-tdd when a new behavior or bugfix can be expressed as a proof-first implementation step
• use superplan-verify when success claims are approaching faster than proof
• use superplan-review when the question becomes "is this task actually done?"

Trigger

Use when:

• there is executable tracked work
• at least one task is graph-ready
• the next need is to operate inside the shaped work rather than redesign it
• the system can make progress by dispatching one or more bounded work units

Stay Out

Do not run when:

• the system is still deciding whether Superplan should engage
• shaping has not happened yet
• context or bootstrap is the real missing prerequisite
• the graph is invalid enough that execution should stop and escalate

Inputs And Assumptions

Inputs:

• current task graph
• task contracts
• runtime state if present
• relevant workspace context
• current ready or blocking status
• relevant user-owned harnesses, scripts, custom skills, and workflows
• recent decision log entries affecting execution
• known workspace or task gotchas

Assumptions:

• execution should operate on ready work, not constantly redesign the project
• not every execution issue is a reason to reshape the graph
• multiple ready tasks may be best handled by subagents in parallel
• implementation and verification can sometimes run in parallel, but only when their contracts and write surfaces make that safe
• trajectory will change during execution; the key question is whether the change is local, structural, or strategic
• execution should route into existing workspace workflows rather than trying to replace them
• execution should stop reading and act once the next edit, command, or blocker transition is clear

Graph, Contract, And Runtime Rule

Keep these layers distinct:

• graph truth decides readiness and dependency state
• task-contract truth defines the bounded unit and its acceptance criteria
• runtime truth records what is in progress, blocked, waiting for feedback, or review-ready

Do not collapse execution into a flat task-file-only mindset.

See references/runtime-state.md.

CLI Alignment Now

Align execution to the CLI that exists today.

Current CLI execution surface:

• superplan task inspect show <task_ref> --json
• superplan run --json
• superplan run --fresh --json
• superplan run <task_ref> --json
• superplan task runtime block <task_ref> --reason <reason> --json
• superplan task runtime request-feedback <task_ref> --message <message> --json
• superplan task review complete <task_ref> --json
• superplan task repair fix --json
• superplan status --json
• superplan worktree ensure <change-slug> --json
• superplan worktree list --json
• superplan worktree detach <change-slug> --json
• superplan worktree prune --json

Current CLI truth:

• readiness is computed from parsed task contracts plus runtime state
• runtime states currently include in_progress, in_review, done, blocked, and needs_feedback
• runtime files live under the shared project state root ~/.config/superplan/project-<name>-<hash>/runtime/, which the CLI may render as .superplan/runtime/... from the repo root
• superplan task inspect show <task_ref> --json includes one task's computed readiness reasons
• superplan status --json is the current narrow runtime summary surface even though a persisted .superplan/runtime/current.json-style summary is still only a product target
• review handoff is now represented explicitly as in_review

Therefore:

• use CLI transitions instead of hand-editing execution state
• use status --json and run --json to inspect the frontier; use task inspect show <task_ref> --json only when one specific task needs deeper inspection
• keep approval decisions explicit through complete, approve, and reopen
• do not end an execution turn after successful implementation proof while the task lifecycle still says pending or in_progress; either move it through complete and the appropriate review state or explicitly report the blocker that prevented that transition

CLI Discipline

Execution is not permission to wander across CLI commands.

• start from the current task contract, the superplan run payload, and one relevant verification path
• do not call --help, neighboring subcommands, or extra diagnostic commands when the next execution command is already known
• use superplan task inspect show <task_ref> --json only when one task's detailed readiness or reasons are actually needed
• use superplan doctor --json only for setup or install issues, not normal execution
• once you know the next command, edit, or blocker transition, stop probing the CLI and act

User Communication

Execution updates must describe actual work performed, current verification, material risks, and user-impacting decisions. Do not narrate Superplan ceremony.

• This skill runs in control-plane mode.
• do not mention scheduler behavior, subagent dispatch, runtime transitions, command history, or other Superplan mechanics unless the user needs that fact to understand a blocker, risk, or decision
• reject updates that are primarily internal process commentary
• tell the user what changed in the workspace, what verification is being run and for what risk, what decision was made and why, or what concrete blocker needs user input
• do not let execution updates drift into planning-mode essays unless the user actually needs approach selection or trade-off review

Lifecycle Semantics And Recovery

Use the CLI as the transition gate for runtime state.

• graph-blocked means dependencies are not yet satisfied
• runtime-blocked means real execution trouble encountered while already working
• needs_feedback means the task cannot proceed without a human decision
• in_review means implementation is complete enough for acceptance review and waiting on approval or reopen

When to Mark Done vs Request Feedback

Mark task done when:

• Component built and tests pass
• Code written and verified working
• Routine implementation complete with proof
• All acceptance criteria satisfied with evidence
• No user decision required

Request feedback only for genuine blockers:

• Requirements unclear — need user decision on specific tradeoff
• Two valid approaches — which convention or path do you prefer?
• External dependency changed — need new credentials or config
• Conflicting patterns found — which codebase convention to follow?
• Unexpected technical constraint — need scope or approach adjustment
• User verification required before proceeding

Do not use needs_feedback for routine work completion. Completion with passing verification should transition through review complete, not feedback request.

• impossible transitions should fail hard
• invalid or stale task contracts should block safe forward motion
• do not recover by hand-editing runtime files or markdown execution state
• passing tests or successful verification do not count as enough closure by themselves; runtime truth must be updated before claiming the task is effectively finished

Recovery rules:

• safe idempotent reruns are acceptable where the CLI already supports them
• use superplan task repair fix for deterministic runtime repair
• use superplan task repair reset <task_ref> only as an explicit recovery action, not as the normal path

See references/runtime-state.md and references/lifecycle-semantics.md.

Trajectory Change Model

Classify discovered changes into three buckets:

• local trajectory change: implementation details vary but the task contract still holds
• structural trajectory change: dependencies, task boundaries, or contract validity changed materially
• strategic trajectory change: user goals or top-level expectations changed

Authority:

• local: stay inside execution
• structural: pause affected work and route to superplan-shape
• strategic: stop broad execution and route upward to superplan-route

See references/trajectory-changes.md.

Allowed Actions

• choose graph-ready work
• choose whether work should run:
• serially
• in parallel by branch
• in parallel by worker/verifier split
• dispatch bounded subagents for ready work
• assign clear ownership for each subagent's task or write surface
• dispatch verification in parallel where safe and useful
• dispatch subagents through existing repo scripts, custom skills, or harnesses when those are the trusted path
• begin task execution
• inspect the frontier with superplan status --json and superplan run --json; use superplan task inspect show <task_ref> --json when one task needs full detail
• repair invalid runtime drift deterministically with superplan task repair fix when warranted
• surface blocked state
• surface needs-feedback state
• route toward review when work appears ready
• collect evidence from subagents and merge it into runtime understanding
• re-evaluate the current frontier after major task events
• classify trajectory changes as local, structural, or strategic
• invoke support disciplines for debugging, tests, and verification
• append meaningful execution decisions to durable decision memory
• append newly discovered traps to gotcha memory when likely to matter again

Recommended patterns:

• branch parallelism
• worker plus verifier
• blocker investigation
• review shadowing

See references/subagent-dispatch.md.

Forbidden Behavior

• broad replanning by default
• reshaping the graph unless truly necessary
• hand-editing lifecycle state ad hoc
• claiming the current CLI has a persisted review runtime state
• claiming completion without review
• continuing blindly when blocked or feedback is clearly needed
• spawning subagents without bounded ownership
• parallelizing work that shares unstable assumptions or tight write conflicts
• letting subagents silently redefine the task graph
• treating major structural drift as a local execution detail
• verifying against stale task contracts after the trajectory has materially changed
• ignoring status, run, task inspect show, or task repair fix when runtime or readiness is unclear
• treating every discovered issue as a reason to reshape
• replacing a working user-owned harness with a Superplan-specific flow during execution
• rewriting or bypassing existing custom skills or scripts unless explicitly asked
• falling into read-only CLI exploration after the next execution step is already known
• repeatedly polling status or task inspect show without a concrete state, blocker, or handoff reason

Outputs

Expected output categories:

• task started
• task in progress
• implementation work started
• verification started for a named risk
• blocked with reason
• needs feedback
• ready for AC review
• runtime repaired
• localized re-shape required
• strategic re-route required
• execution cannot continue safely

Runtime summary should keep legible:

• what is running now
• what is verifying now
• what is blocked
• what is waiting for the user
• what changed in the trajectory
• what can run next
• which user-relevant decisions changed execution

Current CLI Loop

Use the runtime-aware CLI as the scheduler: