@gitwhy-cli/whyspec 0.1.16 → 0.1.18

package/dist/adapters/claude-code.d.ts

@@ -1,14 +1,9 @@
-import { GeneratedFile } from "./types.js";
+import { GeneratedFile, WhySpecCommand } from "./types.js";
 /**
- * Generate Claude Code skill files for all 6 WhySpec commands.
- *
- * Creates .claude/skills/whyspec-<command>/SKILL.md with:
- * - YAML frontmatter (name, description)
- * - Placeholder instructions showing the CLI-as-oracle pattern
- *
- * @param projectRoot - Optional project root prefix for paths (default: "")
- * @returns Array of GeneratedFile objects
+ * Generate compact instructions for each WhySpec command.
+ * Used by adapters that embed skill content (Codex, Claude commands).
+ * The canonical full-length skills live in skills/whyspec-{cmd}/SKILL.md.
  */
-export declare function generateClaudeCodeSkills(projectRoot?: string): GeneratedFile[];
+export declare function getSkillInstructions(command: WhySpecCommand): string;
 export declare function generateClaudeCodeCommands(projectRoot?: string): GeneratedFile[];
 //# sourceMappingURL=claude-code.d.ts.map

package/dist/adapters/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAKd,MAAM,YAAY,CAAC;AAyLpB;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,GAAE,MAAW,GACvB,aAAa,EAAE,CAmBjB;AAED,wBAAgB,0BAA0B,CACxC,WAAW,GAAE,MAAW,GACvB,aAAa,EAAE,CAqBjB"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAIb,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CA+IpE;AAED,wBAAgB,0BAA0B,CACxC,WAAW,GAAE,MAAW,GACvB,aAAa,EAAE,CAqBjB"}

package/dist/adapters/claude-code.js

@@ -1,47 +1,45 @@
 import { WHYSPEC_COMMANDS, COMMAND_DESCRIPTIONS, COMMAND_ARGUMENT_HINTS, } from "./types.js";
 /**
- * Generate the placeholder instructions for each WhySpec command skill.
- * These are filled with real content by Agent 5 (skill authoring).
- * The placeholders show the CLI-as-oracle pattern so the skill is functional
- * even before Agent 5 enriches it.
+ * Generate compact instructions for each WhySpec command.
+ * Used by adapters that embed skill content (Codex, Claude commands).
+ * The canonical full-length skills live in skills/whyspec-{cmd}/SKILL.md.
  */
