@kiwidata/grimoire 0.1.1

package/skills/grimoire-branch-guard/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: grimoire-branch-guard
+description: Enforce branch hygiene when starting a new feature. Use when the user requests a new feature and the current branch is dirty, mid-feature, or otherwise unfit for piggy-backing. Creates an appropriately named branch before any drafting or planning begins.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-branch-guard
+
+Force a clean, appropriately named branch before a new feature is drafted. Prevents piggy-backing new scope onto an in-progress branch or dirty tree.
+
+## Triggers
+- User requests a new feature, capability, or behavior change
+- The `grimoire branch-check` UserPromptSubmit hook emits a warning into the prompt context
+- Before `grimoire-draft` runs for a *net-new* change (not an edit to an existing draft)
+- User says: "new feature", "add feature", "build X", "implement X", "let's add", "i want to add"
+
+## Routing
+- Continuing an existing change (editing manifest, revising scenarios) → skip this skill; go straight to `grimoire-draft`
+- Bug fix or refactor → skip; route to `grimoire-bug` or leave branch alone
+- User is on `main`/`master`/`develop`/`trunk` with a clean tree → no hygiene issue; suggest a branch name but do not block
+- User explicitly opts out ("stay on this branch", "piggy-back is fine") → respect it, but surface the risk once and record it in the manifest's Assumptions
+
+## Preconditions
+- Project is a git repository
+- Current working directory is inside the project root (`.grimoire/` or `features/` discoverable upward)
+
+## Workflow
+
+### 1. Snapshot branch state
+Run:
+
+```
+git branch --show-current
+git status --porcelain
+```
+
+Then enumerate active grimoire changes:
+
+```
+grimoire list --changes --json
+```
+
+Record: current branch, dirty-file count, and any active change whose `manifest.md` frontmatter `branch:` matches the current branch.
+
+### 2. Classify the situation
+
+| Condition | Action |
+|-----------|--------|
+| Clean tree + on protected branch (main/master/develop/trunk) | Propose a new branch name, create it, proceed |
+| Clean tree + on feature branch tied to a matching active change | **Block.** This branch belongs to an existing change. Ask: is the request related to that change (edit) or truly new (branch)? |
+| Clean tree + on feature branch with **no** matching active change | Warn that the branch appears stale. Offer: rebase onto main, or create a new branch |
+| Dirty tree (any branch) | **Block.** Require the user to commit, stash, or discard before proceeding |
+| Dirty tree + active change on this branch | **Block hard.** Finish the in-progress change (or commit WIP) before drafting a new one |
+
+### 3. Propose a branch name
+Derive a slug from the user's request. Use the `feat/` prefix for features, `chore/` for chores, `refactor/` for refactors. Examples:
+
+- "Add password reset flow" → `feat/password-reset`
+- "Let's build a CSV export" → `feat/csv-export`
+- "I want to add rate limiting to the API" → `feat/api-rate-limiting`
+
+Keep slugs short (≤40 chars), lowercase, hyphen-separated. Prefer nouns from the request. Avoid including the verb ("add", "new") in the slug.
+
+Confirm the name with the user before creating the branch.
+
+### 4. Create the branch
+
+If dirty, first help the user resolve:
+
+- **Commit WIP**: `git commit -am "wip: <summary>"` (only if changes belong to the current feature)
+- **Stash**: `git stash push -m "wip before <new-feature-slug>"`
+- **Discard**: only if user explicitly says so
+
+Then create and switch:
+
+```
+git switch -c <proposed-slug>
+```
+
+Or, if starting from something other than the default branch:
+
+```
+git switch main && git pull --ff-only && git switch -c <proposed-slug>
+```
+
+### 5. Hand off to `grimoire-draft`
+Once on the new branch with a clean tree, invoke `grimoire-draft`. In the draft's `manifest.md`, set the `branch:` frontmatter field to the new branch name so future prompts can match.
+
+## Do-not
+- **Do not** draft, plan, or edit specs while the branch guard is active and the conditions above are not met.
+- **Do not** silently create a branch without confirming the name with the user.
+- **Do not** force-delete uncommitted work. When in doubt, stash.
+- **Do not** piggy-back features onto a branch whose manifest describes a different change. This violates grimoire's one-branch-one-change assumption and breaks the `Change:` trailer audit trail.
+- **Do not** override the guard for a single clarifying exchange (e.g., "what's the schema for X?" is not a new-feature request).
+
+## Configuration
+- Intent patterns live in `src/core/branch-check.ts` (`NEW_FEATURE_PATTERNS`). If the hook is over- or under-triggering, adjust there.
+- Protected branches: `main`, `master`, `develop`, `trunk`. Add project-specific defaults in `.grimoire/config.yaml` under `project.protected_branches` (if/when implemented).
+
+## Rationale
+A branch that bundles two features makes every downstream grimoire artifact ambiguous:
+
+- The `Change:` commit trailer points at one change, not both
+- `manifest.md` frontmatter has one `branch:` field, so only one change can claim it
+- `grimoire check --changed` cannot tell which scenarios back which code
+- PR review (`grimoire-pr-review`) cannot isolate the diff for a single change
+
+Forcing a dedicated branch up front is cheaper than untangling a mixed branch later.

