| name | vs-shape-it |
| description | Use when the user says shape it, brainstorm, explore this idea, grill this, or wants to turn an idea into a buildable design. |
Shape It
Turn loose ideas and rough plans into approved, buildable designs. Keep the
conversation short and decision-focused; the human makes strategic calls.
Do NOT write code, scaffold projects, create GitHub issues, or start
implementation workers. Planning-only research or critique subagents are
allowed for complex work. Output is questions, evidence, design, stress-test,
and a goal-ready execution blueprint.
Route the input
Infer the route; do not ask the user to choose a mode.
- Explore: vague idea, open question, or no chosen approach. This is the
default; follow the workflow below.
- Challenge: formed plan, spec, or RFC, or an explicit request to grill,
challenge, or stress-test. Delegate to
/vs-pushback; do not duplicate its
scoring and verdict workflow here.
If the initial route was wrong, pivot immediately.
When Codex goal tools are available, follow
Codex Goal Integration.
Shape-it owns only the planning goal, never the later implementation goal.
For work that may benefit from delegation, load and follow
Subagent Orchestration.
Explore workflow
1. Gather evidence
Read relevant repository docs, nearby code, screenshots, and prior artifacts
before asking anything they can answer. Check
~/.vs/$PROJECT_ID/{pushback,specs,context,rfcs}/ when relevant, resolving
$PROJECT_ID per internal-shared.
Start with sources the user named and the nearest relevant implementation. Do
not inventory the repo or launch broad research until a specific design question
requires it. Stop when more reading is unlikely to change the next decision.
For multi-domain or high-risk work, delegate only independent planning lanes,
such as one bounded evidence inventory and one fresh adversarial critique. The
parent keeps user alignment, decisions, synthesis, and goal ownership. Do not
delegate the interview or ask several agents to design the same whole solution.
2. Clarify once
If intent, constraints, success criteria, or an expensive-to-reverse choice is
still unclear, ask up to 3 strategic questions in one round. Otherwise state
the assumptions and continue without interviewing again.
- Render the round through the host's structured question tool when available
(
AskUserQuestion in Claude Code); see internal-shared
Structured questions. Fall back to the text format below otherwise.
- Batch only independent questions; every question in the round must be
answerable without the others' answers. If a question depends on an earlier
answer, state the dependency inline or save it for a rare second round.
- Keep the question turn under about 60 words per question.
- Recommend a path for every choice; make it option
A and the default.
- Accept batched replies like
1A, 2B; a bare A or yes accepts every
recommendation.
- Infer tactical details and state safe defaults briefly.
- After the reply, move to design unless a real contradiction remains.
Question 1 of N: ...
Recommendation: A
Options: A) [recommended default] B) ... C) ...
Question 2 of N (independent of Q1): ...
...
3. Design
Lead with the recommended approach and why. Keep the core chat design under
about 450 words, excluding a justified orchestration appendix, and include:
- the smallest valuable, deployable end-to-end slice
- scope and explicit non-goals
- terminology and system boundaries
- data/control flow and important interfaces
- 1-2 alternatives with concrete tradeoffs
- risks, success criteria, and verification
Do not make the first delivery absorb every useful capability discovered during
shaping. Separate what is required for the smallest complete outcome from later
reliability, scale, analytics, automation, and platform work. A larger first
slice needs evidence that the smaller slice cannot produce the approved outcome
or would create unacceptable risk.
The slice must advance the approved outcome beyond the confirmed baseline.
Re-auditing or hardening behavior that already works is not the first delivery
unless evidence shows that behavior is unreliable and correcting it is part of
the user's goal. When new value depends on user access or external ownership,
surface that dependency instead of silently substituting lower-value work.
When a cheap prototype would answer a costly design question, recommend
/vs-prototype. When a performance claim shapes the design, use /vs-perf to
define the metric and evaluator before calling it build-ready.
For an expensive-to-reverse repo-level decision, recommend an ADR. Follow the
repo convention, or suggest slug-only files under adr/ and /vs-setup-adr.
Name the decision, alternatives, and rationale so implementation can record it.
4. Stress-test alignment
For large, cross-domain, or expensive-to-reverse work, use a fresh planning
critic before final approval. Give it the proposed design, evidence paths, and
the exact uncertainties to attack; do not give it implementation ownership.
Integrate supported findings into the design. Ask the user again only when a
finding exposes a strategic contradiction or materially different outcome.
Use /vs-pushback for a formed proposal that needs the full interactive verdict
workflow. Shape-it still owns synthesis of an explore-session design.
5. Finalize the spec
Do not restart the interview. Synthesize the conversation and repository
evidence into the design:
- Small work: the approved chat design is enough.
- Medium or large work: write
~/.vs/$PROJECT_ID/specs/YYYY-MM-DD-<topic>-design.md.
- Include Problem, Solution, Terminology, Boundaries, Decisions, Testing,
Out of Scope, Risks, Success Criteria, Goal Contract, and Execution Strategy.
- In Testing, prefer the highest existing behavioral seam. Name relevant test
prior art; propose a new seam only when existing seams cannot prove success.
The Goal Contract is the stable handoff from shaping to building:
## Goal Contract
- Implementation objective: <one observable outcome for /vs-build-it>
- Scope: <surfaces, workflows, files, or systems>
- Success criteria: <observable completion conditions>
- Verification: <tests, runtime evidence, CI, review, or acceptance checks>
- Constraints and approvals: <hard boundaries and human gates>
Do not describe activities such as "implement the plan" as the objective. State
the achieved product or system outcome. A build agent should be able to create
or reuse its implementation goal from this section without reinterpreting the
conversation.
6. Design the execution strategy
Order work by what can invalidate or block delivery, not by architectural
layering:
- Surface strategic decisions, user-provided access, credentials, approvals,
and external ownership needed for proof before broad internal work.
- Run the cheapest safe test of the assumption most likely to invalidate or
reorder the design.
- Deliver the smallest deployable vertical slice across the real integration
boundary.
- Deepen reliability, scale, and optional capabilities only after that slice
is observable.
"Risk first" means retire delivery uncertainty early; it does not mean build
the largest defensive subsystem first. An inventory or foundation is an early
workstream only when its result changes a decision or unblocks the vertical
slice.
Every design names its execution class:
- Direct: one parent, one session, tightly coupled work. No issues or
workers. This is the default for small work.
- Orchestrated: multiple independent domains, more than one session, risky
evidence collection, or durable coordination. Include the blueprint below.
For orchestrated work, make the execution plan runnable rather than saying only
"use agents" or "parallelize":
- Choose the source of truth. Use the spec alone for one durable orchestrator;
add GitHub issues when work must be independently claimed, reviewed, or
resumed by different people/sessions. Issues describe ready work, not open
product decisions.
- Choose concrete host primitives. Prefer subagents for bounded internal work
under one orchestrator. Recommend Codex tasks/threads for durable user-visible
ownership or long-running independent work; recommend Claude Code subagents
in Claude Code. Do not invent a primitive the host does not provide.
- Define workstreams with stable IDs. For each, name its outcome, owner
primitive, reasoning effort, inputs, outputs, dependencies, write scope, and
verification. Use low effort for deterministic inventory, medium for scoped
implementation, and high or xhigh for ambiguous architecture, integration,
security, or independent criticism. Name a specific model only when the host
supports it and the choice materially helps.
- Arrange waves. Parallelize only work with stable inputs and disjoint write
scopes. Put foundations, integration, approval, and final verification behind
explicit sequential merge gates. Fresh critics should run after evidence is
normalized so they do not inherit worker assumptions.
- Include copyable worker briefs for every delegated lane: objective, exact
scope, evidence paths, constraints, expected return shape, and stop
conditions. The parent owns integration, user communication, goal state, and
final verification.
- Render a Mermaid flowchart when there are at least three workstreams or two
execution waves. Show parallel branches, merge gates, approval gates, and the
final verification/handoff path.
Use this compact table in the spec:
| ID | Outcome | Primitive | Effort | Inputs | Output | Depends on | Write scope | Verification |
|---|---|---|---|---|---|---|---|---|
The blueprint is a plan, not authorization. Do not create the issues, tasks,
threads, or implementation workers during shape-it.
7. Approve and hand off
Ask for approval once, after the whole design, Goal Contract, and any execution
blueprint are visible. Approval means the artifact is ready for /vs-build-it;
it does not itself start implementation.
Recommend the smallest handoff that can execute the approved Goal Contract.
Default to the approved design or spec, then /vs-build-it. Extra coordination
must follow the execution class and blueprint above:
- Durability: propose issues when work spans sessions or people, needs a
shared dependency graph, or must survive chat context. Distinguish unresolved
decision issues from ready-to-build implementation issues; route only the
latter to
/vs-to-issues.
- Parallelism: propose host-native workers only for independent, bounded
lanes. In Codex, prefer subagents under one orchestrator; propose tasks/threads
for durable user-visible ownership. In Claude Code, propose subagents. If the
host has no parallel primitive, recommend sequential execution. Name the
concrete primitive; do not stop at generic “sessions,” “lanes,” or “agents.”
- Both: issues remain the source of truth; each worker references one issue.
- Multi-milestone: when the spec has several milestones expected to span
hours or days and surface new facts, recommend
/vs-orchestrate. It seeds a
living GOALS.md from this spec's Goal Contract and Execution Strategy and
drives one milestone at a time. The spec stays frozen; GOALS.md tracks the
changing state.
Execution: direct | orchestrated — <why>
Source of truth: spec | spec + GitHub issues — <why>
Runtime: parent only | parent + subagents | Codex tasks/threads | Claude subagents — <why>
Next: /vs-build-it with implementation objective: <objective>
(or /vs-orchestrate when the spec is multi-milestone)
Confusion
When strategic signals conflict, stop and name the conflict with recommended
options. Do not silently choose between materially different outcomes.
Verification
Before finishing, check:
- no implementation, issues, tasks/threads, or implementation workers were created
- evidence was read before asking answerable questions
- the design has one approval gate and a behavioral verification seam
- the first delivery is the smallest complete vertical slice, with later
capabilities explicitly deferred
- the first delivery advances the approved outcome beyond the confirmed baseline
- user-dependent blockers and plan-invalidating assumptions are tested before
broad internal foundations
- the Goal Contract states an observable outcome, scope, success, and proof
- unresolved strategic ambiguity is explicit
- direct work has no coordination overhead
- orchestrated work has bounded workstreams, effort, dependencies, merge gates,
worker briefs, and a diagram when the topology is non-trivial
- the handoff is runnable by build-it without relying on hidden chat context
Workflow
Direct: emit Next only. Composed: return to caller.
Prev: idea, rough plan, or question
Next: /vs-build-it
Relevant: /vs-improve
