superplan-md/superplan-plugin/superplan-shape

Shape Work

Overview

Create the minimum durable artifact structure and execution trajectory that preserves visibility, verification quality, and bounded execution.

This skill is not a task generator. It is a trajectory shaper.

Its job is to shape work so the agent can move with bounded autonomy while staying aligned to the user's real expectations. It must not collapse graph-shaped work into a single task merely because one agent could carry it alone.

Phase Ownership Rule

This skill owns artifact creation and execution trajectory, not open-ended analysis.

• shape the minimum durable structure that makes the next execution move safe
• choose the proof path before broad implementation starts
• once the executable frontier is clear, stop shaping and hand to execution

Trigger

Use when:

• superplan-route has decided Superplan should engage
• the work needs durable structure created now
• the next step is to author plan, spec, or task artifacts proportional to the work
• the system must decide how much of the work is shapeable now versus discovery-driven
• the system must choose a verification loop before execution begins

Stay Out

Do not shape work when:

• superplan-route decided to stay out
• execution is already fully shaped
• the request was already answered directly
• creating artifacts would add no value

Inputs And Assumptions

Inputs:

• routing decision and chosen depth
• user request and raw narrative when available
• repo state
• current .superplan/ artifacts if any
• workspace context when available
• existing verification loops
• existing user-owned harnesses, scripts, custom skills, and workflows
• recent decision log entries when relevant
• known gotchas when relevant

Assumptions:

• depth determines how much structure to create
• not all work is fully deterministic at shaping time
• some work should be represented as investigation, prototype, or decision-gate work before deeper decomposition
• the right shaping output is often a trajectory, not a frozen perfect plan
• shaping should stop once the minimum useful artifact set and next executable frontier are clear
• multi-step work means work with 3 or more distinct steps, or work where sequencing across files or components matters; do not rationalize 3-step work as "only two steps" to skip graph shaping
• dense PRDs, JTBD dumps, implementation checklists, or multi-surface requests should default to multiple tracked tasks unless they truly collapse to one bounded executable unit
• if different parts of the work need different acceptance checks, they should usually not share one task contract
• when useful workspace or global skills already exist for planning, brainstorming, review, debugging, or verification, shaping should route execution toward them instead of inventing an ad hoc loop

Hard Shaping Triggers

Shape multiple tracked tasks when any of the following are true:

• the request has 3 or more distinct deliverables, surfaces, or verification concerns
• parallelization would be useful
• different files or components can be owned safely by different workers
• different acceptance checks apply to different parts of the work
• one task would reduce visibility into progress, blockers, or verification quality

Anti-collapse rules:

• do not flatten multi-surface work into one task merely because one agent can personally execute it
• do not use one task when doing so would hide sequencing, parallel-safe work, or different reviewer evidence
• if the graph split feels optional but would materially improve delegation or verification, make the split

Artifact Distinction Rule

Keep these layers distinct when the distinction adds clarity:

• graph truth: what work exists, how it depends, and what is ready now
• task-contract truth: what each bounded task means and what done requires
• runtime truth: what is happening now, what is blocked, and what is waiting on feedback

Artifact roles:

• specs/*.md capture behavior, constraints, interfaces, and acceptance intent
• plan.md captures implementation path, sequencing, and execution strategy
• graph/index artifacts capture dependency structure and workstreams
• task contracts capture bounded executable units

Canonical rule:

• specs constrain truth
• plans constrain trajectory
• task contracts, acceptance criteria, and checks constrain reality

Ownership rule:

• graph truth canonically owns task membership, workstream, depends_on_all, depends_on_any, and exclusive_group
• task-contract truth canonically owns meaning, context, acceptance criteria, verification, and expected evidence
• runtime truth canonically owns active, blocked, feedback, and event state

Once graph truth exists, do not use task files as the real owner of dependency edges or workstream membership.

Do not force all artifacts to exist for every request.

CLI Alignment Now

Align shaping to the CLI that exists today, not only to future command ideas.

Product target:

• changes/<slug>/tasks.md is the human-readable graph/index surface
• changes/<slug>/tasks/T-xxx.md are the executable task contracts
• for very large changes, tasks.md may remain the root graph/index while delegating task-entry churn into graph shard files

Current CLI reality:

• superplan init --yes --json ensures the global Superplan root exists under ~/.config/superplan/ and installs any needed repo-local agent instructions
• superplan context bootstrap --json creates missing durable workspace context entrypoints
• superplan context status --json reports missing durable workspace context entrypoints
• superplan change new <change-slug> --json scaffolds a tracked change root plus change-scoped plan/spec surfaces
• superplan change plan set <change-slug> --stdin --json writes the change plan
• superplan change spec set <change-slug> --name <spec-slug> --stdin --json writes a change-scoped spec
• superplan change task add <change-slug> --title "..." --json adds graph truth and scaffolds the task contract in one CLI-owned write
• superplan validate <change-slug> --json validates tasks.md, graph diagnostics, and graph/task-contract consistency
• superplan task scaffold new <change-slug> --task-id <task_id> --json scaffolds one graph-declared task contract without mutating tasks.md
• superplan task scaffold batch <change-slug> --stdin --json scaffolds multiple graph-declared task contracts from JSON stdin without mutating tasks.md
• superplan parse [path] --json parses task contract files and overlays dependency truth from the graph
• superplan status --json summarizes the ready frontier from task files plus runtime state
• superplan task inspect show <task_ref> --json explains one task's current readiness in detail
• superplan doctor --json checks setup, overlay, and workspace-shape health

Therefore:

• for tracked work, define plans, specs, graph tasks, and workspace memory through CLI commands instead of editing Superplan state files directly
• when Superplan is staying out, do not create graph artifacts
• manual creation of anything under the shared Superplan project state root is off limits; from the repo root the CLI may surface those paths as .superplan/changes/<slug>/...
• use superplan change new --single-task or repeated superplan change task add calls to define tracked work quickly and correctly
• keep dependency truth in the CLI-owned change graph and task-contract truth in the CLI-owned task files
• choose current CLI validation commands explicitly during shaping
• distinguish current CLI commands from future CLI hooks

See references/cli-authoring-now.md.

Task Authoring Rule

Manual creation of files under the shared Superplan project state root is off limits.

Agents should spend their shaping effort deciding what tracked work exists, then use CLI commands that place artifacts correctly:

• superplan change new <change-slug> --single-task "..." --json for the one-task fast path
• superplan change task add <change-slug> --title "..." ... --json for additional tracked tasks
• superplan change plan set <change-slug> --stdin --json for change plans
• superplan change spec set <change-slug> --name <spec-slug> --stdin --json for change specs
• prefer CLI-created task fronts that make parallel-safe delegation obvious instead of relying on one overloaded task contract

Prefer these commands because they are the fastest way to stay helpful without teaching the model bad .superplan editing habits.

Current Contract Gap

The CLI now validates and consumes the root graph contract, but the full product shape is still ahead of the runtime in a few places.

Today the CLI validates and executes:

• changes/<slug>/tasks.md as graph truth for task membership and dependency edges
• task-contract markdown with frontmatter such as task_id, change_id, title, status, and priority
• Description
• Acceptance Criteria
• runtime state such as in_progress, in_review, done, blocked, and needs_feedback

It does not yet fully execute every future graph/program feature:

• root graph plus shard scaling for very large graphs
• workstream-aware runtime behavior
• exclusive_group runtime semantics beyond structural validation
• richer task-contract metadata such as context, assignee, date, or spec linkage
• deeper plan/spec-driven orchestration

Shaping should stay honest about this gap.

• do not describe the current CLI as if every future artifact layer is already enforced
• do shape work toward the intended contract when the product direction depends on it
• when the contract gap itself is the blocker, call it out explicitly as CLI debt rather than hiding it in vague shaping prose

Hard Contract Authoring Rule

When shaping tracked work, follow references/graph-contract-authoring.md.

Core rule:

• if Superplan is staying out, do not create graph artifacts
• if Superplan is engaged and the work is being tracked, create a root changes/<slug>/tasks.md

That includes:

• tracked direct work
• tracked task work
• tracked slice work
• tracked program work

For tiny tracked work, keep the graph minimal:

• one root tasks.md
• one task entry
• one superplan task scaffold new task contract shell
• no explicit workstream grouping unless grouping materially helps

For large tracked work, shape the graph according to the hard contract:

• required root sections
• canonical IDs
• graph-only ownership for edges and workstream membership
• required task-file sections
• invariants and diagnostic risks considered during shaping
• root-plus-shard structure once scale justifies it

Do not author "graph-like" markdown that ignores the contract shape.

CLI Discipline

Shaping is not permission to explore the CLI surface.

• use the current CLI contract already listed in this skill instead of probing adjacent commands
• do not call --help or overlapping authoring or diagnostic commands when change new, task scaffold new, task scaffold batch, parse, status, task inspect show, or doctor already cover the need
• use superplan parse for task validity, superplan status --json for frontier checks, superplan task inspect show <task_ref> --json for one task detail, and superplan doctor --json when install, workspace artifact, or task-state health is in doubt
• once the needed authoring or validation command is known, run it instead of exploring alternatives

User Communication

Keep shaping internals out of routine user updates.