@gitwhy-cli/whyspec 0.1.17 → 0.1.19

package/skills/whyspec-execute/SKILL.md

@@ -1,118 +0,0 @@
----
-name: whyspec-execute
-description: Implement a planned change using intent and design as context. Use when the user wants to start implementing, continue work, or execute tasks from a WhySpec plan.
----
-
-Implement a change — read the plan, work through tasks, commit atomically.
-
-When all tasks are done, run `/whyspec-capture` to save your reasoning.
-
----
-
-**Input**: Optionally specify a change name. If omitted, auto-detect or prompt for available changes.
-
-**Steps**
-
-1. **Select the change**
-
-   If a name is provided, use it. Otherwise:
-   - Auto-select if only one active change exists
-   - If multiple changes exist, run `whyspec list --json` and use **AskUserQuestion** to let the user select
-
-   Always announce: "Executing change: **<name>**"
-
-2. **Load execution context**
-
-   ```bash
-   whyspec execute --json "<name>"
-   ```
-
-   Parse the JSON response:
-   - `change_name`: The change being executed
-   - `intent`: Content of intent.md
-   - `design`: Content of design.md
-   - `tasks`: Content of tasks.md
-   - `progress`: `{ total, completed, remaining }`
-   - `pending_tasks`: Array of uncompleted tasks
-
-3. **Read plan files for context**
-
-   Read the full content of these files from the change folder:
-   - `intent.md` — understand WHY this change exists, what constraints apply
-   - `design.md` — understand HOW to approach it, what decisions are pending
-   - `tasks.md` — understand WHAT to implement and how to verify
-
-   Keep intent and design in mind throughout implementation. When making a decision during coding, check if it's listed under "Decisions to Make" — you're resolving the Decision Bridge in real-time.
-
-4. **Show current progress**
-
-   ```
-   ## Executing: <name>
-
-   Progress: N/M tasks complete
-   Remaining:
-   - [ ] Task description 1
-   - [ ] Task description 2
-   ...
-   ```
-
-5. **Implement tasks sequentially**
-
-   For each pending task:
-
-   a. Show: `Working on task N/M: <description>`
-   b. Implement the code changes
-   c. Mark task complete in tasks.md: `- [ ]` → `- [x]`
-   d. Run the task's `verify:` check if one is defined
-   e. Commit atomically — one commit per task or logical unit
-   f. Continue to next task
-
-   **Pause if:**
-   - Task is unclear or ambiguous → use **AskUserQuestion** to clarify before implementing
-   - Implementation reveals a design issue → suggest updating design.md, ask user how to proceed
-   - Task contradicts the stated intent → flag the contradiction to the user
-   - Error or blocker encountered → report what happened and wait for guidance
-   - You're unsure about a "Decision to Make" from design.md → ask the user to resolve it
-
-6. **On completion**
-
-   When all tasks are done:
-
-   ```
-   ## Implementation Complete
-
-   Change: <name>
-   Progress: M/M tasks complete
-
-   Completed:
-   - [x] Task 1: description
-   - [x] Task 2: description
-   ...
-
-   Ready to capture reasoning? Run /whyspec-capture
-   ```
-
-   If paused before completion:
-
-   ```
-   ## Implementation Paused
-
-   Change: <name>
-   Progress: N/M tasks complete
-
-   Issue: <what caused the pause>
-
-   Resume with: /whyspec-execute <name>
-   ```
-
-   **Always end with the capture prompt** — the reasoning is freshest right after implementation.
-
-**Guardrails**
-
-- **Read intent.md before coding** — every implementation decision should align with the stated intent and constraints.
-- **Never skip tasks** — work through all tasks in order. If a task seems unnecessary, ask the user to remove it rather than silently skipping.
-- **Commit atomically** — one commit per task or logical unit. Don't batch all changes into one commit.
-- **Pause on unclear tasks** — don't guess at ambiguous requirements. Ask for clarification.
-- **Pause on design issues** — if reality doesn't match the plan, stop and suggest design.md updates before continuing.
-- **Mark checkboxes immediately** — update tasks.md after each task completion, not at the end.
-- **Always prompt capture** — end every execution session (complete or paused) with the `/whyspec-capture` suggestion.

package/skills/whyspec-plan/SKILL.md

@@ -1,170 +0,0 @@
----
-name: whyspec-plan
-description: Plan a change by declaring intent, design, and tasks before coding. Use when the user wants to plan what to build, capture decisions that need to be made, or set up the Decision Bridge before implementation.
----
-
-Plan a change — create intent.md, design.md, and tasks.md with the Decision Bridge.
-
-When ready to implement, run `/whyspec-execute`
-
----
-
-**Input**: A change name (kebab-case) or description of what to build.
-
-**Steps**
-
-1. **Ask forcing questions before anything else**
-
-   Do NOT create any files yet. Use the **AskUserQuestion tool** to ask these questions — they shape the entire plan:
-
-   First ask:
-   > "What problem does this solve? Who feels this pain today?"
-
-   Then, building on their answer:
-   > "What constraints exist? (technical limits, timeline, dependencies, things that can't change)"
-
-   Finally:
-   > "How will you know it works? What does success look like?"
-
-   If the user provides a rich description upfront that already answers these, you may condense to one clarifying question. But never skip entirely.
-
-2. **Create the change folder**
-
-   Derive a kebab-case name from the user's input (e.g., "add user authentication" → `add-user-auth`).
-
-   ```bash
-   whyspec plan --json "<name>"
-   ```
-
-   Parse the JSON response:
-   - `path`: The change directory (e.g., `.gitwhy/changes/add-auth/`)
-   - `templates`: Template content for intent.md, design.md, tasks.md
-   - `context`: Project context from config.yaml (constraints for you — do NOT copy into files)
-   - `rules`: Project-specific rules (constraints for you — do NOT copy into files)
-
-   If a change with that name already exists, use **AskUserQuestion** to ask: continue the existing change, or create a new one with a different name?
-
-3. **Create intent.md**
-
-   Write to `<path>/intent.md`. Populate using the user's answers to the forcing questions:
-
-   ```markdown
-   ## Why This Change Exists
-
-   [Problem statement — from forcing question 1. Be specific about who feels the pain.]
-
-   ## What It Enables
-
-   [Capabilities this unlocks. What becomes possible that wasn't before?]
-
-   ## Decisions to Make
-
-   - [ ] [Decision 1: option A vs option B?]
-   - [ ] [Decision 2: approach X vs approach Y?]
-   - [ ] [Decision 3: ...]
-
-   These checkboxes form the "before" side of the Decision Bridge.
-   They will be resolved during /whyspec-capture after implementation.
-
-   ## Constraints
-
-   [From forcing question 2 — technical limits, non-negotiables, dependencies]
-
-   ## Success Looks Like
-
-   [From forcing question 3 — observable outcomes, acceptance criteria]
-
-   ## Assumptions
-
-   [What we're assuming is true but haven't verified]
-   ```
-
-   **IMPORTANT**: The "Decisions to Make" checkboxes are the Decision Bridge. Every design choice that isn't settled yet MUST be listed here. These get resolved in the context file after implementation.
-
-4. **Create design.md**
-
-   Write to `<path>/design.md`:
-
-   ```markdown
-   ## Approach
-
-   [Chosen technical direction — 2-3 sentences on the high-level strategy]
-
-   ## Trade-off Matrix
-
-   | Option | [Criterion 1] | [Criterion 2] | [Criterion 3] |
-   |--------|---------------|---------------|---------------|
-   | Option A | ... | ... | ... |
-   | Option B | ... | ... | ... |
-
-   ## Architecture
-
-   [ASCII diagram showing the design — components, data flow, boundaries]
-
-   ## Questions to Resolve
-
-   - [ ] [Open question needing an answer before or during coding]
-   - [ ] [Another open question]
-
-   ## Risks & Unknowns
-
-   - [What could go wrong]
-   - [What we don't know yet]
-
-   ## Dependencies
-
-   - [External libraries, APIs, services, other teams' work]
-   ```
-
-5. **Create tasks.md**
-
-   Write to `<path>/tasks.md`. **Define verification FIRST** — goal-backward planning means you know what success looks like before listing tasks:
-
-   ```markdown
-   ## Verification
-
-   What proves this change works — defined BEFORE tasks:
-
-   - [ ] [Verification criterion 1 — e.g., "all auth tests pass"]
-   - [ ] [Verification criterion 2 — e.g., "login flow works end-to-end"]
-
-   ## Tasks
-
-   - [ ] Task 1: [description]
-     verify: [how to verify this specific task]
-   - [ ] Task 2: [description]
-     verify: [verification step]
-   - [ ] Task 3: [description]
-     verify: [verification step]
-   ```
-
-   Each task should be small enough for one atomic commit. Include a `verify:` line where meaningful.
-
-6. **Show summary**
-
-   Display:
-
-   ```
-   ## Plan Created: <name>
-
-   <path>/
-     intent.md    — WHY: problem, constraints, success criteria
-     design.md    — HOW: approach, trade-offs, decisions to make
-     tasks.md     — WHAT: verification criteria + implementation checklist
-
-   Decisions to make: N pending
-   Questions to resolve: N open
-   Tasks: N defined
-
-   Ready to implement? Run /whyspec-execute
-   ```
-
-**Guardrails**
-
-- **Ask forcing questions FIRST** — never create files before asking. The questions shape the plan quality.
-- **Don't implement code** — this skill creates plan files only. Implementation happens in `/whyspec-execute`.
-- **Don't skip "Decisions to Make"** — every unsettled design choice must be a checkbox. These are the Decision Bridge. If the user hasn't mentioned trade-offs, ask: "What decisions haven't been made yet?"
-- **Use CLI-as-oracle** — always call `whyspec plan --json` to create the folder. Don't create paths or generate IDs manually.
-- **Apply `context` and `rules` as constraints** — they guide your writing but must NOT appear in the output files.
-- **Verification before tasks** — in tasks.md, define what "done" looks like before listing the work to do.
-- **Don't over-design** — if the user describes a small fix, create proportionally small plan files. Not every change needs a full trade-off matrix.