package/skills/grimoire-bug/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: grimoire-bug
+description: Disciplined bug fix workflow with reproduction-first methodology. Use when the user reports a bug or defect that needs fixing.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-bug
+
+Disciplined bug fix workflow: reproduce first, then fix. Every bug gets a failing test before any code changes.
+
+## Triggers
+- User reports a bug, defect, or unexpected behavior
+- User says something is "broken", "wrong", "not working"
+- Loose match: "bug", "fix", "broken", "defect", "issue", "regression"
+
+## Routing
+- Tester/non-developer reporting a bug → `grimoire-bug-report`
+- Feature request disguised as a bug → `grimoire-draft`
+- Performance issue → handle directly (profiling, not repro test)
+- Configuration error → just fix the config
+
+## Workflow
+
+### 1. Understand the Bug
+Get enough information to reproduce:
+- **What happened** — the actual behavior
+- **What should happen** — the expected behavior
+- **How to trigger it** — steps to reproduce
+
+If the user's report is vague, ask one clarifying question. Don't start fixing until you can describe the reproduction steps.
+
+### 2. Classify the Bug
+
+**Check existing feature files** — `grep -rn '<keyword from bug>' features/` to find scenarios describing the expected behavior.
+
+**Scenario exists** → The spec is right, the code is wrong. This is a pure implementation bug. Skip to step 3.
+
+**No scenario covers this behavior** → The bug reveals a gap in the specs. This is a missing scenario. Before fixing:
+1. Write a new scenario (or add to an existing feature) that describes the correct behavior
+2. Add it directly to `features/` (not through a full grimoire change — this is a gap fill, not new functionality)
+3. Note in a comment or commit message that this scenario was added to cover a discovered bug
+
+**Scenario is wrong** → Rare, but possible. The spec itself describes incorrect behavior. Flag this to the user — it may need a grimoire draft to update the feature properly.
+
+### 3. Write a Reproduction Test
+Before touching any production code:
+
+1. Write a step definition (or unit test if no BDD scenario applies) that exercises the exact bug conditions
+2. Run it — **it MUST FAIL**, reproducing the bug
+3. If it passes, your test doesn't actually reproduce the bug. Fix the test until it fails for the right reason.
+
+This is non-negotiable. A bug fix without a reproduction test is a guess that might work. A failing test is proof you understand the problem.
+
+### 4. Document the Bug
+Create a brief record in the test or commit. No separate tracking file needed — the test IS the documentation.
+
+The reproduction test should make the bug obvious:
+```gherkin
+# Bug: users with special characters in email can't reset password
+Scenario: Password reset with plus-sign email
+  Given a user exists with email "test+alias@example.com"
+  When they request a password reset
+  Then they should receive a reset email
+```
+
+Or as a unit test comment:
+```python
+def test_password_reset_special_chars():
+    """Bug: email addresses with + were being URL-encoded in the reset
+    link, causing lookup failures. Reported 2026-04-05."""
+```
+
+The commit message should reference the bug:
+```
+fix(auth): handle special characters in password reset emails
+
+Plus signs in email addresses were URL-encoded during reset link
+generation, causing user lookup to fail on the reset page.
+
+Added scenario: "Password reset with plus-sign email"
+```
+
+### 5. Create Fix Branch
+Before writing any code, create a branch for the fix:
+```
+fix/<short-description>
+```
+For example: `fix/special-chars-password-reset`, `fix/null-pricing-response`.
+
+### 6. Fix the Bug
+Now — and only now — modify production code:
+
+1. Make the smallest change that fixes the failing test
+2. Run the reproduction test — it should pass
+3. Run ALL existing tests — no regressions
+4. If the fix is more than a few lines, pause and consider whether the approach is the simplest one
+
+**Escalation guard:** If the fix requires changes to more than 3 files, introduces new abstractions, modifies data models, or crosses service boundaries — STOP. This is not a bug fix, it's a change that needs design. Tell the user: "This fix is larger than a typical bug fix. I recommend routing to `grimoire-draft` to handle this as a proper change with specs and a plan." The user can override.
+
+### 7. Verify
+- Reproduction test passes (`config.tools.bdd_test`)
+- All existing feature scenarios pass (`config.tools.bdd_test`)
+- All existing unit/integration tests pass (`config.tools.unit_test`)
+- If a new scenario was added in step 2, it passes with the fix
+
+### 8. Tester Verification Checklist
+
+After the fix, generate a checklist for testers to verify the fix and check for regressions. This bridges the gap between "developer says it's fixed" and "tester confirms it's fixed."
+
+1. **Confirm the original bug** — restate the exact reproduction steps from the report and what the tester should now see instead.
+
+2. **Check related areas** — identify 3-5 areas that could have been affected by the fix:
+   - Other scenarios in the same feature file
+   - Features that share the same code path or data (check what the fix touched)
+   - Edge cases near the fix — if you fixed a null check, what about empty strings? If you fixed one role, what about other roles?
+
+3. **Generate the checklist:**
+```markdown
+## Verification Checklist: <bug-id>
+Fix branch: `fix/<name>`
+
+### Original Bug
+- [ ] Reproduce the original steps: <steps>
+- [ ] Confirm expected behavior: <what should happen now>
+
+### Regression Checks
+- [ ] <related scenario or area>: <what to verify>
+- [ ] <related scenario or area>: <what to verify>
+- [ ] <related scenario or area>: <what to verify>
+```
+
+4. **Include in bug report** — append the checklist to `.grimoire/bugs/<bug-id>/report.md` (or the triage file if it exists) so the tester can find it.
+
+5. If an external ticket exists, post the checklist as a comment so the tester doesn't need to look at local files.
+
+### 9. Summary
+Report to the user:
+- What the bug was (root cause, not symptoms)
+- What was changed (files and what specifically)
+- Whether a new scenario was added to cover the gap
+- Test results
+- The verification checklist for testers (from step 8)
+
+## When NOT to Use This Skill
+- **Feature requests disguised as bugs** — "it's broken because it doesn't do X" when X was never specified. Route to `grimoire-draft`.
+- **Performance issues** — these usually need profiling, not a repro test. Handle directly.
+- **Configuration errors** — wrong env vars, missing dependencies, bad setup. Just fix the config.
+
+## Important
+- **Reproduce before you fix.** No exceptions. If you can't reproduce it, you don't understand it, and your fix is a guess.
+- **Small fixes only.** If the bug fix requires significant architectural changes, it's not a bug fix — route to `grimoire-draft` for a proper change.
+- **Don't over-document.** The test is the documentation. A one-line comment in the test explaining the bug is enough. Don't create tracking files, bug reports, or manifests for a bug fix.
+- **The feature file is truth.** If a scenario describes behavior the user now says is wrong, that's a spec change, not a bug. Handle it through `grimoire-draft`.
+- **One bug, one fix.** Don't bundle "while I'm in here" improvements with a bug fix. Fix the bug, nothing more.
+
+## Done
+When the bug is fixed, tests pass (reproduction + regression), and the summary is presented, the workflow is complete. Suggest `grimoire-commit` for the fix commit.

