vs-shape-it
Use when the user says shape it, brainstorm, explore this idea, grill this, or wants to turn an idea into a buildable design.
- License 许可
- MIT
- 所属仓库
- vltansky/vs
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- 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.
02 资源文件 32
- 参考文档agents/openai.yaml84 B
- 脚本scripts/reject-step-map.mjs3.3 KB
- 脚本test/adr-first.static.eval.ts4.3 KB
- 脚本test/approve-handoff.static.eval.ts11.1 KB
- 脚本test/context-docs.static.eval.ts1.8 KB
- 脚本test/design-quality.static.eval.ts4.7 KB
- 参考文档test/fixtures/auto-update-project/.claude/settings.json227 B
- 参考文档test/fixtures/auto-update-project/adr/adopt-adrs-for-repo-level-decisions.md559 B
- 参考文档test/fixtures/auto-update-project/package.json199 B
- 参考文档test/fixtures/caching-project/docs/plan.md720 B
- 参考文档test/fixtures/caching-project/package.json142 B
- 脚本test/fixtures/caching-project/src/api.js582 B
- 参考文档test/fixtures/perf-project/package.json142 B
- 参考文档test/fixtures/ponytail-plan/package.json80 B
- 脚本test/fixtures/ponytail-plan/src/import-contacts.js106 B
- 参考文档test/fixtures/publishing-project/package.json171 B
- 参考文档test/fixtures/step-map/bad-no-map/chat.md89 B
- 参考文档test/fixtures/step-map/bag-of-words/chat.md109 B
- 参考文档test/fixtures/step-map/clean-map/chat.md442 B
- 参考文档test/fixtures/step-map/copy-phrases-skill.md205 B
- 参考文档test/fixtures/step-map/four-names-no-here/chat.md147 B
- 参考文档test/fixtures/step-map/headings-four-names/chat.md92 B
- 参考文档test/fixtures/step-map/slogan-only-skill.md135 B
- 参考文档test/fixtures/suggestion-project/package.json159 B
- 脚本test/interaction-cadence.static.eval.ts6.5 KB
- 脚本test/ponytail-composition.eval.ts2.4 KB
- 脚本test/research-and-pushback.static.eval.ts4.8 KB
- 脚本test/risk-first.static.eval.ts1.3 KB
- 脚本test/shape-it.eval.ts21.7 KB
- 脚本test/shape-it.history.eval.ts13.7 KB
- 脚本test/shape-it.real.eval.ts9.3 KB
- 脚本test/step-map.static.eval.ts4.0 KB
03 SKILL.md 正文
Shape It
Turn loose ideas and rough plans into approved, buildable designs. Keep the conversation short and decision-focused; the human makes strategic calls.
<HARD-GATE>
Shape-it itself never writes code. Until the user approves a READY or READY_WITH_RISKS close,
do NOT write code, scaffold projects, create GitHub issues, or start
implementation workers. After that approval, shape-it still does not
implement: it hands the approved spec to /vs-build-it, or stops or returns to
its caller, per the Approval table below. Planning-only research or critique subagents are
allowed for complex work. Output is questions, evidence, design, stress-test,
a decision record when one is warranted, a goal-ready execution blueprint,
and a closing /vs-eli5 HTMDX of the spec. Writing an ADR is a decision record, not implementation, and is allowed. The eli5 is a short review of the spec so the user can confirm it, not a replacement for the spec and not implementation.
</HARD-GATE>
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.
- Guided Explore: the user says
interview me,ask me questions,question me, orgrill meand wants to work through their own idea. Follow Explore, but use the adaptive interview cadence in the opening interaction. - Challenge: formed plan, spec, or RFC, or an explicit request to grill,
challenge, or stress-test the proposal itself. Delegate to
/vs-pushback; do not duplicate its scoring and verdict workflow here.Grill this planis Challenge;grill me — question meis Guided Explore.
If the initial route was wrong, pivot immediately.
If the shaped outcome is a vs skill eval contract, compose /vs-eval after
the spec is accepted — not during Explore.
All routes end in pushback. Explore and Guided Explore run it as the last step
of independent shaping, then the close-time eli5. Challenge hands the whole
session to pushback in interactive mode; pushback composes the close-time
/vs-eli5. Shape-it does not compose a second one.
For Explore, use the shared
context-docs.md protocol
for project language. Shape-it owns the question rounds, design, ADR outcome,
and any resolved glossary updates; do not open a separate context interview.
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.
Long-horizon shaping
Shape-it still owns work whose strategic decisions cannot be resolved reliably in one session. Treat this as long-horizon shaping, not a separate workflow.
Use the existing design spec as the durable source of truth. Create it during
independent shaping when necessary and mark it Status: SHAPING. Keep these
sections current alongside the normal design:
- Open decisions — unresolved strategic questions and their dependencies
- Evidence — paths and URLs that constrain those decisions
- Next decision — the single question the next shaping session should resolve
At a clean boundary, apply Phase Boundaries. Resume by loading the spec first, then only the evidence needed for its Next decision; do not reload the whole prior conversation. Keep open decisions out of implementation issues and do not start implementation until the Goal Contract is approved. Once the open decisions are resolved, continue with the normal spec approval and handoff.
Explore workflow
The default cadence is interaction -> independent -> interaction. Align while the user is present, do the substantive shaping without making them babysit the process, then bring back a complete recommendation for decision.
1. Opening interaction
Assume the user is available and engaged at the start. Read the sources they named and inspect only enough nearby context to avoid questions the repository can answer. Do not begin broad research or produce a near-final design before alignment.
Before asking the first question, resolve and read the applicable
CONTEXT-MAP.md/CONTEXT.md using the shared context-docs protocol, then use
its canonical language. Ask about unresolved strategic choices only; do not
ask the user to restate a term the glossary or nearby code already settles.
Discover the active workspace, repository, and existing artifacts from the host and current directory. Ask for an evidence location only when it cannot be discovered or accessed and choosing the wrong one would materially change the design; ordinary navigation is not a strategic question.
Opening is Alignment. When this phase starts, show the visual progress
checkpoint at 25%, with none yet for subskills and Goal Contract + Execution Strategy drafting for Output, per
communication.md.
Every Explore session crosses an explicit alignment checkpoint before independent shaping. In the default route, ask up to 3 high-leverage strategic questions in one round. Even when the direction sounds settled, ask one question about the least-supported expensive-to-reverse assumption instead of silently treating the agent's interpretation as alignment.
Skip the question only when the user explicitly asks for no questions, or the current conversation already contains explicit answers for the outcome, boundary, and proof of success. In that case, reflect those settled decisions in one short alignment statement before independent shaping. Repository facts and ordinary navigation never count as user alignment.
When choosing questions, use only the lenses that remain unresolved:
- Problem and outcome — what should change, for whom, and why it matters
- System boundary and ownership — where the responsibility belongs
- Kill criterion — what evidence would make this not worth building
Do not ask all three by rote or spend a slot on a lens the evidence already settles.
Guided Explore interview
Use this cadence only for Guided Explore. It is deliberately more interactive than the default batched checkpoint:
-
Start with a brief assessment of what is known, what remains undecided, and the likely decision areas. Show the visual checkpoint from
communication.md. Use this shape at every user-visible phase change:─── <TOPIC> ─── Progress: <25|50|75|100>% <█░░░|██░░|███░|████> <✓|→|○> Alignment: <concrete state> <✓|→|○> Shaping: <concrete state> <✓|→|○> Your input needed: <the decision, or "none"> <✓|→|○> Handoff: <concrete state> Subskills completed: </vs-* → concrete contribution; ...> or <none yet> Output: Goal Contract + Execution Strategy <drafting|ready|blocked>The percentage is the current phase ordinal: 25% Alignment, 50% Shaping, 75% Your input needed, and 100% Handoff. It is not confidence or a work estimate. Do not name session internals (compact, clear, or the session-action handoff). Do not show a time estimate, target question count, or an empty progress bar.
-
Ask up to 3 independent consequential strategic questions per round. Batch only questions whose answers do not depend on each other. Lead each with a Why tldr (one line: what the user loses if they pick wrong), then the recommended answer. Always include Drill (
eli5) as the last option. Compose/vs-eli5on that question's tradeoff only if they pick it. -
Branch after each round: choose the next round from its answers, skip decisions those answers settle, and inspect the code or named evidence yourself when a fact can answer the next question.
-
Accept
done,skip,back,?, andeli5.skipaccepts the stated reversible default for the current question;?defers it as an open decision;eli5drills this question's tradeoff with/vs-eli5and waits for A/B after;backrevisits the previous answer and updates dependent decisions. If the user saysdone, preserve remaining uncertainty as explicit open decisions with recommendations. -
Stop interviewing once outcome, boundary, and one expensive-to-reverse call are clear. Do not keep grilling until all expensive choices are clear. Everything else is a stated reversible default in the spec. Keep Why + Drill as the last option. Reflect the agreed mental model in no more than three bullets, then state the aligned model and enter the uninterrupted independent beat without another question. Do not start another question round after that expensive-to-reverse call.
-
Update progress only when a decision changes state. During alignment, show resolved and open decisions; do not turn progress into a fixed questionnaire.
Do not turn Guided Explore into a fixed questionnaire. Progress means resolved decisions, not a target question count. The user supplies priorities and trade-offs; the agent supplies facts, code reading, and recommendations.
For either cadence, render questions through the host's structured question
tool when available
(request_user_input in Codex, AskUserQuestion in Claude Code); see
internal-shared Structured questions. Fall
back to the Markdown format below otherwise. In Codex, when
request_user_input is listed, call it rather than rendering the fallback.
For the default batched checkpoint:
- 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 infer a reversible default later.
- Keep the question turn under about 60 words per question.
- State the decision in everyday language before presenting options. Make clear what changes for the user; do not make them decode architecture or workflow labels to answer.
- Every question has a Why tldr: one line, user-world stake if they pick
wrong. It is not a call to
/vs-tldr. - Every question ends with the same Drill option: compose
/vs-eli5on that question's tradeoff and open the html. Do not open it unless they pick Drill. In the text fallback it is alwaysD. Drill — /vs-eli5 this tradeoff. In the structured tool it is the last option, same label.1Doreli5drills that question, then wait for A/B/C. - Recommend a path for every choice; put it first and label it the default. In
the text fallback, make it option
A. - Accept batched replies like
1A, 2B; a bareAoryesaccepts every recommendation. - Infer tactical details and state safe defaults briefly.
- Spend one of the three questions on external research only when the design could proceed without it and the lookup would cost real time. When the need is clear, run it in the independent beat instead of asking.
Guided Explore calls the structured tool once per round with one to three independent questions, then waits for all answers. It uses the batched-reply shortcut and multi-question fallback below.
## Decisions needed
### 1. <short decision title>
**Why:** <one-line tldr of the user-world stake if they pick wrong>
**Recommended: A — <choice>** — <one-clause rationale>
- A. <choice> — <consequence>
- B. <choice> — <consequence>
- C. <choice> — <consequence>
- D. Drill — `/vs-eli5` this tradeoff
### 2. <short decision title>
...
Reply `A` to accept every recommendation, `1D` to drill question 1, or
specify changes such as `1B, 2A`.
2. Independent shaping
After the opening reply, assume the user may be away until the closing interaction. Research, design, challenge, and synthesize autonomously. Do not drip follow-up questions or pause at section-by-section gates. Resolve tactical uncertainty with explicit, reversible defaults. Preserve genuinely strategic uncertainty as an open decision with a recommendation and consequences, then continue every safe part of the design.
Autonomous is not silent. Per
../vs-internal-shared/references/communication.md,
this beat is Shaping. When the phase starts, emit the visual progress
checkpoint at 50%. Update Subskills completed with only finished /vs-*
skills, each paired with the result Shape It kept, and keep Output: Goal Contract + Execution Strategy drafting. Score
the checkpoint with skills/vs-shape-it/scripts/reject-step-map.mjs (identity
ee2e6aed87fd652c945d67a1e7a580bb65ffd23a01a12d7b2b79607ce9a4cdea;
exit 1 is a fail). Exclusive cases live under test/fixtures/step-map.
─── STASH CANVAS PILOT ───
Progress: 50% ██░░
✓ Alignment: pilot goal aligned
→ Shaping: scope and evidence in progress
○ Your input needed: none
○ Handoff: Goal Contract + Execution Strategy
Subskills completed: none yet
Output: Goal Contract + Execution Strategy drafting
Do not turn these into questions. They report state; they do not request input. Do not name session internals in the checkpoint. The topic and states above are examples; replace them with the current work.
Gather evidence
Read relevant repository docs, nearby code, screenshots, and prior artifacts
needed to test the aligned direction. Check
~/.vs/$PROJECT_ID/{pushback,specs,context,rfcs}/ when relevant, resolving
$PROJECT_ID per internal-shared.
When the topic has project-specific language, also read the applicable
CONTEXT.md or CONTEXT-MAP.md using
../vs-internal-shared/references/context-docs.md.
If a term resolves during this session, update the selected glossary inline
according to the shared context-docs protocol; do not create an empty context
file merely because context support was loaded.
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.
Architecture evidence
Before Design, load and follow
../vs-architect/SKILL.md in composed mode when all
of these are true:
- an existing implementation is in scope;
- the design changes module responsibilities, interfaces, seams, coupling, or consolidation;
- the recommendation depends on understanding current callers and tests;
- no current architect result already covers the scoped area.
Scope architect to the affected flow or package. It returns evidence and vetted candidates to shape-it; it does not open its standalone candidate-selection gate. Use the top candidate as evidence, preserve credible alternatives, and surface only strategic candidate choice through shape-it's normal interaction.
Skip architect for greenfield work, local implementation choices, and an already approved design or spec. A recorded design is the source of truth until the user requests a revision or implementation evidence invalidates it.
Research prior art
Repository evidence answers how this codebase works; it cannot tell you whether the approach is the one the ecosystem already settled. Decide once, early in the independent beat, whether an external research flow runs.
Run one without asking when the answer would change the recommendation and you are confident which lookup produces it:
- the design depends on an external system's real API, limits, or semantics
- the user named an external project, tool, standard, or spec
- the chosen approach has well-known prior art whose tradeoffs are already known
- a build-vs-adopt call hinges on what an existing library actually does
Pick the narrowest flow and follow its SKILL.md file:
../vs-octocode/SKILL.md for prior
art, ecosystem patterns, and landscape comparison;
../vs-rfc-research/SKILL.md when the decision
is RFC- or ADR-grade and needs code-cited evidence;
../vs-steal/SKILL.md for one named external repo.
Scope it to the specific design question, not the whole topic.
Offer it as an opening-round choice when it would cost real time and the design can proceed without it. Skip it, and say so in one clause, when named sources and repository evidence already settle the decision — external reading is not a default tax on every session.
Research is evidence, not authority. Cite what changed the design, and record a prior-art finding you deliberately rejected as a decision with its rationale.
Design
Load and follow ../vs-ponytail/SKILL.md in
composed mode while generating candidates, choosing the first slice, and
finalizing scope. Start with the first complete rung; do not present a larger
candidate unless evidence shows the smaller one cannot deliver the approved
outcome. Never reduce evidence, verification, safety, or an explicit
requirement.
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
- failure modes, degradation/recovery, and ownership when the design crosses a runtime or operational boundary
- 1-2 alternatives with concrete tradeoffs
- risks, success criteria, and verification
For a meaningful solution-size decision, include a compact ### Ponytail cut
with the smallest complete slice, machinery avoided, explicit deferrals, and
the evidence that makes the slice complete. Omit it when no machinery or scope
choice was made; do not manufacture a section for trivial wording work.
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.
Record the decision
The record precedes the implementation it governs, per Record repo-level decisions before implementation. Resolve the ADR question once, here, with a stated outcome. Silence is not an allowed outcome.
An ADR is warranted when the design settles a decision that is expensive to reverse and that future readers will ask "why did we do it this way" about: cross-cutting workflow or runtime behavior, a convention contributors and agents must follow, an enforcement or validation policy, or a build-vs-adopt call that locks in a dependency or integration boundary. It is not warranted for feature work, local refactors, or tactical implementation choices that a later session can change freely.
For an ADR connected to a context decision, also follow the context-document storage rules so an existing in-repo or per-user preference is not overridden. The glossary records vocabulary; the ADR records the durable trade-off.
When it is warranted, write adr/<slug>.md now, before the closing interaction:
- Follow the repo's existing ADR convention. Absent one, use
adr/at the repo root with a slug-only filename — lowercase, dash-separated, present-tense imperative, no numeric prefix. - Include Date, Context, Decision, Consequences, and the alternatives actually evaluated with the reason each was rejected. Carry over prior art you rejected during research; that rationale is intact now and expensive to reconstruct later.
- Leave it uncommitted and add no
Statusfield. Approval happens at PR merge. - Never edit a merged ADR. When this design changes an existing decision, add a new ADR that names the one it supersedes.
When the repo has no ADR surface and the decision qualifies, recommend
/vs-setup-adr in the closing interaction rather than inventing an ADR
convention the repo never adopted.
When no repo-level decision was settled, say so in one clause with the reason.
Either way, the Goal Contract's ADR line records the result.
Finalize the spec
Do not restart the interview. Synthesize the conversation and repository evidence into the design:
- Small work: the final 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>
- Evidence plan: <surface + route or command + state or fixture that will prove
the outcome, or OPEN DECISION when no surface exists today>
- ADR: <path(s) to the decision record(s) build-it must honor, or None — reason>
- Context: <glossary path(s) updated or read, or None — reason>
- Constraints and approvals: <hard boundaries and human gates>
The Evidence plan is what the user is really deciding: how the result will be judged. Name the concrete thing build-it will point a browser or a command at. "Tests pass" is a guardrail, not evidence of the outcome.
For interaction changes, put a small demo scenario table in that Evidence plan: scenario, shared route/fixture/viewport, action, expected Before/After, and the assertion that proves the result. Usually 3–4 scenarios cover the main flow and the relevant failure/retry, cancellation, or boundary case; use fewer for a small change. Map them to Success criteria, not a separate approval gate. This is a capture plan for build-it/ship-it, not permission to record or implement during shaping. Static changes need matched stills, not invented interactions.
If nothing today can prove the outcome, that is a strategic open decision — the
options are building a surface, accepting a weaker proof, or descoping. Carry it
into the closing interaction with a recommendation. Do not defer it to build-it
as a tactical detail; build-it will then head its handoff UNPROVEN.
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.
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.
Stress-test with pushback
Every explore session ends its independent beat by loading
../vs-pushback/SKILL.md and running its composed
mode over the finished design, Goal Contract, and execution strategy. There is
no size threshold: a design small enough to survive the grill costs one short
pass, and the sessions that skip it are the ones that needed it.
Run it last, once the design is whole. Grilling a half-formed design produces objections the remaining shaping would have answered anyway.
Composed mode is non-interactive by contract — it must not open question rounds
inside the independent beat. It answers its own dimensions from the design and
the evidence already gathered, records what the evidence cannot settle as
unresolved with severity, and returns Verdict, Score, and Top Pushback.
Then integrate before returning:
- fold supported findings into the design, spec, and Goal Contract rather than appending a critique section the user has to reconcile
- keep a finding you reject, with the reason it does not hold
- carry an unresolved high-severity finding, or any finding that exposes a strategic contradiction, into the closing interaction as a decision with a recommendation
Shape-it still owns synthesis, user communication, and the design. Pushback supplies the verdict, not the plan.
Self-review the design
Review the final integrated design, Goal Contract, any ADR, and execution strategy. Fix issues directly rather than handing editorial cleanup to the user:
- Placeholder scan — remove any TBD, TODO, placeholder, or incomplete section
- Internal consistency — align the architecture, Goal Contract, ADR, and execution strategy
- Scope check — keep one buildable outcome or decompose work that cannot share one contract
- Ambiguity check — choose one interpretation or surface a strategic open decision
Do not repeat the review after fixing these issues; continue to the closing interaction.
3. Closing interaction
Explore and Guided Explore only. Challenge does not compose /vs-eli5 here;
pushback does that close.
Cite ../vs-internal-shared/references/explanation-surfaces.md
only for chat TLDR vs artifact, not its opener. The close-time eli5 is required even when that
complexity test would keep the answer in chat: the user is confirming a spec.
On Explore and Guided Explore, always compose /vs-eli5 on the spec or plan, including
a NOT_READY close — the pictures should show the block. Do not skip the eli5
for a small or routine shape. The eli5 is a short picture review of that spec
so the user can confirm it. The Markdown spec, Goal Contract, and any ADR stay
the thing they approve and the machine source of truth; link them from the
eli5. Do not treat the eli5 as a replacement contract.
After /vs-eli5 returns Saved:, always produce the eli5 HTML and the chat
TLDR. Display: save the eli5 HTML and put its path (or “eli5 saved”) in close item 2 as a link; do not auto-open, and do not run open or xdg-open unless the user picked Drill mid-session or later asks to open the file.
Entering Your input needed is a phase change: emit the visual progress
checkpoint at 75%, then the close. Name the exact approval or rework decision,
list every completed /vs-* subskill with its concrete contribution (including
the /vs-eli5 review path and /vs-pushback verdict here), and set Output to
Goal Contract + Execution Strategy ready or blocked. The checkpoint is not
a fifth close item. After approval, emit the 100% Handoff checkpoint, then
follow the Approval table. On Build, write
Handoff: approved spec → /vs-build-it <spec path>. That checkpoint is a
bridge, not an end: build-it's first [1/7] line continues the same run. Do
not re-greet, re-summarize the design, or restart the map.
Chat is only this exclusive 4-item close, in this order:
- The first sentence is the TLDR returned by composed
/vs-eli5(two to four short lines): the recommendation in plain English and why it is the best fit. Do not write a second TLDR. - The eli5 file path (or “eli5 saved”).
- Verdict-honest Handoff. READY or READY_WITH_RISKS:
Handoff: Goal Contract ready | <N> open decisions(or the missing field). NOT_READY:Handoff: Goal Contract blocked — not ready, rework(or the missing field). Never writeGoal Contract readyon a NOT_READY close. - One
Your actionline. READY or READY_WITH_RISKS: approval. Required shape, by case:- READY: Reply
approveto start/vs-build-iton this spec, or request changes. - READY_WITH_RISKS: Reply
approveto accept <the main open risk, one clause> and start/vs-build-it, or request changes. - Spec or design only (the user asked for no implementation): Reply
approveto accept the spec, orbuildto start/vs-build-it. - NOT_READY: rework only — do not offer approve or
/vs-build-it.
- READY: Reply
Do not paste the Goal Contract, ADR, pushback report, execution blueprint, or
the Execution: block into chat. Those live in the linked files and the eli5.
Routing metadata does not replace or suppress the closing design.
Put the complete recommendation and all of the following in the linked files, not in chat:
- the complete recommendation, stress-test changes, and any ADR (path plus one-line decision, or one clause why none was warranted)
- unresolved strategic decisions, each with one recommended path and how alternatives change the outcome
- the pushback result as the state of the design, one compact sentence plus
surviving high and medium findings (
The design is ready to build, with one open rollout risk (READY_WITH_RISKS).) - the sharpest supported reason the recommendation can fail, with cause and user consequence; a generic risk label is not enough
- a
NOT_READYverdict is rework only: it blocks the approval gate. The spec and eli5 lead with the blocking finding. Your action is rework, not approve and not/vs-build-it. Offer interactive/vs-pushbackif they want to defend it in rounds - the smallest handoff that can execute the approved Goal Contract, default
/vs-build-it, plus the execution class below
Approval exists only for READY or READY_WITH_RISKS. Keep one approval request
in those cases. Ask for approval once, after the whole design, Goal Contract, any ADR, and any
execution blueprint are visible in those files. If the
composed pushback verdict is NOT_READY, skip the approval gate: Your action
is rework. If an unresolved strategic decision remains on a READY or
READY_WITH_RISKS close and each option is already shaped, combine it with
this gate: approve accepts the recommended option.
Approval
Approval can start an autonomous build, so the trigger is strict. Check the non-Build rows first: any non-Build row that matches wins over Build. Only when none matches, use a Build row.
| Situation | Outcome |
|---|---|
Direct Explore or Guided Explore run, READY, the user did not ask for spec or design only: the reply is approve (any case, punctuation ignored), or a bare acceptance such as approved, yes, or lgtm, with no edit, condition, question, or non-recommended pick |
Build: emit the 100% Handoff, then load and follow ../vs-build-it/SKILL.md on the approved spec path, with the Goal Contract as its contract |
| Direct Explore or Guided Explore run, READY_WITH_RISKS, the user did not ask for spec or design only: the same strict acceptance, to an approve line that named the risk | Build: the risk is now accepted. Emit the 100% Handoff, then load and follow ../vs-build-it/SKILL.md on the approved spec path |
The reply carries an edit, condition, or question, for example approve but rename X or looks good, one question |
Revise: treat it as a requested change. Revise the design, then close again. Do not build |
| The reply picks a non-recommended option on the combined decision gate | Revise: fold that pick into the design, then close again. Do not build |
| Ambiguous reply (you cannot tell acceptance from a change) | Ask: ask once which it is. Do not build |
| The user asked for a spec or design only, not implementation | Finalize: approve accepts the spec and stops. Do not build. A later build reply is a new /vs-build-it request |
| Composed run: a caller workflow loaded shape-it and is still running, waiting for the spec | Return: hand the approved spec path back to that caller. The caller owns the build-it handoff, so build-it never runs twice |
| NOT_READY close | Rework: no approve was offered. Revise, or offer interactive /vs-pushback |
| Challenge route | Return: /vs-pushback owns that close. Shape-it does not start build-it |
The host cannot resolve ../vs-build-it/SKILL.md |
Stop: tell the user to type /vs-build-it <spec path> and stop |
A caller that handed off and ended does not make the run composed. Examples:
/vs-architect handing the user to shape-it, or /vs-build-it stopping to
route a decision here (its architect step). That run is direct: a Build row
applies, with a fresh build-it run on the approved spec.
On Build, if shape-it owns a Codex planning goal, mark it complete before
loading build-it, so build-it's get_goal finds no conflicting active goal
(Codex Goal Integration).
On Build, the default session action is Continue. Apply
Phase Boundaries only on
its observable signals: if they choose Clear or Handoff (the spec is durable
and the shaping context is now a burden), end with
Next: /vs-build-it <spec path> and a one-clause reason. Never stop at a TLDR
that names /vs-build-it without that reason.
A Build approval authorizes /vs-build-it only. It does not authorize
/vs-to-issues, Codex tasks/threads, or other workers proposed in the
execution class below. Each needs its own explicit OK, and then build-it or
/vs-to-issues creates them, never shape-it. Build-it's own rules still
govern how it runs.
On READY or READY_WITH_RISKS only, default to the approved spec, then /vs-build-it.
On NOT_READY, skip that default. Extra coordination follows
the execution class written in the spec, not in chat:
- 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.
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>
Write that block in the spec. Do not print it in chat.
Confusion
When strategic signals conflict during the opening or closing interaction, name the conflict with recommended options. During independent shaping, record the conflict, use a clearly provisional recommendation where safe, and continue work that does not depend on it. Stop early only when no useful safe shaping can continue. Do not silently choose between materially different outcomes.
Verification
Before finishing, check:
- before approval, no implementation, issues, tasks/threads, or implementation workers were created
- the reply was matched to the Approval table, non-Build rows first; spec-only, composed, edited, ambiguous, and Challenge replies never reach build-it
- named sources and enough nearby evidence were read before asking answerable questions
- external research either ran with its finding cited, or was skipped with a stated reason
- pushback ran in composed mode over the finished design and returned a verdict and score, and its supported findings were folded into the design
- the cadence was opening interaction, uninterrupted independent shaping, then closing interaction
- READY or READY_WITH_RISKS: the design has one approval gate and a behavioral verification seam; NOT_READY has no approval gate
- the completed design passed placeholder, consistency, scope, and ambiguity review
- 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
- the Goal Contract names an Evidence plan, or marks it OPEN DECISION and surfaces it in the closing interaction
- the ADR question was resolved with a stated outcome: a drafted
adr/<slug>.mdnamed in the Goal Contract, or a one-clause reason none was warranted - resolved project vocabulary was written inline to the applicable glossary, or no context file was created because no term crystallised
CONTEXT.mdcontains vocabulary only, with no implementation detail or spec- 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
Before the final handoff, apply
Phase Boundaries. Keep
Next below as the semantic route; report a session action only when required
by that contract.
When the shaped design carries multiple options, risks, or non-trivial
topology, present it to the user as an HTMDX proposal page through
../vs-show-me/SKILL.md (the proposal shell) with a
short chat TLDR — not a wall of chat text. The machine-facing handoff for
build-it stays Markdown. When this run creates HTMDX, inherit the URL +
first-screen shot handoff from /vs-show-me. Pointer only.
Output style
Apply the shared output style to every user-facing message.
Workflow
Direct: on a Build approval (Approval table), continue into Next; otherwise emit Next only. Composed: return the approved spec to the caller.
Prev: idea, rough plan, or question
Next: /vs-build-it
Relevant: /vs-improve | /vs-eli5
04 同仓库更多 Skills
vs-write
Use when asked to write, rewrite, edit, tighten, simplify, or polish prose for clarity, or to put text in STE, ASD-STE100, or controlled language. Produces plain, direct, accessible copy without losing substance or precision.
vs-fake-verify
暂无简介
vs-fake-verify
暂无简介
vs-verify
Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS/WARN/FAIL status.
vs-fake-verify
暂无简介
vs-verify
Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS/WARN/FAIL status.