package/skills/whyspec-search/SKILL.md

@@ -1,69 +0,0 @@
----
-name: whyspec-search
-description: Search past reasoning, decisions, and contexts across all changes. Use when looking for why something was built a certain way, finding past decisions, or discovering institutional knowledge.
----
-
-Search reasoning — find past decisions, contexts, and intent across all changes.
-
----
-
-**Input**: A search query string. Optionally include `--domain <domain>` to filter by domain.
-
-**Steps**
-
-1. **Run the search**
-
-   ```bash
-   whyspec search --json "<query>"
-   ```
-
-   If a domain filter is specified:
-   ```bash
-   whyspec search --json "<query>" --domain "<domain>"
-   ```
-
-   Parse the JSON response — an array of scored results, each containing:
-   - `id`: Context ID (e.g., `ctx_a1b2c3d4`) or file identifier
-   - `title`: Context or intent title
-   - `change_name`: Name of the change
-   - `domain`: Auto-detected or specified domain
-   - `score`: Relevance score (title=100, reasoning=30, files=20, general=10)
-   - `matched_sections`: Which sections matched (title, reasoning, files, etc.)
-   - `path`: File path for retrieval
-   - `snippet`: Most relevant text excerpt
-
-2. **Display results with scores and snippets**
-
-   ```
-   ## Search: "<query>"
-
-   Found N results:
-
-   1. [score: 130] **JWT Authentication Setup** (add-auth)
-      Domain: authentication | Matched: title, reasoning
-      > "Chose RS256 over HS256 — allows key rotation without redeploying"
-
-   2. [score: 30] **Database Migration Plan** (migrate-db)
-      Domain: database | Matched: reasoning
-      > "Considered token storage in DB but rejected — latency concerns"
-
-   3. [score: 20] **API Rate Limiting** (add-rate-limits)
-      Domain: api | Matched: files
-      > "src/auth/middleware.ts — modified"
-   ```
-
-   For each result, show the most relevant decision or reasoning snippet — not just the title.
-
-3. **Offer follow-up actions**
-
-   After displaying results:
-   - "View full story: `/whyspec-show <change-name>`"
-   - "Narrow by domain: `/whyspec-search \"<query>\" --domain <domain>`"
-
-**Guardrails**
-
-- **Always show scores** — include the relevance score so the user understands why results are ranked.
-- **Always show snippets** — the reasoning excerpt is more useful than titles alone. Show the most relevant decision or trade-off text.
-- **Handle empty results clearly** — if nothing matches, say "No results found for '<query>'" and suggest broader search terms or different keywords.
-- **Don't fabricate results** — only display what the CLI returns. Never synthesize or guess at matches.
-- **Search includes plan files** — the CLI searches intent.md and design.md too, not just context files. This finds planned decisions that haven't been captured yet.

