superplan-md/superplan-plugin/superplan-entry

Using Superplan

Overview

Universal outer workflow layer for Superplan. Internal category: workflow-control / execution-orchestration.

This skill replaces the entry discipline that using-superpowers used to provide.

Keep it small, but not permissive. Its job is to decide whether Superplan should meaningfully participate, whether readiness is missing, and which workflow phase owns the next responsibility.

If there is a meaningful chance that the request is repo work, use this skill before implementation, broad repo exploration, or clarifying questions.

Fast Trigger Rule

Treat this as an early trigger, not a late fallback.

• if there is even a modest chance the request is repo work, load this skill first
• do not wait for "proof" that the work is complex before routing
• do not keep the work inside superplan-entry once a narrower phase owner is clear

The value of this skill is early discrimination, not broad control.

Subagent Guard

If you were dispatched as a bounded subagent to execute, investigate, or verify a specific task, skip this skill.

Do not rerun top-level Superplan entry routing from inside a task-owned subagent unless the assignment explicitly says to reevaluate engagement.

Instruction Priority

Follow this order:

1. direct user instructions and repo instructions such as AGENTS.md, CLAUDE.md, or equivalent host guidance
2. superplan-entry entry discipline
3. generic default behavior

If a repo instruction conflicts with a default Superplan habit, obey the user or repo instruction.

Mandatory Discipline

Treat entry routing as mandatory first-contact discipline, not optional advice.

• do not start implementing first and promise to structure later
• do not start broad repo exploration first and claim routing can happen after
• do not ask clarifying questions first when the real first question is whether Superplan should engage
• do not rationalize that a dense request is "probably just one task" without checking
• do not let "smallest useful depth" become a reason to skip an explicit route result
• do not begin execution for newly requested repo work until the route and shape chain is complete

Rationalizations that mean stop and use this skill:

• "This is probably straightforward."
• "I'll inspect a few files first."
• "I'll just ask one clarifying question."
• "I already know this repo."
• "The user asked for code, not process."
• "The skill description is broad, so I can skip it."
• "I'll know whether this is repo work after a quick look."
• "This probably stays lightweight, so routing can wait."

When repo work is in play, entry discipline outranks generic default behavior unless the user or repo explicitly says otherwise.

Workspace Precedence

Inspect the repo first before suggesting generic Superplan helpers.

Prefer the workspace's current harnesses, scripts, custom skills, and repo-native workflows when they already provide a better path.

Use Superplan to coordinate and supervise that setup, not to replace it.

Do not modify or outrank a working user-owned workflow unless the user explicitly asks.

User Communication

Keep workflow control language internal.

• This skill runs in control-plane mode.
• do not narrate skill selection, routing decisions, phase names, or command-by-command orchestration to the user
• do not send meta progress updates such as "I'm using superplan-entry", "I'm shaping the change now", or activity logs like "Explored 5 files"
• progress updates should focus on user-visible value: what is being changed, what risk is being checked, what decision matters, or what blocker affects the user
• mention a command, artifact, or workflow phase only when it directly explains a user-facing decision, blocker, or requested detail
• when in doubt, prefer project thoughts over process thoughts
• if the user needs detailed options, recommendation, trade-offs, or execution path, switch to the planning owner instead of expanding control-plane narration here

CLI Discipline

Entry routing is not permission to explore the CLI surface.

• once the current intent is known, use the canonical command path already named in this skill
• do not call --help, neighboring subcommands, or diagnostic commands just to orient yourself when the correct command is already listed
• use superplan task inspect show <task_ref> --json only when one task's detailed readiness is actually needed
• use superplan doctor --json only for setup or install uncertainty, not normal routing
• once the needed CLI state is known, stop polling and route or act

Session Focus Discipline

Session-local routing depends on a stable per-chat SUPERPLAN_SESSION_ID.

• strongest path: let the host startup hook export SUPERPLAN_SESSION_ID for you and preserve it on every Superplan CLI command in this chat
• fallback path: if startup context gives you a Superplan session token but the host did not auto-export it, prefix every Superplan CLI command with SUPERPLAN_SESSION_ID=<that token>
• workflow-only hosts may not have a startup hook at all; in that case mint one stable chat-local token before the first Superplan CLI command and reuse it for the rest of the chat
• do not silently switch to a different session token mid-chat unless the user explicitly moves this chat onto another session
• explicit task refs such as superplan run <task_ref> --json may cross sessions on purpose; bare superplan run --json should stay bound to the current chat token
• when the user starts unrelated work in the same chat, use superplan run --fresh --json to bypass saved session focus instead of silently resuming the old task

Trigger

Use when:

• Superplan is installed or expected in the current host environment
• the request may involve meaningful repo work
• the user asks for structured work, execution help, tracking, visibility, or durable context
• the system must decide whether Superplan adds value before deeper workflow work begins
• the request may refer to already shaped work that should resume or be reviewed rather than routed from scratch

In practice, this is the default entry layer for repo work in this host.

For dense requirement dumps, packed queries, JTBD lists, or multi-constraint briefs, assume this skill applies unless there is a strong reason to stay out. For new repo work with open structure, execution cannot begin until superplan-route has produced an explicit depth decision and superplan-shape has produced the initial executable frontier.

Specific-Owner Rule

As soon as the next owning phase is clear, hand off.

• use superplan-route for engagement and depth decisions
• use superplan-context when missing durable context is the real blocker
• use superplan-review when completion authority is the real need
• use superplan-execute when tracked work already exists and the question is how to move it

Do not let superplan-entry become a long-lived umbrella once the specific next owner is obvious.

Stay Out

Stay conversational and skip task creation entirely when:

• the user wants a simple explanation or answer
• no durable artifact would help
• no visibility or supervision value would be created
• no reusable context would be captured
• the request is casual, ephemeral, or already fully satisfied
• the work touches exactly one file and requires no decisions — a single-file edit that is verifiable by inspection (e.g. fix a typo, bump a version number) is the only repo-work exception to the task creation mandate

The one-file/no-decisions carve-out is narrow and intentional. If there is any doubt about whether a decision is involved, assume task creation is required.

If Superplan stays out, answer directly and do not create workflow artifacts.

Inputs And Assumptions

Inputs:

• user request
• current repository and working directory
• whether Superplan appears active in this repo or host
• whether setup, init, and durable context appear present
• whether shared Superplan project state already exists, either as a repo-root .superplan/... display path or under ~/.config/superplan/project-<name>-<hash>/
• whether useful workspace context exists already
• whether existing task or runtime artifacts suggest the work is already in a later workflow phase

Assumptions:

• users should not need to think about which skill comes next
• host environments may auto-trigger this skill
• some hosts only provide skill discovery rather than true startup bootstrap, so this skill must be triggerable from natural repo-work requests
• agents should not need to choose between multiple overlapping commands for the same intent
• entry routing should usually resolve without CLI command-surface exploration
• Superplan should improve the workflow, not hijack it

Allowed Actions

• inspect the repo briefly for readiness and context
• inspect repo-native workflows, scripts, harnesses, and custom skills before suggesting generic Superplan helpers
• inspect whether work is already shaped and should resume in a later phase
• decide whether to stay out or continue
• run the minimum readiness command needed to make engagement possible
• route to superplan-route
• route to superplan-context when missing context is the real blocker
• route to superplan-execute when tracked work is already shaped and should move forward
• route to superplan-review when the real request is completion authority
• run repo-local init automatically when the CLI exists and Superplan engagement is warranted
• give brief readiness guidance only when the CLI itself is missing or a required readiness command fails

Current CLI Loop

When Superplan is active in a repo, prefer the CLI as the execution control plane.

Common commands: