@seanmars/tospec 0.11.0 → 0.12.0

package/dist/core/templates/workflows/archive.js

@@ -38,9 +38,7 @@ Either way, the CLI then: re-validates the delta specs (blocking), checks tasks/
 **Guardrails — explicit and non-negotiable**
 - Judge whether a sync is warranted before archiving; only ask the user when the change has spec deltas — and honor a "no" (archive still proceeds, just without \`--require-sync\`)
 - Only pass \`--require-sync\` when \`tospec-sync\` actually produced a passing \`sync-report.md\` this run
-- **Never** construct an archive directory name yourself (the \`yyyyMMdd_HHmmss-<name>\` timestamp is generated by \`tospec archive\`'s internals — you have no way to reproduce it correctly, and guessing risks a collision or a wrong sort order)
-- **Never** create the archive directory yourself
-- **Never** manually move, copy, or rename the change directory
+- **\`tospec archive\` owns the archive directory** — it generates the \`yyyyMMdd_HHmmss-<name>\` name and moves the change there. Let the command do it: the timestamp comes from internals you cannot reproduce, so a hand-built name risks a collision or a wrong sort order
 - If \`tospec archive\` reports a validation failure or asks for confirmation on incomplete tasks, resolve the underlying issue (or explicitly confirm with the user) — do not route around it with manual file operations
 
 **Output**
@@ -49,7 +47,7 @@ Report the archived name and path from \`tospec archive\`'s output, whether a sy
 export function getTospecArchiveSkillTemplate() {
     return {
         name: 'tospec-archive',
-        description: 'Finish and archive a completed change: confirm apply\'s verify was clean, judge whether a spec/code sync is needed (asking the user first when it is), then run the one true tospec archive command. Use when the user wants to finalize an implemented change — never to manually move change directories or invent archive folder names.',
+        description: 'Finish and archive a completed tospec change via `tospec archive`, deciding first whether a spec/code sync is needed. Use when the user wants to finalize an implemented change.',
         instructions: `Finish a completed change: confirm verify (done in apply), decide about sync (run \`tospec-sync\` if warranted and the user agrees), then \`tospec archive\` — the only path to a merged, archived change.
 
 **Input**: The user's request should name the change to archive.
@@ -57,7 +55,7 @@ export function getTospecArchiveSkillTemplate() {
 ${ARCHIVE_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
+        metadata: { author: 'tospec' },
         allowedTools: ['Bash(tospec:*)', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }

package/dist/core/templates/workflows/archive.js.map

@@ -1 +1 @@
-{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/archive.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sJA+CiI,CAAC;AAEvJ,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,4UAA4U;QACzV,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,oGAAoG;QACjH,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QAC7B,OAAO,EAAE;;;;EAIX,YAAY,EAAE;KACb,CAAC;AACJ,CAAC"}
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/archive.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sJA6CiI,CAAC;AAEvJ,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,kLAAkL;QAC/L,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,oGAAoG;QACjH,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QAC7B,OAAO,EAAE;;;;EAIX,YAAY,EAAE;KACb,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/decision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/decision.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA8ClE,wBAAgB,8BAA8B,IAAI,aAAa,CAe9D;AAED,wBAAgB,gCAAgC,IAAI,eAAe,CAYlE"}
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/decision.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAiDlE,wBAAgB,8BAA8B,IAAI,aAAa,CAe9D;AAED,wBAAgB,gCAAgC,IAAI,eAAe,CAYlE"}

package/dist/core/templates/workflows/decision.js

@@ -1,3 +1,4 @@
+import { nextStepLabelRule } from '../fragments/next-step.js';
 const DECISION_BODY = `Capture a decision that has already been made or is ready to be adopted — the reasoning, the alternatives weighed, and what it affects. A decision left only in chat is a decision that gets re-litigated next week.
 
 **Steps**
@@ -14,15 +15,18 @@ const DECISION_BODY = `Capture a decision that has already been made or is ready
    \`\`\`
    Derive a kebab-case \`<topic>\` from the subject. The CLI produces both files: it writes \`tospec/decisions/<yyyyMMdd_HHmmss>-<topic>.md\` from its template (Status/Date/title pre-filled) and appends a row to \`tospec/decisions/index.md\` (seeding that ledger on first use). **The CLI owns the dated filename and the index — never create/rename decision files or hand-edit \`index.md\` yourself.** Use \`--status accepted\` if already agreed, or \`--status superseded\` (and name the successor) when replacing an older decision; pass \`--date\` only to backfill a past decision.
 
-4. **Fill the six sections**
-   Open the created file and complete every section:
+4. **Fill the sections**
+   Open the created file. Six sections are required — they are the structure the schema validates against:
    - **Status** — proposed / accepted / superseded (+ Date); if superseded, name the decision that replaces it.
    - **Context** — the situation and forces that made this decision necessary.
    - **Decision** — what was chosen, the canonical terms, and why this over the alternatives.
    - **Impact** — the modules / APIs / docs / tests this touches.
    - **Alternatives** — each option considered, its trade-offs, and the conclusion.
    - **Follow-up** — the follow-up implementation items, phased if useful.
-   - **Decision Process** (optional) — the key questions you asked and the user's answers that shaped this decision. Format each pair as a \`**Q:** question\` line followed by the answer in the next paragraph, one pair per block. Summarize each Q&A; don't paste a full transcript. Omit the section if there was no interactive discussion.
+
+   The template carries two more that are optional:
+   - **Decision Process** — the key questions you asked and the user's answers that shaped this decision. Format each pair as a \`**Q:** question\` line followed by the answer in the next paragraph, one pair per block. Summarize each Q&A; don't paste a full transcript. Omit the section entirely if there was no interactive discussion.
+   - **Related Changes** — leave it empty. It fills in later, as changes link back via \`tospec new change --decisions\`.
 
 5. **Verify**
    \`\`\`bash
@@ -34,17 +38,16 @@ const DECISION_BODY = `Capture a decision that has already been made or is ready
 
 Summarize the decision, its status, and the follow-up work. If it supersedes an older decision, state which one and flip that older file's Status to \`superseded\`. Report the created filename explicitly — when a change later implements this decision, that filename is what \`tospec new change --decisions\` records to link the change back here (the file's optional \`## Related Changes\` section can list those changes in return).
 
-Then point at the next step. When you put these options to the user, write each label from the decision you just recorded — a short, conversational phrase naming the concrete next action — then append the fixed action keyword in parentheses (\`(update)\`, \`(propose)\`/\`(issue)\`); the words before it must describe *this* action in *this* context, never a canned phrase, and never the raw \`tospec-*\` skill name. If the decision came out of grilling or exploring an **existing** change, offer **(update)** via \`tospec-update\` to fold it into that change's artifacts; if no change exists yet, offer **(propose)** / **(issue)** via \`tospec-propose\`/\`tospec-issue\` and carry the filename into \`--decisions\`.
+Then point at the next step. ${nextStepLabelRule('the decision you just recorded', '\`(update)\`, \`(propose)\`/\`(issue)\`')} If the decision came out of grilling or exploring an **existing** change, offer **(update)** via \`tospec-update\` to fold it into that change's artifacts; if no change exists yet, offer **(propose)** / **(issue)** via \`tospec-propose\`/\`tospec-issue\` and carry the filename into \`--decisions\`.
 
 **Guardrails**
 - The decision file, its date-prefixed filename, and the ledger row are all CLI-generated — pass \`--summary\`, and never create/rename decision files or hand-edit \`index.md\` yourself; only edit the decision file's section contents
 - Don't record a decision whose rationale or alternatives you can't state — clarify with the user first
-- \`superseded\` must name its successor; the superseded record's Status must be updated too
-- Keep the six required sections — they are the structure the schema validates against; Decision Process is an optional seventh for the Q&A trail (each pair starts with a \`**Q:**\` line, answer in the next paragraph)`;
+- \`superseded\` must name its successor; the superseded record's Status must be updated too`;
 export function getTospecDecisionSkillTemplate() {
     return {
         name: 'tospec-decision',
-        description: 'Record an architecture decision as a permanent ADR (dated decision file + derived index). Use when a design/architecture choice has been made or is ready to adopt and should be documented with its rationale, alternatives, and impact instead of left in chat.',
+        description: 'Record an architecture decision as a permanent ADR. Use when a design/architecture choice has been made or is ready to adopt and should be documented with its rationale, alternatives, and impact instead of left in chat.',
         instructions: `Turn a made (or ready-to-adopt) decision into a permanent ADR record via the \`tospec decision\` command.
 
 **Input**: The user's request should describe the decision and, ideally, the reasoning and the alternatives that were considered.
@@ -52,7 +55,7 @@ export function getTospecDecisionSkillTemplate() {
 ${DECISION_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
+        metadata: { author: 'tospec' },
         allowedTools: ['Bash(tospec:*)', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }

package/dist/core/templates/workflows/decision.js.map

@@ -1 +1 @@
-{"version":3,"file":"decision.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/decision.ts"],"names":[],"mappings":"AASA,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0NA0CoM,CAAC;AAE3N,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,mQAAmQ;QACrQ,YAAY,EAAE;;;;EAIhB,aAAa,EAAE;QACb,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gCAAgC;IAC9C,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,6FAA6F;QAC1G,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC;QACrC,OAAO,EAAE;;;;EAIX,aAAa,EAAE;KACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/decision.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAuCS,iBAAiB,CAAC,gCAAgC,EAAE,yCAAyC,CAAC;;;;;6FAKhC,CAAC;AAE9F,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,6NAA6N;QAC/N,YAAY,EAAE;;;;EAIhB,aAAa,EAAE;QACb,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gCAAgC;IAC9C,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,6FAA6F;QAC1G,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC;QACrC,OAAO,EAAE;;;;EAIX,aAAa,EAAE;KACd,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/explore.d.ts

@@ -1,8 +1,11 @@
 /**
- * Skill Template Workflow Modules
+ * Explore Workflow Template
  *
- * This file is generated by splitting the legacy monolithic
- * templates file into workflow-focused modules.
+ * Pre-change requirement convergence: interview a fuzzy idea or problem until
+ * it is concrete enough to hand to propose/issue. Read-only, and obliged to end
+ * by asking the user for the next step. Its sibling `tospec-grill` pressure-tests
+ * something already on the table — explore deliberately avoids leading with the
+ * word "grill" so the two don't compete for the same trigger.
  */
 import type { SkillTemplate, CommandTemplate } from '../types.js';
 export declare function getExploreSkillTemplate(): SkillTemplate;

package/dist/core/templates/workflows/explore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/explore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAgElE,wBAAgB,uBAAuB,IAAI,aAAa,CAcvD;AAED,wBAAgB,+BAA+B,IAAI,eAAe,CAYjE"}
+{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/explore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA4DlE,wBAAgB,uBAAuB,IAAI,aAAa,CAcvD;AAED,wBAAgB,+BAA+B,IAAI,eAAe,CAYjE"}

package/dist/core/templates/workflows/explore.js

@@ -1,6 +1,12 @@
+import { INTERVIEW_MECHANICS } from '../fragments/interview.js';
+import { nextStepLabelRule } from '../fragments/next-step.js';
 const EXPLORE_BODY = `**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and run \`tospec\` read-only commands, but you must NEVER write code or create artifact files during explore. When the requirement converges, record any material decisions via \`tospec-decision\` first, then hand off to \`tospec-propose\` or \`tospec-issue\` — those write the files.
 
-This is a grilling interview, not a freeform chat. Interview the user relentlessly about the idea or problem until you both share the same understanding, walking every branch of the decision tree — batching questions that stand on their own, but following dependent threads one question at a time.
+This is a relentless interview, not a freeform chat. Interrogate the idea or problem until you and the user share the same understanding, walking every branch of the decision tree.
+
+**Interview mechanics**
+
+${INTERVIEW_MECHANICS}
 
 **Steps**
 
@@ -10,11 +16,9 @@ This is a grilling interview, not a freeform chat. Interview the user relentless
    \`\`\`
    Read \`tospec/specs/\` for the capabilities this touches and \`tospec/config.yaml\` for project context. Do this BEFORE asking anything — questions you can answer yourself by reading the codebase are questions you should never ask the user.
 
-2. **Batch independent questions; sequence dependent ones**
-
-   Ask unrelated questions together in a single turn (use \`AskUserQuestion\` — up to 4 at once) so the user answers in one pass instead of a slow drip. A question whose answer depends on another still-open question isn't independent — it belongs to a *later* turn, once the question it hangs off is settled. Batch everything that stands on its own now; hold back only what's waiting on an answer you haven't heard yet, and when you do sequence, wait for that answer before continuing. Each question carries your suggested answer and the reasoning, so the user can just say "yes" instead of writing an essay.
+2. **Work the question priority order**
 
-   Work through this priority order, skipping anything already answered by the conversation or the codebase:
+   Take these in order, skipping anything the conversation or the codebase already answered:
    1. Goal and success condition — what does "done" look like?
    2. Who the user/actor is
    3. Boundaries — what's explicitly out of scope
@@ -22,65 +26,57 @@ This is a grilling interview, not a freeform chat. Interview the user relentless
    5. Data and state — what persists, what's transient
    6. Unstated assumptions — the things nobody said out loud
 
-3. **Probe every answer for hidden premises**
+3. **Converge**
 
-   After each answer, ask what it implies that hasn't been said yet. This is the core of the interview — surface-level answers hide the decisions that actually matter. Keep pulling on a thread until it stops giving you new information, then move to the next branch.
+   You're done when you can fully restate the requirement back to the user in your own words and they confirm it's correct — not when you run out of questions. If they correct your restatement, that's a sign there's still a hidden branch; keep going.
 
-4. **Route by question type**
-   - **Factual** ("does X already exist", "what does Y currently do") → look it up in the codebase yourself, never ask the user
-   - **Decision** (behavior, scope, tradeoffs) → always ask, and wait for the answer before proceeding
+4. **Restate**
 
-5. **Converge**
-
-   You're done when you can fully restate the requirement back to the user in your own words and they confirm it's correct — not when you run out of questions. If they correct your restatement, that's a sign there's still a hidden branch; keep grilling.
+   Deliver the converged understanding back in the conversation — the problem, the decisions made (with reasoning), and anything explicitly ruled out — so \`tospec-propose\`/\`tospec-issue\` can synthesize it straight from context (that's exactly the input they expect).
 
-6. **Restate**
+5. **Record any settled decision — don't ask first**
 
-   Deliver the converged understanding back in the conversation — the problem, the decisions made (with reasoning), and anything explicitly ruled out — so \`tospec-propose\`/\`tospec-issue\` can synthesize it straight from context (that's exactly the input they expect).
+   If the interview settled a **material** decision — a choice between real alternatives with lasting architecture/design impact that will get re-litigated if left in chat — record it now via \`tospec-decision\` with \`--status proposed\`. Don't put this to the user as an option: the restatement they just confirmed is the consent, and \`proposed\` is a draft status they can still reject. An answered factual lookup or a trivial preference is not material — record nothing when nothing material was settled. If you can't state the decision's rationale and the alternatives weighed, don't invent them — ask the user, per \`tospec-decision\`'s own rule. Run it as a sub-step and skip \`tospec-decision\`'s own next-step handoff; step 6 covers it. Report the created filename.
 
-7. **Always ask for the next step — never pick it yourself**
+6. **Always ask for the next step — never pick it yourself**
 
-   Once you've restated the understanding, you MUST put the next step to the user with \`AskUserQuestion\`. This is unconditional: explore never proceeds to the next action on its own, and never ends without asking.
+   Once you've restated the understanding (and recorded any decision), you MUST put the next step to the user with \`AskUserQuestion\`. This is unconditional: apart from that ADR, explore never proceeds to the next action on its own, and never ends without asking.
 
-   One question, always these options, with your recommended one **first** and labelled "(Recommended)". Write each option label from the situation you just explored — a short, conversational phrase naming the concrete next action here — then append the fixed action keyword in parentheses. The keyword is constant (\`(decision)\`, \`(propose)\`/\`(issue)\`, \`(grill)\`); the words before it are not — they must describe *this* action in *this* context, never a canned phrase, and never the raw \`tospec-*\` skill name. E.g. after settling a retry policy the first option might read "Record the retry-limit decision (decision)":
-   - **(decision)** — record a material decision as an ADR via \`tospec-decision\`. Offer this only when the interview actually settled one: a choice between real alternatives with lasting architecture/design impact that will get re-litigated if left in chat. An answered factual lookup or a trivial preference is not material — drop this option when nothing material was settled.
+   One question, always these options, with your recommended one **first** and labelled "(Recommended)". ${nextStepLabelRule('the situation you just explored', '\`(propose)\`/\`(issue)\`, \`(grill)\`')} E.g. after settling a retry policy the first option might read "Write up the retry-limit change (propose)":
    - **(propose)** (or **(issue)** when something is broken) — start writing the proposal via \`tospec-propose\`/\`tospec-issue\`.
    - **(grill)** — keep digging with a four-quadrant deep dive on what was just explored via \`tospec-grill\`.
 
-   Recommend \`tospec-decision\` when a material decision is unrecorded (the ADR comes **before** the proposal), \`tospec-propose\`/\`tospec-issue\` when the requirement is ready to build, and \`tospec-grill\` when it still feels fuzzy or under-tested.
+   Recommend \`tospec-propose\`/\`tospec-issue\` when the requirement is ready to build, and \`tospec-grill\` when it still feels fuzzy or under-tested.
 
-   \`tospec-propose\`/\`tospec-issue\` synthesize the requirement straight from the conversation and write the change artifacts; explore persists nothing itself. If the user picks \`tospec-decision\`, record it, then ask again — now recommending \`tospec-propose\`/\`tospec-issue\` — because a recorded decision still needs to flow into a change. Carry the recorded decision filename(s) (reported by \`tospec decision new\`) into that handoff: the propose/issue step passes them via \`tospec new change --decisions\` so the change's metadata links back to its ADRs.
+   \`tospec-propose\`/\`tospec-issue\` synthesize the requirement straight from the conversation and write the change artifacts; apart from the ADR in step 5, explore persists nothing itself. Carry the recorded decision filename(s) (reported by \`tospec decision new\`) into that handoff: the propose/issue step passes them via \`tospec new change --decisions\` so the change's metadata links back to its ADRs.
 
 **Guardrails**
-- **Always end with the next-step question** — never choose the follow-up action yourself, and never finish explore without asking
+- **Always end with the next-step question** — never choose the follow-up action yourself, and never finish explore without asking. Recording a settled decision (step 5) is the one exception: that one you do unasked
 - **Don't implement** — never write application code or edit source files during explore
-- **Record decisions before proposing** — if the interview settled a material decision, hand off to \`tospec-decision\` to record it before \`tospec-propose\`/\`tospec-issue\`; a real decision must not survive only in chat
-- **Batch what's independent, sequence what's dependent** — ask unrelated questions together in one turn; split to one at a time only when A's answer decides B
-- **Don't ask what you can look up** — codebase facts are yours to find, not the user's to recite
-- **Don't stop at the first plausible answer** — dig for the implied premise behind it
+- **Record decisions before proposing** — a settled material decision gets recorded via \`tospec-decision\` before \`tospec-propose\`/\`tospec-issue\`, not offered as a choice; a real decision must not survive only in chat
 - **Don't force convergence** — if the user wants to keep exploring after you've restated where things stand, keep going`;
 export function getExploreSkillTemplate() {
     return {
         name: 'tospec-explore',
-        description: 'Grill the user through a focused interview to converge on a requirement or a problem before it becomes a change. Use when the idea is still fuzzy, before creating a proposal or issue, or whenever the user wants to think something through rather than build it yet.',
-        instructions: `Grill the user about their idea or problem — batching independent questions, sequencing dependent ones — until it converges into something concrete enough to become a \`tospec-propose\` or \`tospec-issue\`.
+        description: 'Interview the user until a fuzzy idea or problem converges into a concrete requirement. Use before a change exists — when the idea is still fuzzy, or the user wants to think something through rather than build it. To pressure-test something already written, use tospec-grill.',
+        instructions: `Interview the user about their idea or problem until it converges into something concrete enough to become a \`tospec-propose\` or \`tospec-issue\`.
 
 **Input**: The user's request is whatever they want to think through — a vague idea, a specific problem, or a change name to explore in context of.
 
 ${EXPLORE_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
+        metadata: { author: 'tospec' },
         allowedTools: ['Bash(tospec:*)', 'Read', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }
 export function getTospecExploreCommandTemplate() {
     return {
         name: 'TOSPEC: Explore',
-        description: 'Grill the user through a focused interview to converge on a requirement or a problem',
+        description: 'Interview the user to converge a fuzzy idea or problem into a concrete requirement',
         category: 'Workflow',
         tags: ['workflow', 'explore'],
-        content: `Grill the user about their idea or problem — batching independent questions, sequencing dependent ones — until it converges into something concrete enough to become a \`tospec-propose\` or \`tospec-issue\`.
+        content: `Interview the user about their idea or problem until it converges into something concrete enough to become a \`tospec-propose\` or \`tospec-issue\`.
 
 **Input**: The argument after \`tospec-explore\` is whatever the user wants to think through — a vague idea, a specific problem, or a change name to explore in context of. May be empty.
 

package/dist/core/templates/workflows/explore.js.map

@@ -1 +1 @@
-{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/explore.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yHA4DoG,CAAC;AAE1H,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,yQAAyQ;QACtR,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,sFAAsF;QACnG,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QAC7B,OAAO,EAAE;;;;EAIX,YAAY,EAAE;KACb,CAAC;AACJ,CAAC"}
+{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/explore.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,YAAY,GAAG;;;;;;EAMnB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2GAoCsF,iBAAiB,CAAC,iCAAiC,EAAE,wCAAwC,CAAC;;;;;;;;;;;;yHAYhF,CAAC;AAE1H,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,qRAAqR;QAClS,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,oFAAoF;QACjG,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QAC7B,OAAO,EAAE;;;;EAIX,YAAY,EAAE;KACb,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/grill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grill.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0DlE,wBAAgB,qBAAqB,IAAI,aAAa,CAcrD;AAED,wBAAgB,6BAA6B,IAAI,eAAe,CAY/D"}
+{"version":3,"file":"grill.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAmDlE,wBAAgB,qBAAqB,IAAI,aAAa,CAcrD;AAED,wBAAgB,6BAA6B,IAAI,eAAe,CAY/D"}

package/dist/core/templates/workflows/grill.js

@@ -1,6 +1,8 @@
-const GRILL_BODY = `**IMPORTANT: Grill is read-only pressure-testing, not building.** You may read files, search code, and run \`tospec\` read-only commands, but you must NEVER write code, edit sources, or create artifact files during a grill. Grill writes nothing itself — when the interrogation lands something worth persisting, it hands off to the skill that owns that write.
+import { INTERVIEW_MECHANICS } from '../fragments/interview.js';
+import { nextStepLabelRule } from '../fragments/next-step.js';
+const GRILL_BODY = `**IMPORTANT: Grill is read-only pressure-testing, not building.** You may read files, search code, and run \`tospec\` read-only commands, but you must NEVER write code, edit sources, or create artifact files during a grill. Grill writes nothing itself — when the interrogation lands something worth persisting, it delegates to the skill that owns that write (\`tospec-decision\` for a settled decision, \`tospec-update\` for a change's artifacts).
 
-This is a relentless interrogation of whatever is on the table — a plan, a decision, an idea, a design. Stress-test it until every assumption is named and every open question is either answered or explicitly parked. Work the four quadrants below, batching questions that stand on their own and following dependent threads one question at a time.
+This is a relentless interrogation of whatever is on the table — a plan, a decision, an idea, a design. Stress-test it until every assumption is named and every open question is either answered or explicitly parked.
 
 **Pick the target first — never assume one**
 
@@ -24,10 +26,7 @@ Sweep all four — the last two are where the real risk hides:
 
 **Interview mechanics**
 
-- **Batch independent questions; sequence dependent ones.** Ask unrelated questions together in a single turn (use \`AskUserQuestion\` — up to 4 at once). A question whose answer depends on another still-open question isn't independent — hold it for a later turn once the question it hangs off is settled.
-- **Every question carries a suggested answer** and the reasoning behind it, so the user can confirm instead of writing an essay.
-- **Look up what's checkable.** Factual questions ("does X already exist", "what does Y currently do") are yours to answer from the codebase — never ask the user something you can verify yourself.
-- **Probe every answer for its hidden premise.** After each answer, ask what it implies that hasn't been said yet. Don't stop at the first plausible answer; keep pulling the thread until it stops giving new information.
+${INTERVIEW_MECHANICS}
 
 **Converge**
 
@@ -35,28 +34,22 @@ You're done only when you can fully restate the shared understanding — the cla
 
 **Hand off once the understanding is confirmed**
 
-A grill that shifts the picture leaves work behind. After the user confirms the restatement, offer the next step. When you put these options to the user, write each label from what this grill actually surfaced — a short, conversational phrase naming the concrete next action — then append the fixed action keyword in parentheses. The keyword is constant (\`(decision)\`, \`(update)\`, \`(propose)\`/\`(issue)\`, \`(grill)\`); the words before it are not — they must describe *this* action in *this* context, never a canned phrase, and never the raw \`tospec-*\` skill name:
+A grill that shifts the picture leaves work behind. Once the user confirms the restatement:
 
-1. **(decision)**, if the grill produced one. A choice between real alternatives with lasting architecture/design impact belongs in an ADR before anything else — via \`tospec-decision\`. Skip this when nothing material moved; a confirmed assumption is not a decision.
-2. **Then route by target kind:**
-   - **Target was an existing written proposal** -> **(update)** via \`tospec-update\` to fold the outcome into that change's artifacts. Name the change so update doesn't have to re-ask.
-   - **Target was a raw idea or an explore** -> nothing is written yet; offer **(propose)** (or **(issue)** when something is broken) via \`tospec-propose\`/\`tospec-issue\`, or **(grill)** if it's still fuzzy.
+1. **Record any decision the grill produced — don't ask first.** A choice between real alternatives with lasting architecture/design impact belongs in an ADR before anything else: record it via \`tospec-decision\` with \`--status proposed\`. Don't offer this as an option — the confirmation you just got is the consent, and \`proposed\` is a draft status the user can still reject. Record nothing when nothing material moved; a confirmed assumption is not a decision. If you can't state the rationale and the alternatives weighed, don't invent them — ask the user, per \`tospec-decision\`'s own rule. Run it as a sub-step and skip \`tospec-decision\`'s own next-step handoff; step 2 covers it. Report the created filename.
+2. **Then offer the next step,** routed by target kind. ${nextStepLabelRule('what this grill actually surfaced', '\`(update)\`, \`(propose)\`/\`(issue)\`, \`(grill)\`')}
+   - **Target was an existing written proposal** → **(update)** via \`tospec-update\` to fold the outcome into that change's artifacts. Name the change so update doesn't have to re-ask, and carry any recorded decision filename with it.
+   - **Target was a raw idea or an explore** → nothing is written yet; offer **(propose)** (or **(issue)** when something is broken) via \`tospec-propose\`/\`tospec-issue\`, or **(grill)** if it's still fuzzy.
 
-Grill itself writes nothing — \`tospec-decision\` and \`tospec-update\` own those files.
+Apart from that ADR, grill writes nothing — \`tospec-decision\` and \`tospec-update\` own those files.
 
 **Guardrails**
-- **Don't implement** — never write application code, edit sources, or create artifact files during a grill
-- **Don't pick the target yourself** — when the subject isn't explicit or unambiguous, ask; when there's no subject at all, stop
 - **Don't act before consensus** — take no action, including any handoff, until the user has confirmed the restated understanding
-- **Don't ask what you can look up** — codebase facts are yours to find, not the user's to recite
-- **Don't stop at the first plausible answer** — dig for the implied premise behind it
-- **Don't force closure** — if the user wants to keep grilling after you've restated where things stand, keep going
-
-Grill is on-demand deep-dive for *any* artifact — not the pre-change requirement convergence that \`tospec-explore\` owns — and it lands no files of its own, only handoffs.`;
+- **Don't force closure** — if the user wants to keep grilling after you've restated where things stand, keep going`;
 export function getGrillSkillTemplate() {
     return {
         name: 'tospec-grill',
-        description: "Pressure-test any artifact — a plan, a decision, an idea, a design — through a relentless four-quadrant Known/Unknown interrogation. Trigger whenever the user says 'grill', 'grill me', 'grilling', or 'grilling me', or otherwise wants to dig deeper, surface unspoken assumptions, and hunt blind spots before committing.",
+        description: "Pressure-test any artifact — a plan, a decision, an idea, a design — through a relentless four-quadrant Known/Unknown interrogation. Trigger when the user says 'grill', 'grill me' or 'grilling', or wants to surface unspoken assumptions and hunt blind spots before committing. To converge an idea not yet written down, use tospec-explore.",
         instructions: `Grill any artifact the user hands you — a plan, decision, idea, or design — through the four-quadrant Known/Unknown frame until every assumption is named and the understanding is shared and confirmed.
 
 **Input**: The user's request is whatever they want stress-tested — a plan file, a recorded decision, a raw idea, or a change name to interrogate in context of. May be empty, in which case resolve the target per "Pick the target first" below — never assume one.
@@ -64,7 +57,7 @@ export function getGrillSkillTemplate() {
 ${GRILL_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
+        metadata: { author: 'tospec' },
         allowedTools: ['Bash(tospec:*)', 'Read', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }

package/dist/core/templates/workflows/grill.js.map

@@ -1 +1 @@
-{"version":3,"file":"grill.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6KAsD0J,CAAC;AAE9K,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,gUAAgU;QAC7U,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,2FAA2F;QACxG,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;QAC3B,OAAO,EAAE;;;;EAIX,UAAU,EAAE;KACX,CAAC;AACJ,CAAC"}
+{"version":3,"file":"grill.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BjB,mBAAmB;;;;;;;;;;;0DAWqC,iBAAiB,CAAC,mCAAmC,EAAE,sDAAsD,CAAC;;;;;;;;oHAQpD,CAAC;AAErH,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,mVAAmV;QAChW,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,2FAA2F;QACxG,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;QAC3B,OAAO,EAAE;;;;EAIX,UAAU,EAAE;KACX,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/issue.js

@@ -69,8 +69,8 @@ export function getTospecIssueSkillTemplate() {
 ${ISSUE_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
-        allowedTools: ['Bash(tospec:*)', 'Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'AskUserQuestion'],
+        metadata: { author: 'tospec' },
+        allowedTools: ['Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }
 export function getTospecIssueCommandTemplate() {

package/dist/core/templates/workflows/issue.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/issue.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EA2DuD,CAAC;AAE3E,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,6NAA6N;QAC1O,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KACrG,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,8EAA8E;QAC3F,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,WAAW,CAAC;QACxC,OAAO,EAAE;;;;EAIX,UAAU,EAAE;KACX,CAAC;AACJ,CAAC"}
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/issue.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EA2DuD,CAAC;AAE3E,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,6NAA6N;QAC1O,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KACnF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,8EAA8E;QAC3F,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,WAAW,CAAC;QACxC,OAAO,EAAE;;;;EAIX,UAAU,EAAE;KACX,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/propose.js

@@ -59,7 +59,7 @@ export function getTospecProposeSkillTemplate() {
 ${PROPOSE_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
+        metadata: { author: 'tospec' },
         allowedTools: ['Bash(tospec:*)', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }

package/dist/core/templates/workflows/propose.js.map

@@ -1 +1 @@
-{"version":3,"file":"propose.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/propose.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gIAiD2G,CAAC;AAEjI,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,kRAAkR;QAC/R,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,wEAAwE;QACrF,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC;QACtC,OAAO,EAAE;;;;EAIX,YAAY,EAAE;KACb,CAAC;AACJ,CAAC"}
+{"version":3,"file":"propose.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/propose.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gIAiD2G,CAAC;AAEjI,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,kRAAkR;QAC/R,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,wEAAwE;QACrF,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC;QACtC,OAAO,EAAE;;;;EAIX,YAAY,EAAE;KACb,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/sync.js

@@ -59,7 +59,7 @@ Summarize how many Requirements were in sync, how many specs were updated, and w
 export function getTospecSyncSkillTemplate() {
     return {
         name: 'tospec-sync',
-        description: 'Compare each Requirement a change touched against the actual implementation and reconcile drift, with the source code as the source of truth, producing sync-report.md. Use before archiving a change with spec deltas — the tospec-archive workflow will offer to run this when it judges a sync is warranted.',
+        description: 'Reconcile a change\'s Requirements against the actual implementation — code wins on any mismatch — and write sync-report.md. Use before archiving a change whose specs may have drifted from the code.',
         instructions: `Reconcile \`specs/\` against the implementation for every Requirement this change touched — code wins on any mismatch. Run this before \`tospec-archive\` when the change's specs may have drifted from the code.
 
 **Input**: The user's request should name the change to sync.
@@ -67,7 +67,7 @@ export function getTospecSyncSkillTemplate() {
 ${SYNC_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
+        metadata: { author: 'tospec' },
         allowedTools: ['Bash(tospec:*)', 'Read', 'Write', 'Edit', 'Grep', 'Glob'],
     };
 }

package/dist/core/templates/workflows/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/sync.ts"],"names":[],"mappings":"AAYA,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mQAyDiP,CAAC;AAEpQ,MAAM,UAAU,0BAA0B;IACxC,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,iTAAiT;QAC9T,YAAY,EAAE;;;;EAIhB,SAAS,EAAE;QACT,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,qEAAqE;QAClF,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC;QAC1C,OAAO,EAAE;;;;EAIX,SAAS,EAAE;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/sync.ts"],"names":[],"mappings":"AAYA,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mQAyDiP,CAAC;AAEpQ,MAAM,UAAU,0BAA0B;IACxC,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,wMAAwM;QACrN,YAAY,EAAE;;;;EAIhB,SAAS,EAAE;QACT,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,qEAAqE;QAClF,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC;QAC1C,OAAO,EAAE;;;;EAIX,SAAS,EAAE;KACV,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0ElE,wBAAgB,4BAA4B,IAAI,aAAa,CAc5D;AAED,wBAAgB,8BAA8B,IAAI,eAAe,CAYhE"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAgElE,wBAAgB,4BAA4B,IAAI,aAAa,CAc5D;AAED,wBAAgB,8BAA8B,IAAI,eAAe,CAYhE"}

package/dist/core/templates/workflows/update.js

@@ -1,19 +1,9 @@
-const UPDATE_BODY = `Revise a change's existing planning artifacts and keep them coherent. Never edit code.
+import { nextStepLabelRule } from '../fragments/next-step.js';
+const UPDATE_BODY = `**Steps**
 
-**Steps**
+1. **Select the change**
 
-1. **If no change name provided, prompt for selection**
-
-   Run \`tospec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
-
-   Present the top 3-4 most recently modified changes as options, showing:
-   - Change name
-   - Status (e.g., "0/5 tasks", "complete", "no tasks" from \`completedTasks\`/\`totalTasks\`/\`status\`)
-   - How recently it was modified (from \`lastModified\`)
-
-   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   If the user named one, use it. Otherwise run \`tospec list --json\` and let the user pick with \`AskUserQuestion\` — never guess, never auto-select. Offer the 3-4 most recently modified, each labelled with its name, its status (from \`completedTasks\`/\`totalTasks\`/\`status\`) and how recently it changed (from \`lastModified\`), with the most recent marked "(Recommended)".
 
 2. **Get the change's artifacts**
    \`\`\`bash
@@ -25,9 +15,9 @@ const UPDATE_BODY = `Revise a change's existing planning artifacts and keep them
    - \`isComplete\`: Boolean indicating if all required artifacts are complete
    - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
-   The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
+   The artifact ids and paths come from the active schema — never assume them, and never branch on hardcoded artifact names. Custom schemas must work unchanged.
 
-   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` — the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
 
 3. **Understand the request**
    - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
@@ -35,14 +25,14 @@ const UPDATE_BODY = `Revise a change's existing planning artifacts and keep them
 
 4. **Read and reconcile**
    - Read the artifact(s) the request touches and the change's other existing artifacts.
-   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
+   - Apply the requested edit. Then check every other existing artifact against it — in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
    - Note everything that is now inconsistent, missing, or contradictory.
-   - Revise only files that already exist (\`existingOutputPaths\`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to \`tospec-propose\` (sdd) or \`tospec-issue\` to create them.
+   - Revise only files that already exist (\`existingOutputPaths\`). Creating an artifact that doesn't exist yet, or a new file under a glob artifact, is \`tospec-propose\`/\`tospec-issue\`'s job — note what's missing and point the user there.
    - If the change is already coherent, say so and make no edits.
 
 5. **Confirm and apply, one artifact at a time**
    - Show each proposed revision and why. Write only after the user confirms.
-   - If the user rejects a revision, do not write it - leave that artifact unchanged.
+   - If the user rejects a revision, leave that artifact unchanged.
    - When a substantial rewrite is needed, get that artifact's rules and template first:
      \`\`\`bash
      tospec instructions <artifact-id> --change "<name>" --json
@@ -50,23 +40,23 @@ const UPDATE_BODY = `Revise a change's existing planning artifacts and keep them
      Read \`rules\` and \`template\` from the response.
 
 6. **Point to the next step (guidance only - NEVER act on it)**
-   When you surface these to the user, write each label from where this change actually stands — a short, conversational phrase naming the concrete next action — then append the fixed action keyword in parentheses (\`(propose)\`/\`(issue)\`, \`(apply)\`, \`(archive)\`); the words before it must describe *this* action in *this* context, never a canned phrase, and never the raw \`tospec-*\` skill name:
-   - Artifacts still missing -> suggest **(propose)** (sdd) or **(issue)** via \`tospec-propose\`/\`tospec-issue\` to create them.
-   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest **(apply)** via \`tospec-apply\`.
-   - Everything done and implemented -> suggest **(archive)** via \`tospec-archive\`.
+   ${nextStepLabelRule('where this change actually stands', '\`(propose)\`/\`(issue)\`, \`(apply)\`, \`(archive)\`')}
+   - Artifacts still missing → suggest **(propose)** (sdd) or **(issue)** via \`tospec-propose\`/\`tospec-issue\` to create them.
+   - Change already implemented (tasks checked off / already applied) → the code may no longer match the revised plan; suggest **(apply)** via \`tospec-apply\`.
+   - Everything done and implemented → suggest **(archive)** via \`tospec-archive\`.
 
 **Output**
 
 After each invocation, show:
 - Which artifacts were revised (and which proposed revisions were rejected)
-- Anything deferred to artifact creation (not-yet-created artifacts or files -> \`tospec-propose\`/\`tospec-issue\`)
+- Anything deferred to artifact creation (not-yet-created artifacts or files → \`tospec-propose\`/\`tospec-issue\`)
 - Where the change stands and the recommended next command
 
 **Guardrails**
-- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to \`tospec-apply\`.
+- Planning artifacts only — NEVER edit implementation code. If the revised plan implies code changes, stop and point to \`tospec-apply\`.
 - Use the artifact ids and paths reported by \`tospec status\`; never branch on hardcoded artifact names.
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
-- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`tospec-propose\`/\`tospec-issue\`'s job.
+- Stay behind the build frontier: revise what exists, and leave new artifacts and new glob files to \`tospec-propose\`/\`tospec-issue\`.
 - Confirm every edit with the user before writing.
 - If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`tospec-propose\`/\`tospec-issue\` (the "Update vs. Start Fresh" heuristic).`;
 export function getTospecUpdateSkillTemplate() {
@@ -80,8 +70,8 @@ export function getTospecUpdateSkillTemplate() {
 ${UPDATE_BODY}`,
         license: 'MIT',
         compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec', version: '1.0' },
-        allowedTools: ['Bash(tospec:*)', 'Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob'],
+        metadata: { author: 'tospec' },
+        allowedTools: ['Bash(tospec:*)', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'AskUserQuestion'],
     };
 }
 export function getTospecUpdateCommandTemplate() {

package/dist/core/templates/workflows/update.js.map

@@ -1 +1 @@
-{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oLAsEgK,CAAC;AAErL,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,oPAAoP;QACjQ,YAAY,EAAE;;;;EAIhB,WAAW,EAAE;QACX,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAC9C,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAClF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,6EAA6E;QAC1F,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;QAC/B,OAAO,EAAE;;;;EAIX,WAAW,EAAE;KACZ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAyCf,iBAAiB,CAAC,mCAAmC,EAAE,uDAAuD,CAAC;;;;;;;;;;;;;;;;;;oLAkBgE,CAAC;AAErL,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,oPAAoP;QACjQ,YAAY,EAAE;;;;EAIhB,WAAW,EAAE;QACX,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,6EAA6E;QAC1F,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;QAC/B,OAAO,EAAE;;;;EAIX,WAAW,EAAE;KACZ,CAAC;AACJ,CAAC"}

package/dist/core/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/core/update.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,GAAE,oBAAyB;IAIxC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqKjD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,OAAO,CAAC,+BAA+B;IAkBvC;;;;OAIG;YACW,yBAAyB;CA0BxC"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/core/update.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,GAAE,oBAAyB;IAIxC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoKjD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,OAAO,CAAC,+BAA+B;IAkBvC;;;;OAIG;YACW,yBAAyB;CA0BxC"}

package/dist/core/update.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { AI_TOOLS, TOSPEC_DIR_NAME } from './config.js';
-import { getToolVersionStatus, getSkillTemplates, generateSkillContent, getConfiguredTools, removeLegacySkillDirs, removeLegacyToolSkillLayout, writeToolCommands, } from './shared/index.js';
+import { getToolVersionStatus, getSkillTemplates, writeSkillDir, getConfiguredTools, removeLegacySkillDirs, removeLegacyToolSkillLayout, writeToolCommands, } from './shared/index.js';
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
@@ -83,8 +83,7 @@ export class UpdateCommand {
         // formats). Always rewritten on update, same as init.
         const agentsSkillsDir = path.join(resolvedProjectPath, '.agents', 'skills');
         for (const { template, dirName } of skillTemplates) {
-            const skillContent = generateSkillContent(template, TOSPEC_VERSION);
-            await FileSystemUtils.writeFile(path.join(agentsSkillsDir, dirName, 'SKILL.md'), skillContent);
+            await writeSkillDir(agentsSkillsDir, dirName, template, TOSPEC_VERSION);
         }
         await removeLegacySkillDirs(agentsSkillsDir);
         await fs.promises.rm(path.join(resolvedProjectPath, '.agents', 'commands'), { recursive: true, force: true });