package/skills/grimoire-bug-explore/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: grimoire-bug-explore
+description: AI-guided exploratory testing that finds gaps in feature coverage, generates edge case scenarios, and identifies untested paths. Use when you want to proactively find bugs before users do.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-bug-explore
+
+AI-guided exploratory testing. Systematically analyze feature specs and code to find untested edge cases, missing negative scenarios, and potential failure modes — before they become bug reports.
+
+## Triggers
+- User wants to find gaps in test coverage
+- User says "what are we missing?", "explore for bugs", "what could break?"
+- Loose match: "exploratory testing", "edge cases", "negative scenarios", "what's untested", "find gaps"
+- User says "onboard", "where do I start testing?", "what's risky?" → onboard mode
+
+## Routing
+- Want a focused, timeboxed testing session with live tracking → `grimoire-bug-session`
+- Found a specific bug during exploration → `grimoire-bug-report` to file it
+- Want to fix a known bug → `grimoire-bug`
+- Analyzing a filed bug report → `grimoire-bug-triage`
+
+## Prerequisites
+- A grimoire project with feature files in `features/`
+- For developer mode: code exists to analyze (not just specs)
+- For tester/onboard mode: feature files are sufficient
+
+## Modes
+
+This skill operates in three modes:
+
+- **Tester mode** (default) — Spec-only analysis. Gap analysis, negative scenarios, cross-feature risks, and existing automation coverage. No code reading required. Suitable for testers who don't read source code.
+- **Developer mode** — activated by `--deep`, or when the user is a developer. Adds code-level analysis (Step 3) on top of everything in tester mode.
+- **Onboard mode** — activated by `--onboard` or when a tester is new to the project. Generates a tester's guide: feature areas ranked by risk, what's automated vs manual, recent changes, and open bugs.
+
+## Workflow
+
+### 1. Choose Scope
+
+Ask the user what to explore:
+
+- **Specific feature area** — e.g., "explore auth" → focus on `features/auth/` and its implementation
+- **Recent changes** — explore areas touched by recent commits (use `git log --since` to find them)
+- **Full sweep** — analyze all feature areas (warn that this takes longer)
+
+If the user doesn't specify, default to recent changes — that's where bugs most likely live.
+
+### 2. Analyze Feature Specs
+
+For each feature file in scope:
+
+**Gap analysis:**
+- Read every scenario. What behaviors are specified?
+- What behaviors are conspicuously absent?
+  - **Error cases** — what happens when input is invalid, empty, too long, wrong type?
+  - **Boundary conditions** — what about zero, one, max, max+1? Empty lists? Unicode? Special characters?
+  - **State transitions** — what about concurrent access? Partial failures? Interrupted operations?
+  - **Permissions** — what about unauthorized users? Wrong role? Expired session?
+  - **Timing** — what about timeouts? Retries? Race conditions? Clock skew?
+
+**Negative scenario generation:**
+For each scenario that describes a happy path, generate the corresponding negative scenarios:
+```
+Happy: "User logs in with valid credentials"
+Missing negatives:
+  - Login with wrong password
+  - Login with nonexistent email
+  - Login with empty fields
+  - Login with account locked
+  - Login with expired password
+  - Login after too many failed attempts
+```
+
+### 2b. Map Automation Coverage
+
+Help the tester understand what's already automated and what requires manual testing.
+
+For each feature file in scope:
+1. **Find step definitions** — grep the test directory for step text patterns from each scenario (e.g., `grep -rn 'valid credentials' tests/` for a step `Given I have entered valid credentials`)
+2. **Classify each scenario:**
+   - **Automated** — has step definitions with real assertions (not `pass` or `assert True`)
+   - **Partially automated** — has step definitions but some steps are stubs or have weak assertions
+   - **Not automated** — no step definitions found, or all steps are stubs
+3. **Identify automation gaps** — scenarios that exist in specs but have no test automation. These are the things that must be tested manually today.
+4. **Identify manual-only areas** — behaviors that are hard to automate (visual layout, UX feel, accessibility, real-device behavior). Flag these as intentionally manual.
+
+Present this as a coverage map:
+```markdown
+## Automation Coverage: <area>
+
+### Automated (N scenarios)
+- ✅ "Scenario name" — `test_file.py:42` (strong assertions)
+
+### Partially Automated (N scenarios)
+- ⚠️ "Scenario name" — `test_file.py:58` (weak: only checks `is not None`)
+  - Manual check needed: verify the actual values match expected behavior
+
+### Not Automated (N scenarios)
+- ❌ "Scenario name" — needs manual testing
+  - Suggested manual test: <brief description of what to check>
+
+### Intentionally Manual
+- 🖐 Visual/UX checks, accessibility, cross-device behavior
+```
+
+This map tells the tester: "Here's what the robots check for you. Here's what only you can catch."
+
+### 3. Analyze Implementation (Developer Mode Only)
+
+> **Skip this step in tester mode.** This requires reading source code.
+
+Read the code that implements the features in scope:
+
+**Code-level gap detection:**
+- Find error handling paths — are they tested by any scenario?
+- Find conditional branches — is every branch exercised by a scenario?
+- Find input validation — is each validation rule covered by both a passing and failing test?
+- Find external calls (APIs, databases, file I/O) — are failure modes covered?
+- Find configuration-dependent behavior — are different config values tested?
+
+**Anti-pattern detection:**
+- Catch blocks that swallow errors silently
+- Default values that mask missing data
+- Type coercion that could hide mismatches
+- Fallback behavior that's never tested
+
+### 4. Cross-Feature Interaction
+
+Look for interactions between features that might not be tested:
+
+- Feature A changes state that Feature B depends on — is that handoff tested?
+- Shared data models modified by multiple features — are conflicts possible?
+- Ordering dependencies — does Feature B assume Feature A ran first?
+
+### 5. Generate Findings Report
+
+Present findings organized by risk, not by area:
+
+```markdown
+# Exploratory Testing: <scope>
+Date: <YYYY-MM-DD>
+
+## Critical Gaps (likely bugs or high-impact missing coverage)
+- **<area>**: <description of what's missing and why it matters>
+  - Missing scenario: `<suggested Given/When/Then>`
+  - Risk: <what could go wrong>
+
+## Edge Cases (boundary conditions not covered)
+- **<area>**: <description>
+  - Missing scenario: `<suggested Given/When/Then>`
+
+## Negative Scenarios (error paths not tested)
+- **<area>**: <description>
+  - Missing scenario: `<suggested Given/When/Then>`
+
+## Cross-Feature Risks (interaction effects)
+- **<area A> × <area B>**: <description of potential interaction issue>
+
+## Summary
+- <N> critical gaps found
+- <N> edge cases identified
+- <N> negative scenarios missing
+- <N> cross-feature risks noted
+```
+
+### 6. Act on Findings
+
+For each finding, offer the user a choice:
+
+- **Write the scenario now** — add a `.feature` scenario covering the gap. This can be done directly (gap fill, like `grimoire-bug` does for spec gaps) without a full grimoire change.
+- **File a bug report** — if the finding looks like it might already be broken, use `grimoire-bug-report` to file it.
+- **Add to backlog** — note it for later. Don't force action on everything.
+- **Dismiss** — the user decides this isn't worth covering.
+
+Batch similar findings — "these 5 missing negative scenarios can all go in one new scenario outline" is better than creating 5 separate items.
+
+### 7. Browser-Based Exploration (Optional)
+
+If a Playwright MCP server or browser automation tool is available:
+
+1. Read the feature scenarios to understand expected flows
+2. Execute the flows in an actual browser
+3. Try variations: wrong inputs, fast clicking, back button, expired sessions
+4. Capture any unexpected behavior as findings
+
+This is optional and only available if the project has browser testing infrastructure configured. Don't suggest it if there's no way to run it.
+
+### 8. Onboard Mode (--onboard)
+
+When a tester is new to the project, generate a tester's orientation guide instead of a gap analysis.
+
+1. **Inventory feature areas** — read all feature files and group by area/directory. For each area, summarize what it covers in one sentence.
+
+2. **Rank by risk** — assign a risk level to each area based on:
+   - **Recent changes** — `git log --since="2 weeks ago"` the feature area's implementation files. Recently changed = higher risk.
+   - **Open bugs** — check `.grimoire/bugs/` for unresolved reports in each area.
+   - **Sparse coverage** — areas with few scenarios relative to their complexity (e.g., 2 scenarios covering an entire payment flow).
+   - **No automation** — areas where scenarios have no step definitions (from step 2b).
+
+3. **Map automation coverage** — for each area, run step 2b and summarize: "Auth: 12 scenarios, 10 automated, 2 manual. Payments: 8 scenarios, 3 automated, 5 manual."
+
+4. **Highlight recent changes** — list files changed in the last 2 weeks with their feature area. These are where regressions most likely live.
+
+5. **Generate the guide:**
+```markdown
+# Tester's Guide: <project name>
+Generated: <YYYY-MM-DD>
+
+## Feature Areas (ranked by risk)
+
+### 🔴 High Risk
+- **<area>** — <summary>. <N> scenarios (<N> automated, <N> manual). <reason for high risk>.
+
+### 🟡 Medium Risk
+- **<area>** — <summary>. <N> scenarios (<N> automated, <N> manual). <reason>.
+
+### 🟢 Low Risk
+- **<area>** — <summary>. <N> scenarios (<N> automated, <N> manual).
+
+## Recent Changes (last 2 weeks)
+- <area>: <what changed> (<commit date>)
+
+## Open Bugs
+- <bug-id>: <title> (<area>, <severity>)
+
+## Where to Start
+<Recommend the tester start with the highest-risk area that has the least automation — that's where manual testing adds the most value.>
+```
+
+## Important
+- **This is exploration, not audit.** The goal is to find what's missing, not to grade coverage. Frame findings as opportunities, not failures.
+- **Prioritize by risk.** A missing error scenario on a payment flow matters more than a missing edge case on a settings page. Lead with what could hurt users.
+- **Suggest scenarios, don't just flag gaps.** "Missing negative scenario for login" is less useful than a concrete Given/When/Then that the team can evaluate.
+- **Respect existing coverage.** If an area is well-covered, say so. Don't manufacture findings for completeness.
+- **Don't duplicate test-quality.** `grimoire verify` already checks assertion strength and test anti-patterns. This skill focuses on missing coverage, not weak tests.
+- **Scope matters.** A full-sweep exploration of a large codebase will produce a lot of findings. Help the user prioritize rather than dumping everything on them.
+
+## Done
+When the findings report is presented and the user has acted on findings (write scenarios, file bugs, defer, or dismiss), the workflow is complete. Suggest follow-up actions based on findings.