-function getSkillInstructions(command) {
+export function getSkillInstructions(command) {
     switch (command) {
         case "plan":
-            return `# WhySpec Plan
+            return `Plan a change — create intent.md, design.md, and tasks.md with the Decision Bridge.
 
-Use this skill when the developer wants to plan a change before coding.
+When ready to implement, run \`/whyspec:execute\`
 
 ## Workflow
 
-1. Ask the developer 2-3 forcing questions:
-   - "What problem does this solve?"
-   - "What constraints exist?"
-   - "How will you know it works?"
+1. Parse what the user typed. If they gave a meaningful description, act immediately — do NOT
+   ask generic questions like "What problem does this solve?" or "What constraints exist?"
+   Only ask if ARGUMENTS is empty or genuinely ambiguous.
 
 2. Call the CLI to create the change folder:
    \`\`\`bash
    whyspec plan --json "<change-name>"
    \`\`\`
 
-3. Parse the JSON response to get the folder path and templates.
+3. Explore the codebase to understand the affected area before writing plan files.
 
 4. Create three files in the change folder:
    - **intent.md** — Why this change exists, decisions to make, constraints, success criteria
    - **design.md** — Technical approach, trade-off matrix, architecture, questions to resolve
    - **tasks.md** — Verification criteria (defined FIRST), then implementation checklist
 
-5. The "Decisions to Make" section in design.md is the BEFORE side of the Decision Bridge.
-   These will be resolved by /whyspec-capture after implementation.
+5. The "Decisions to Make" section in intent.md is the BEFORE side of the Decision Bridge.
 
 ## Important
-- Always call the CLI first — it handles path creation and validation.
-- Capture COMPLETE reasoning, not abbreviated summaries.
-- Every decision-to-make should be a checkbox: \`- [ ] Token storage: cookie vs localStorage?\``;
+- Act first, ask only when stuck. The user told you what they want.
+- Ground plans in the actual codebase — read relevant files before writing.
+- Every unsettled design choice must be a checkbox in "Decisions to Make".
+- Scale the plan to the change — a typo fix gets 3 lines, not a trade-off matrix.`;
         case "execute":
-            return `# WhySpec Execute
+            return `Implement a change — read the plan, work through tasks, commit atomically.
 
-Use this skill when the developer wants to implement a planned change.
+When all tasks are done, run \`/whyspec:capture\`
 
 ## Workflow
 
@@ -50,103 +48,78 @@ Use this skill when the developer wants to implement a planned change.
    whyspec execute --json "<change-name>"
    \`\`\`
 
-2. Parse the JSON response to get intent, design, tasks, and progress.
+2. Read intent.md and design.md BEFORE coding — understand the goal first.
 
-3. Read intent.md and design.md for WHY context — understand the goal before coding.
-
-4. Work through tasks.md sequentially:
+3. Work through tasks.md sequentially:
    - Show progress: "Working on task 3/7: <description>"
    - Implement the code changes
    - Mark each task complete: \`- [ ]\` → \`- [x]\` in tasks.md
+   - Run the task's verify: check
    - Commit atomically (one commit per task or logical unit)
 
-5. On completion, prompt: "Ready to capture reasoning? Run /whyspec-capture"
+4. If reality contradicts the design, STOP and flag it — don't silently override.
 
 ## Important
-- Use intent.md as context while implementing — it contains the WHY.
-- Track deviations from the plan — surprises are valuable for capture.
-- Do not skip tasks or mark them done without implementing.`;
+- Never skip the plan. Read intent.md before writing code.
+- Commit atomically — one commit per task, not one giant commit.
+- Pause on design contradictions — update the plan before continuing.`;
         case "capture":
-            return `# WhySpec Capture
+            return `Capture reasoning — resolve the Decision Bridge and preserve the full story.
 
-Use this skill when the developer wants to save reasoning after coding.
+View the complete story with \`/whyspec:show\`
 
 ## Workflow
 
-1. Call the CLI to get the capture template and metadata:
+1. Call the CLI to get the capture template:
    \`\`\`bash
    whyspec capture --json "<change-name>"
    \`\`\`
 
-2. Parse the JSON response to get the template, linked commits, and files changed.
-
-3. Read intent.md and design.md from the change folder.
-
-4. Create a ctx_<id>.md file in the change folder using the GitWhy SaaS XML format:
-   - Map each "Decision to Make" from design.md → "Decisions Made" with rationale
-   - Map each "Question to Resolve" → resolved answer
-   - Capture "Surprises" — decisions NOT in the plan
-   - Include story, rejected alternatives, trade-offs, verification, risks
+2. Read intent.md and design.md for the Decision Bridge mapping.
 
-5. This completes the Decision Bridge: plan PREDICTED decisions, capture RECORDS them.
+3. Create ctx_<id>.md in GitWhy SaaS XML format:
+   - Map each "Decision to Make" → "Decisions Made" with full rationale
+   - Map each "Question to Resolve" → answer with reasoning
+   - Capture "Surprises" — decisions NOT in the original plan
 
 ## Important
-- The context file uses \`<context>\` XML tags (GitWhy SaaS format).
-- Include ALL decisions, not just the ones from the plan.
+- Capture reasoning, not summaries. "We chose X because Y outweighs Z" not just "we used X."
+- Every planned decision must be resolved. Prompt the user for any gaps.
 - Surprises (unplanned decisions) are the most valuable part of the capture.`;
         case "show":
-            return `# WhySpec Show
-
-Use this skill when the developer wants to view the full story of a change.
+            return `Show the full story — intent, design, tasks, reasoning — with the Decision Bridge delta.
 
 ## Workflow
 
-1. Call the CLI to get the full change data:
+1. Call the CLI:
    \`\`\`bash
    whyspec show --json "<change-name>"
    \`\`\`
 
-2. Parse the JSON response containing intent, design, tasks, context, surprises, and Decision Bridge delta.
+2. Display: Intent (WHY) → Design (HOW) → Tasks (WHAT) → Reasoning (AFTER)
 
-3. Display the change story in sections:
-   - **Intent** — WHY (from intent.md)
-   - **Design** — HOW (from design.md)
-   - **Tasks** — WHAT (from tasks.md with completion status)
-   - **Context** — REASONING (from ctx_<id>.md)
-   - **Decision Bridge Delta** — Decisions to Make vs Decisions Made, highlighting changes and surprises
+3. Highlight the Decision Bridge Delta: planned vs actual decisions with rationale.
 
 ## Important
-- The Decision Bridge delta is the unique value — always show it.
-- If context hasn't been captured yet, show intent + design + tasks and suggest running /whyspec-capture.`;
+- The Decision Bridge delta is the core value — always show it.
+- If context hasn't been captured, suggest running /whyspec:capture.`;
         case "search":
-            return `# WhySpec Search
-
-Use this skill when the developer wants to find past decisions and reasoning.
+            return `Search reasoning — find past decisions and contexts across all changes.
 
 ## Workflow
 
-1. Call the CLI to search across all changes:
+1. Call the CLI:
    \`\`\`bash
    whyspec search --json "<query>"
    \`\`\`
 
-2. Parse the JSON response containing scored results with snippets.
-
-3. Display results ranked by relevance:
-   - Title matches score highest (100 points)
-   - Reasoning/decision matches score next (30 points)
-   - File path matches score lower (20 points)
-
-4. For each result, show: title, change name, score, and a relevant snippet.
+2. Display results ranked by relevance with reasoning snippets — not just titles.
 
 ## Important
-- Search covers both active changes and archived ones.
-- Search also finds intent.md and design.md — not just captured contexts.
-- Use this before starting new work: "Has anyone reasoned about this area before?"`;
+- Always show reasoning snippets, not just titles.
+- Search includes plan files (intent.md, design.md), not just captured contexts.`;
         case "debug":
-            return `# WhySpec Debug
-
-Use this skill when the developer is investigating a bug.
+            return `Debug with scientific method. No fix without root cause.
 
 ## Workflow
 
@@ -155,54 +128,21 @@ Use this skill when the developer is investigating a bug.
    whyspec debug --json "<bug-description>"
    \`\`\`
 
-2. Parse the JSON response to get the debug folder path and related past contexts.
+2. Search past contexts first — check if this domain has been reasoned about before.
 
 3. Follow the scientific method:
-   - **Symptoms** — Expected vs actual behavior, error messages, reproduction steps
-   - **Related contexts** — Search past decisions in this area (from CLI response)
-   - **Hypotheses** — Form 3+ falsifiable hypotheses with "what would prove this wrong?"
-   - **Investigation** — Test each hypothesis with evidence gathering
-   - **Root cause** — Prove the diagnosis BEFORE proposing a fix (Iron Law)
-   - **Fix** — Apply the fix and verify
-   - **Prevention** — How to prevent this class of bug in the future
-
-4. Create debug.md with the full investigation trail.
-
-5. Auto-prompt: "Ready to capture debug reasoning? Run /whyspec-capture"
+   - **Symptoms** — Expected vs actual, error messages, reproduction steps
+   - **Hypotheses** — 3+ falsifiable claims with concrete tests
+   - **Investigation** — Test one at a time, record evidence
+   - **Root cause** — Prove diagnosis BEFORE proposing fix (Iron Law)
+   - **Fix + Capture** — Minimal fix, then auto-capture reasoning
 
 ## Important
-- No fix without root cause — this is the Iron Law.
-- Check related past contexts BEFORE forming hypotheses — past decisions inform better hypotheses.
-- The debug.md persists across sessions so investigation survives context resets.`;
+- No fix without root cause — the Iron Law is non-negotiable.
+- Write debug.md incrementally — it persists across context resets.
+- Always capture the investigation as a context file when resolved.`;
     }
 }
-/**
- * Generate Claude Code skill files for all 6 WhySpec commands.
- *
- * Creates .claude/skills/whyspec-<command>/SKILL.md with:
- * - YAML frontmatter (name, description)
- * - Placeholder instructions showing the CLI-as-oracle pattern
- *
- * @param projectRoot - Optional project root prefix for paths (default: "")
- * @returns Array of GeneratedFile objects
- */
-export function generateClaudeCodeSkills(projectRoot = "") {
-    const prefix = projectRoot ? `${projectRoot}/` : "";
-    return WHYSPEC_COMMANDS.map((command) => {
-        const frontmatter = [
-            "---",
-            `name: whyspec-${command}`,
-            `description: ${COMMAND_DESCRIPTIONS[command]}`,
-            "---",
-        ].join("\n");
-        const instructions = getSkillInstructions(command);
-        const content = `${frontmatter}\n\n${instructions}\n`;
-        return {
-            path: `${prefix}.claude/skills/whyspec-${command}/SKILL.md`,
-            content,
-        };
-    });
-}
 export function generateClaudeCodeCommands(projectRoot = "") {
     const prefix = projectRoot ? `${projectRoot}/` : "";
     return WHYSPEC_COMMANDS.map((command) => {

package/dist/adapters/claude-code.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,OAAuB;IACnD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gGA6BmF,CAAC;QAE7F,KAAK,SAAS;YACZ,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;4DA0B+C,CAAC;QAEzD,KAAK,SAAS;YACZ,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;6EA0BgE,CAAC;QAE1E,KAAK,MAAM;YACT,OAAO;;;;;;;;;;;;;;;;;;;;;;0GAsB6F,CAAC;QAEvG,KAAK,QAAQ;YACX,OAAO;;;;;;;;;;;;;;;;;;;;;;;mFAuBsE,CAAC;QAEhF,KAAK,OAAO;YACV,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kFA6BqE,CAAC;IACjF,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,cAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACtC,MAAM,WAAW,GAAG;YAClB,KAAK;YACL,iBAAiB,OAAO,EAAE;YAC1B,gBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;YAC/C,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,YAAY,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,GAAG,WAAW,OAAO,YAAY,IAAI,CAAC;QAEtD,OAAO;YACL,IAAI,EAAE,GAAG,MAAM,0BAA0B,OAAO,WAAW;YAC3D,OAAO;SACR,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,cAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACtC,MAAM,WAAW,GAAG;YAClB,KAAK;YACL,gBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;YAC/C,kBAAkB,sBAAsB,CAAC,OAAO,CAAC,EAAE;YACnD,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,YAAY,GAAG,oBAAoB,CAAC,OAAO,CAAC;aAC/C,UAAU,CAAC,WAAW,EAAE,WAAW,CAAC;aACpC,UAAU,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;QAChD,MAAM,cAAc,GAAG,qCAAqC,OAAO,KAAK,CAAC;QAEzE,OAAO;YACL,IAAI,EAAE,GAAG,MAAM,4BAA4B,OAAO,KAAK;YACvD,OAAO,EAAE,GAAG,WAAW,OAAO,cAAc,OAAO,YAAY,IAAI;SACpE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAuB;IAC1D,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;kFA4BqE,CAAC;QAE/E,KAAK,SAAS;YACZ,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;sEAyByD,CAAC;QAEnE,KAAK,SAAS;YACZ,OAAO;;;;;;;;;;;;;;;;;;;;;6EAqBgE,CAAC;QAE1E,KAAK,MAAM;YACT,OAAO;;;;;;;;;;;;;;;qEAewD,CAAC;QAElE,KAAK,QAAQ;YACX,OAAO;;;;;;;;;;;;;iFAaoE,CAAC;QAE9E,KAAK,OAAO;YACV,OAAO;;;;;;;;;;;;;;;;;;;;;oEAqBuD,CAAC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,cAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACtC,MAAM,WAAW,GAAG;YAClB,KAAK;YACL,gBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;YAC/C,kBAAkB,sBAAsB,CAAC,OAAO,CAAC,EAAE;YACnD,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,YAAY,GAAG,oBAAoB,CAAC,OAAO,CAAC;aAC/C,UAAU,CAAC,WAAW,EAAE,WAAW,CAAC;aACpC,UAAU,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;QAChD,MAAM,cAAc,GAAG,qCAAqC,OAAO,KAAK,CAAC;QAEzE,OAAO;YACL,IAAI,EAAE,GAAG,MAAM,4BAA4B,OAAO,KAAK;YACvD,OAAO,EAAE,GAAG,WAAW,OAAO,cAAc,OAAO,YAAY,IAAI;SACpE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/adapters/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/adapters/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAId,MAAM,YAAY,CAAC;AAgCpB;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,GAAE,MAAW,GACvB,aAAa,EAAE,CAmBjB"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/adapters/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAId,MAAM,YAAY,CAAC;AAgCpB;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,GAAE,MAAW,GACvB,aAAa,EAAE,CAyBjB"}

package/dist/adapters/codex.js

@@ -1,5 +1,5 @@
 import { WHYSPEC_COMMANDS, COMMAND_DESCRIPTIONS, } from "./types.js";
-import { generateClaudeCodeSkills } from "./claude-code.js";
+import { getSkillInstructions } from "./claude-code.js";
 function getDisplayName(command) {
     return `WhySpec ${command[0].toUpperCase()}${command.slice(1)}`;
 }
@@ -34,20 +34,23 @@ function renderOpenAiMetadata(command) {
  */
 export function generateCodexSkills(projectRoot = "") {
     const prefix = projectRoot ? `${projectRoot}/` : "";
-    const claudeSkills = generateClaudeCodeSkills().map((file) => {
-        const commandMatch = file.path.match(/whyspec-(plan|execute|capture|show|search|debug)\//);
-        if (!commandMatch) {
-            return file;
-        }
+    const skillFiles = WHYSPEC_COMMANDS.map((command) => {
+        const frontmatter = [
+            "---",
+            `name: whyspec-${command}`,
+            `description: ${COMMAND_DESCRIPTIONS[command]}`,
+            "---",
+        ].join("\n");
+        const instructions = getSkillInstructions(command);
         return {
-            ...file,
-            path: `${prefix}whyspec-${commandMatch[1]}/SKILL.md`,
+            path: `${prefix}whyspec-${command}/SKILL.md`,
+            content: `${frontmatter}\n\n${instructions}\n`,
         };
     });
     const metadataFiles = WHYSPEC_COMMANDS.map((command) => ({
         path: `${prefix}whyspec-${command}/agents/openai.yaml`,
         content: renderOpenAiMetadata(command),
     }));
-    return [...claudeSkills, ...metadataFiles];
+    return [...skillFiles, ...metadataFiles];
 }
 //# sourceMappingURL=codex.js.map

package/dist/adapters/codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/adapters/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,SAAS,cAAc,CAAC,OAAuB;IAC7C,OAAO,WAAW,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAuB;IAC/C,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,gDAAgD,CAAC;QAC1D,KAAK,SAAS;YACZ,OAAO,oDAAoD,CAAC;QAC9D,KAAK,SAAS;YACZ,OAAO,iEAAiE,CAAC;QAC3E,KAAK,MAAM;YACT,OAAO,yEAAyE,CAAC;QACnF,KAAK,QAAQ;YACX,OAAO,oEAAoE,CAAC;QAC9E,KAAK,OAAO;YACV,OAAO,6DAA6D,CAAC;IACzE,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAuB;IACnD,OAAO;mBACU,cAAc,CAAC,OAAO,CAAC;wBAClB,oBAAoB,CAAC,OAAO,CAAC;qBAChC,gBAAgB,CAAC,OAAO,CAAC;CAC7C,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,cAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,MAAM,YAAY,GAAG,wBAAwB,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC3F,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,GAAG,IAAI;YACP,IAAI,EAAE,GAAG,MAAM,WAAW,YAAY,CAAC,CAAC,CAAC,WAAW;SACrD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI,EAAE,GAAG,MAAM,WAAW,OAAO,qBAAqB;QACtD,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC;KACvC,CAAC,CAAC,CAAC;IAEJ,OAAO,CAAC,GAAG,YAAY,EAAE,GAAG,aAAa,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/adapters/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,SAAS,cAAc,CAAC,OAAuB;IAC7C,OAAO,WAAW,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAuB;IAC/C,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,gDAAgD,CAAC;QAC1D,KAAK,SAAS;YACZ,OAAO,oDAAoD,CAAC;QAC9D,KAAK,SAAS;YACZ,OAAO,iEAAiE,CAAC;QAC3E,KAAK,MAAM;YACT,OAAO,yEAAyE,CAAC;QACnF,KAAK,QAAQ;YACX,OAAO,oEAAoE,CAAC;QAC9E,KAAK,OAAO;YACV,OAAO,6DAA6D,CAAC;IACzE,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAuB;IACnD,OAAO;mBACU,cAAc,CAAC,OAAO,CAAC;wBAClB,oBAAoB,CAAC,OAAO,CAAC;qBAChC,gBAAgB,CAAC,OAAO,CAAC;CAC7C,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,cAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpD,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAClD,MAAM,WAAW,GAAG;YAClB,KAAK;YACL,iBAAiB,OAAO,EAAE;YAC1B,gBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;YAC/C,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,YAAY,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAEnD,OAAO;YACL,IAAI,EAAE,GAAG,MAAM,WAAW,OAAO,WAAW;YAC5C,OAAO,EAAE,GAAG,WAAW,OAAO,YAAY,IAAI;SAC/C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI,EAAE,GAAG,MAAM,WAAW,OAAO,qBAAqB;QACtD,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC;KACvC,CAAC,CAAC,CAAC;IAEJ,OAAO,CAAC,GAAG,UAAU,EAAE,GAAG,aAAa,CAAC,CAAC;AAC3C,CAAC"}

package/dist/adapters/types.d.ts

@@ -11,7 +11,9 @@ export interface GeneratedFile {
 /** The 6 WhySpec commands that adapters generate config for. */
 export declare const WHYSPEC_COMMANDS: readonly ["plan", "execute", "capture", "show", "search", "debug"];
 export type WhySpecCommand = (typeof WHYSPEC_COMMANDS)[number];
-/** One-line descriptions for each command, used across all adapters. */
+/** One-line descriptions for each command, used across all adapters.
+ * IMPORTANT: These must be trigger conditions ("Use when..."), not workflow summaries.
+ * Summary descriptions cause Claude to shortcut the skill body. */
 export declare const COMMAND_DESCRIPTIONS: Record<WhySpecCommand, string>;
 /** Gray placeholder text shown beside slash commands in UIs that support it. */
 export declare const COMMAND_ARGUMENT_HINTS: Record<WhySpecCommand, string>;

package/dist/adapters/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,oEAOnB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAO/D,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAOjE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,oEAOnB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D;;mEAEmE;AACnE,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAO/D,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAOjE,CAAC"}

package/dist/adapters/types.js

@@ -7,22 +7,24 @@ export const WHYSPEC_COMMANDS = [
     "search",
     "debug",
 ];
-/** One-line descriptions for each command, used across all adapters. */
+/** One-line descriptions for each command, used across all adapters.
+ * IMPORTANT: These must be trigger conditions ("Use when..."), not workflow summaries.
+ * Summary descriptions cause Claude to shortcut the skill body. */
 export const COMMAND_DESCRIPTIONS = {
-    plan: "Declare intent and plan decisions before coding",
-    execute: "Implement from plan with full reasoning context",
-    capture: "Save the reasoning behind what was built",
-    show: "View the full story of a change with Decision Bridge delta",
-    search: "Search past decisions and reasoning across all changes",
-    debug: "Debug with the scientific method and capture root cause",
+    plan: "Use when planning a code change, capturing decisions before coding, or setting up the Decision Bridge",
+    execute: "Use when starting implementation, continuing work, or executing tasks from a WhySpec plan",
+    capture: "Use after coding to preserve reasoning — resolves the Decision Bridge with actual outcomes",
+    show: "Use when reviewing the full story of a change — intent, design, tasks, and Decision Bridge delta",
+    search: "Use when looking for why something was built a certain way or finding past decisions",
+    debug: "Use when encountering any bug, test failure, or unexpected behavior — before proposing fixes",
 };
 /** Gray placeholder text shown beside slash commands in UIs that support it. */
 export const COMMAND_ARGUMENT_HINTS = {
-    plan: "change description",
-    execute: "change name",
-    capture: "change name",
-    show: "change name",
-    search: "query",
-    debug: "issue description",
+    plan: "<change-name-or-description>",
+    execute: "[change-name]",
+    capture: "[change-name]",
+    show: "[change-name]",
+    search: "<query> [--domain <domain>]",
+    debug: "<bug-description-or-change-name>",
 };
 //# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAWA,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM;IACN,SAAS;IACT,SAAS;IACT,MAAM;IACN,QAAQ;IACR,OAAO;CACC,CAAC;AAIX,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAmC;IAClE,IAAI,EAAE,iDAAiD;IACvD,OAAO,EAAE,iDAAiD;IAC1D,OAAO,EAAE,0CAA0C;IACnD,IAAI,EAAE,4DAA4D;IAClE,MAAM,EAAE,wDAAwD;IAChE,KAAK,EAAE,yDAAyD;CACjE,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAmC;IACpE,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,aAAa;IACtB,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,mBAAmB;CAC3B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAWA,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM;IACN,SAAS;IACT,SAAS;IACT,MAAM;IACN,QAAQ;IACR,OAAO;CACC,CAAC;AAIX;;mEAEmE;AACnE,MAAM,CAAC,MAAM,oBAAoB,GAAmC;IAClE,IAAI,EAAE,uGAAuG;IAC7G,OAAO,EAAE,2FAA2F;IACpG,OAAO,EAAE,4FAA4F;IACrG,IAAI,EAAE,kGAAkG;IACxG,MAAM,EAAE,sFAAsF;IAC9F,KAAK,EAAE,8FAA8F;CACtG,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAmC;IACpE,IAAI,EAAE,8BAA8B;IACpC,OAAO,EAAE,eAAe;IACxB,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,6BAA6B;IACrC,KAAK,EAAE,kCAAkC;CAC1C,CAAC"}

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQlD;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CA8D5E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAwBvE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CA0CjD;AAsED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAoB1D;AAuED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAmBrE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAIpE;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CActD;AAID,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CA8I7C"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQlD;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CA8D5E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAwBvE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CA+BjD;AAsED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAoB1D;AA0FD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAoBrE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAIpE;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CActD;AAID,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAkJ7C"}

package/dist/commands/init.js

@@ -93,40 +93,34 @@ export function writeConfigYaml(root, opts) {
 }
 export function addToGitignore(root) {
     const entry = ".gitwhy/";
-    const gitDir = path.join(root, ".git");
     const gitignorePath = path.join(root, ".gitignore");
+    const gitDir = path.join(root, ".git");
     const gitExcludePath = path.join(gitDir, "info", "exclude");
-    const ensureIgnoreEntry = (filePath) => {
-        if (fs.existsSync(filePath)) {
-            const content = fs.readFileSync(filePath, "utf-8");
-            const lines = content.split("\n");
-            if (lines.some((line) => line.trim() === entry)) {
-                return;
-            }
+    // Always use .gitignore (committed, visible to all agents).
+    // .git/info/exclude is local-only and some agents delete files
+    // listed there on startup, causing data loss.
+    if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, "utf-8");
+        const lines = content.split("\n");
+        if (!lines.some((line) => line.trim() === entry)) {
             const separator = content.endsWith("\n") ? "" : "\n";
-            fs.writeFileSync(filePath, content + separator + entry + "\n", "utf-8");
-            return;
+            fs.writeFileSync(gitignorePath, content + separator + entry + "\n", "utf-8");
         }
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, entry + "\n", "utf-8");
-    };
-    const removeIgnoreEntry = (filePath) => {
-        if (!fs.existsSync(filePath)) {
-            return;
+    }
+    else {
+        fs.writeFileSync(gitignorePath, entry + "\n", "utf-8");
+    }
+    // Migrate: remove from .git/info/exclude if it was previously added there.
+    // This prevents double-ignoring and completes the migration to .gitignore.
+    if (fs.existsSync(gitExcludePath)) {
+        const excludeContent = fs.readFileSync(gitExcludePath, "utf-8");
+        const excludeLines = excludeContent.split("\n");
+        if (excludeLines.some((line) => line.trim() === entry)) {
+            const filtered = excludeLines
+                .filter((line) => line.trim() !== entry);
+            fs.writeFileSync(gitExcludePath, filtered.join("\n"), "utf-8");
         }
-        const content = fs.readFileSync(filePath, "utf-8");
-        const filtered = content
-            .split("\n")
-            .filter((line) => line.trim() !== entry && line.length > 0);
-        const nextContent = filtered.length > 0 ? `${filtered.join("\n")}\n` : "";
-        fs.writeFileSync(filePath, nextContent, "utf-8");
-    };
-    if (fs.existsSync(gitDir)) {
-        ensureIgnoreEntry(gitExcludePath);
-        removeIgnoreEntry(gitignorePath);
-        return;
     }
-    ensureIgnoreEntry(gitignorePath);
 }
 const WHYSPEC_COMMANDS = ["plan", "execute", "capture", "show", "search", "debug"];
 /** Write GeneratedFile[] to disk, creating directories as needed. */
@@ -246,6 +240,21 @@ function installClaudeCommandsFromSkills(root, skillsSourceDir) {
     }
     return installed;
 }
+function removeLegacyClaudeSkills(root) {
+    const skillsRoot = path.join(root, ".claude", "skills");
+    let removed = false;
+    for (const cmd of WHYSPEC_COMMANDS) {
+        const legacyPath = path.join(skillsRoot, `whyspec-${cmd}`);
+        if (fs.existsSync(legacyPath)) {
+            fs.rmSync(legacyPath, { recursive: true, force: true });
+            removed = true;
+        }
+    }
+    if (removed && fs.existsSync(skillsRoot) && fs.readdirSync(skillsRoot).length === 0) {
+        fs.rmdirSync(skillsRoot);
+    }
+    return removed;
+}
 function getSkillsSourceDir() {
     const currentDir = path.dirname(fileURLToPath(import.meta.url));
     return path.join(path.dirname(path.dirname(currentDir)), "skills");
@@ -268,6 +277,7 @@ export function installSkillFiles(root, tools) {
     const skillsDir = getSkillsSourceDir();
     // Claude Code skills
     if (tools.includes("claude-code")) {
+        removeLegacyClaudeSkills(root);
         const commandsInstalled = installClaudeCommandsFromSkills(path.join(root, ".claude", "commands"), skillsDir);
         if (!commandsInstalled) {
             writeGeneratedFiles(root, generateClaudeCodeCommands());
@@ -335,6 +345,10 @@ export async function runInit() {
         // Check if skills need to be installed (e.g. prior crash before skill step)
         if (tools.includes("claude-code")) {
             const commandCheck = path.join(root, ".claude", "commands", "whyspec:plan.md");
+            const removedLegacySkills = removeLegacyClaudeSkills(root);
+            if (removedLegacySkills) {
+                repaired = true;
+            }
             if (!fs.existsSync(commandCheck)) {
                 console.log(chalk.yellow("\n  Repairing missing Claude commands...\n"));
                 installSkillFiles(root, tools);