package/skills/whyspec-show/SKILL.md

@@ -1,90 +0,0 @@
----
-name: whyspec-show
-description: Display the full story of a change — intent, design, tasks, and reasoning — with the Decision Bridge delta showing how decisions evolved from plan to implementation.
----
-
-Show the full story — from intent through design, tasks, and reasoning — with the Decision Bridge delta.
-
----
-
-**Input**: A change name. If omitted, prompt for available changes.
-
-**Steps**
-
-1. **Get the full story from CLI**
-
-   ```bash
-   whyspec show --json "<name>"
-   ```
-
-   Parse the JSON response:
-   - `intent`: Content of intent.md
-   - `design`: Content of design.md
-   - `tasks`: Content of tasks.md with completion status
-   - `context`: Content of ctx_<id>.md (if captured)
-   - `decision_bridge_delta`: Computed delta of planned vs actual decisions
-   - `surprises`: Decisions not in the original plan
-
-   If no change name provided:
-   - Run `whyspec list --json` to get available changes
-   - Use **AskUserQuestion** to let the user select
-
-2. **Display the full story as a narrative arc**
-
-   ```
-   # <Change Name>
-
-   ## Intent (WHY)
-
-   [From intent.md — problem statement, what it enables, constraints, success criteria]
-
-   ## Design (HOW)
-
-   [From design.md — approach, architecture, trade-offs considered]
-
-   ## Tasks (WHAT)
-
-   [From tasks.md — task list with completion status]
-   Progress: N/M tasks complete
-
-   ## Reasoning (AFTER)
-
-   [From ctx_<id>.md — story of what happened, decisions made, trade-offs accepted]
-   ```
-
-   If context hasn't been captured yet, show:
-   ```
-   ## Reasoning (AFTER)
-
-   Not yet captured. Run /whyspec-capture to complete the story.
-   ```
-
-3. **Highlight the Decision Bridge Delta**
-
-   When both plan files and context exist, display the evolution:
-
-   ```
-   ## Decision Bridge
-
-   | Decision | Planned (Before) | Actual (After) | Status |
-   |----------|-------------------|----------------|--------|
-   | Token storage | cookie vs localStorage? | httpOnly cookie — XSS protection | Resolved |
-   | Hashing algorithm | bcrypt vs argon2? | bcrypt — better library support | Resolved |
-   | Session strategy | JWT vs server-side? | JWT — no session store needed | Resolved |
-   | [Unresolved item] | X vs Y? | — | Pending |
-
-   ### Surprises (not in original plan)
-
-   - Added 2FA — security review required it
-   - Added rate limiting on login — discovered during load testing
-   ```
-
-   The delta is the most valuable output of `/whyspec-show` — it reveals how thinking evolved from plan to reality.
-
-**Guardrails**
-
-- **Show all available phases** — always display intent, design, tasks, and context (if present). Don't skip sections even if they're short.
-- **Always show the Decision Bridge delta** — when both plan and context exist, the delta table is mandatory. It's the core differentiator.
-- **Handle missing files gracefully** — if some files don't exist, show what's available and note what's missing. Suggest the appropriate command to fill gaps.
-- **Read-only** — this skill displays information. It never modifies files.
-- **Show completion status** — for tasks, always show N/M complete. For the Decision Bridge, show how many decisions were resolved vs pending.