safeword 0.8.4 → 0.8.6

package/templates/skills/safeword-brainstorming/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: brainstorming
+description: Use before implementation when refining rough ideas into specs. Guides collaborative design through Socratic questioning, alternative exploration, and incremental validation. Triggers: 'brainstorm', 'design', 'explore options', 'figure out', 'think through', 'what approach'.
+allowed-tools: '*'
+---
+
+# Brainstorming Ideas Into Specs
+
+Turn rough ideas into validated specs through Socratic dialogue.
+
+**Iron Law:** ONE QUESTION AT A TIME. EXPLORE ALTERNATIVES BEFORE DECIDING.
+
+## When to Use
+
+Answer IN ORDER. Stop at first match:
+
+1. Rough idea needs refinement? → Use this skill
+2. Multiple approaches possible? → Use this skill
+3. Unclear requirements? → Use this skill
+4. Clear task, obvious approach? → Skip (use enforcing-tdd directly)
+5. Pure research/investigation? → Skip
+
+---
+
+## Phase 1: CONTEXT
+
+**Purpose:** Understand what exists before asking questions.
+
+**Protocol:**
+
+1. Check project state (files, recent commits, existing specs)
+2. Review relevant docs in `.safeword/planning/`
+3. Identify constraints and patterns already established
+
+**Exit Criteria:**
+
+- [ ] Reviewed relevant codebase areas
+- [ ] Checked existing specs/designs
+- [ ] Ready to ask informed questions
+
+---
+
+## Phase 2: QUESTION
+
+**Iron Law:** ONE QUESTION PER MESSAGE
+
+**Protocol:**
+
+1. Ask one focused question
+2. Prefer multiple choice (2-4 options) when possible
+3. Open-ended is fine for exploratory topics
+4. Focus on: purpose, constraints, success criteria, scope
+
+**Question Types (in order of preference):**
+
+| Type            | When                    | Example                                              |
+| --------------- | ----------------------- | ---------------------------------------------------- |
+| Multiple choice | Clear options exist     | "Should this be (A) real-time or (B) polling-based?" |
+| Yes/No          | Binary decision         | "Do we need offline support?"                        |
+| Bounded open    | Need specifics          | "What's the max number of items to display?"         |
+| Open-ended      | Exploring problem space | "What problem are you trying to solve?"              |
+
+**Exit Criteria:**
+
+- [ ] Understand the core problem/goal
+- [ ] Know key constraints
+- [ ] Have success criteria
+- [ ] Scope boundaries are clear
+
+---
+
+## Phase 3: ALTERNATIVES
+
+**Iron Law:** ALWAYS PRESENT 2-3 OPTIONS BEFORE DECIDING
+
+**Protocol:**
+
+1. Present 2-3 approaches with trade-offs
+2. Lead with your recommendation and why
+3. Be explicit about what each gives up
+4. Let user choose (or suggest hybrid)
+
+**Format:**
+
+```text
+I'd recommend Option A because [reason].
+
+**Option A: [Name]**
+- Approach: [how it works]
+- Pros: [benefits]
+- Cons: [drawbacks]
+
+**Option B: [Name]**
+- Approach: [how it works]
+- Pros: [benefits]
+- Cons: [drawbacks]
+
+**Option C: [Name]** (if applicable)
+- Approach: [how it works]
+- Pros: [benefits]
+- Cons: [drawbacks]
+
+Which direction feels right?
+```
+
+**Exit Criteria:**
+
+- [ ] Presented 2-3 viable approaches
+- [ ] Gave clear recommendation with reasoning
+- [ ] User selected approach (or hybrid)
+
+---
+
+## Phase 4: DESIGN
+
+**Iron Law:** PRESENT IN 200-300 WORD SECTIONS. VALIDATE EACH.
+
+**Protocol:**
+
+1. Present design incrementally (not all at once)
+2. After each section: "Does this look right so far?"
+3. Cover: architecture, components, data flow, error handling
+4. Apply YAGNI ruthlessly - remove anything "just in case"
+5. Go back and clarify when something doesn't fit
+
+**Sections (present one at a time):**
+
+1. **Overview** - What we're building, high-level approach
+2. **Components** - Key pieces and responsibilities
+3. **Data Flow** - How data moves through system
+4. **Edge Cases** - Error handling, boundaries
+5. **Out of Scope** - What we're explicitly NOT doing
+
+**Exit Criteria:**
+
+- [ ] Each section validated by user
+- [ ] Design is complete and coherent
+- [ ] YAGNI applied (no speculative features)
+- [ ] Ready to create spec
+
+---
+
+## Phase 5: SPEC
+
+**Purpose:** Convert validated design into structured spec.
+
+**Protocol:**
+
+1. Determine level (L0/L1/L2) using triage questions
+2. Create spec using appropriate template
+3. Commit the spec
+
+**Triage:**
+
+| Question                                 | If Yes →                     |
+| ---------------------------------------- | ---------------------------- |
+| User-facing feature with business value? | **L2** → Feature Spec        |
+| Bug, improvement, internal, or refactor? | **L1** → Task Spec           |
+| Typo, config, or trivial change?         | **L0** → Task Spec (minimal) |
+
+**Output Locations:**
+
+- L2: `.safeword/planning/specs/feature-[slug].md`
+- L1/L0: `.safeword/planning/specs/task-[slug].md`
+- L2 Test Defs: `.safeword/planning/test-definitions/feature-[slug].md`
+
+**Exit Criteria:**
+
+- [ ] Spec created in correct location
+- [ ] L2: Test definitions created
+- [ ] Spec committed to git
+
+---
+
+## Phase 6: HANDOFF
+
+**Protocol:**
+
+1. Summarize what was created
+2. Ask: "Ready to start implementation with TDD?"
+3. If yes → Invoke enforcing-tdd skill
+
+**Exit Criteria:**
+
+- [ ] User confirmed spec is complete
+- [ ] Handed off to enforcing-tdd (if continuing)
+
+---
+
+## Key Principles
+
+| Principle                     | Why                                     |
+| ----------------------------- | --------------------------------------- |
+| One question at a time        | Prevents overwhelm, gets better answers |
+| Multiple choice preferred     | Faster to answer, reduces ambiguity     |
+| Alternatives before decisions | Avoids premature commitment             |
+| Incremental validation        | Catches misunderstandings early         |
+| YAGNI ruthlessly              | Scope creep kills projects              |
+
+---
+
+## Anti-Patterns
+
+| Don't                          | Do                               |
+| ------------------------------ | -------------------------------- |
+| Dump full design at once       | Present in 200-300 word sections |
+| Ask 5 questions in one message | Ask ONE question                 |
+| Skip alternatives              | Always present 2-3 options       |
+| Accept vague requirements      | Probe until concrete             |
+| Add "nice to have" features    | Put them in "Out of Scope"       |

package/templates/skills/{safeword-systematic-debugger → safeword-debugging}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: systematic-debugger
+name: debugging
 description: Four-phase debugging framework that ensures root cause identification before fixes. Use when encountering bugs, test failures, unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline ('debug this', 'fix this error', 'test is failing', 'not working').
 allowed-tools: '*'
 ---
@@ -26,33 +26,6 @@ Answer IN ORDER. Stop at first match:
 - "Quick fix" seems obvious (red flag)
 - Already tried 1+ fixes that didn't work
 
----
-
-## Work Log
-
-**Think hard. Keep notes.**
-
-Before starting Phase 1, create or open a work log:
-
-**Location:** `.safeword/logs/{artifact-type}-{slug}.md`
-
-| Working on...         | Log file name            |
-| --------------------- | ------------------------ |
-| Ticket `001-fix-auth` | `ticket-001-fix-auth.md` |
-| Spec `task-add-cache` | `spec-task-add-cache.md` |
-
-**One artifact = one log.** If log exists, append a new session.
-
-**Especially important for debugging:**
-
-1. **Re-read the log** before each hypothesis
-2. **Log what you tried** and why it didn't work
-3. **Note dead ends** - debugging often revisits same paths
-
-**Template:** @./.safeword/templates/work-log-template.md
-
----
-
 ## The Four Phases
 
 Complete each phase before proceeding.
@@ -220,32 +193,6 @@ If you catch yourself thinking:
 
 **ALL mean: STOP. Return to Phase 1.**
 
-## Finding Test Pollution
-
-When tests pass individually but fail together (test isolation problem, tests affect each other, tests leave files behind), use bisection:
-
-```bash
-./.safeword/scripts/bisect-test-pollution.sh '.git' '*.test.ts' src
-```
-
-See: @./.safeword/scripts/bisect-test-pollution.sh
-
-## Debug Logging
-
-When adding diagnostic logging:
-
-```javascript
-// ❌ BAD
-console.log('here');
-console.log(data);
-
-// ✅ GOOD
-console.log('validateUser', { expected: 'admin', actual: user.role });
-console.log('processOrder', JSON.stringify({ input, output }, null, 2));
-```
-
-Log **expected vs actual**. Remove after fixing.
-
 ## Quick Reference
 
 | Phase             | Key Question                          | Success Criteria                   |
@@ -254,20 +201,3 @@ Log **expected vs actual**. Remove after fixing.
 | 2. Pattern        | "What's different from working code?" | Identified key differences         |
 | 3. Hypothesis     | "Is my theory correct?"               | Confirmed or formed new theory     |
 | 4. Implementation | "Does the fix work?"                  | Test passes, issue resolved        |
-
-## Finding Zombie Process Spawners
-
-When tests leave processes behind (playwright browsers not cleaned up, port stays in use, zombie node processes, chromium accumulating), use bisection to find the culprit:
-
-```bash
-./.safeword/scripts/bisect-zombie-processes.sh 'chromium' '*.test.ts' tests
-./.safeword/scripts/bisect-zombie-processes.sh 'playwright' '*.spec.ts' e2e
-```
-
-See: @./.safeword/scripts/bisect-zombie-processes.sh
-
-## Related Resources
-
-- Process cleanup guide: @./.safeword/guides/zombie-process-cleanup.md
-- Debug logging style: @./.safeword/guides/code-philosophy.md
-- TDD for fix verification: @./.safeword/guides/testing-guide.md

package/templates/skills/{safeword-tdd-enforcer → safeword-enforcing-tdd}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: tdd-enforcer
-description: Use when implementing features, fixing bugs, or adding new behavior. Ensures scope is defined before coding, then enforces RED → GREEN → REFACTOR test discipline. NOT for pure refactoring (use refactoring skill for structural improvements without behavior change). Triggers: 'implement', 'add', 'build', 'create', 'fix', 'change', 'feature', 'bug'.
+name: enforcing-tdd
+description: Use when implementing features, fixing bugs, or making code changes. Ensures scope is defined before coding, then enforces RED → GREEN → REFACTOR test discipline. Triggers: 'implement', 'add', 'build', 'create', 'fix', 'change', 'feature', 'bug'.
 allowed-tools: '*'
 ---
 
@@ -17,7 +17,7 @@ Answer IN ORDER. Stop at first match:
 1. Implementing new feature? → Use this skill
 2. Fixing bug? → Use this skill
 3. Adding enhancement? → Use this skill
-4. Refactoring only (no new behavior)? → Skip (use refactoring skill)
+4. Refactoring? → Use this skill
 5. Research/investigation only? → Skip this skill
 
 ---
@@ -160,15 +160,15 @@ Claim: "All tests pass"             "Tests pass" (no output shown)
 
 **Red Flags → STOP:**
 
-| Flag                        | Action                                 |
-| --------------------------- | -------------------------------------- |
-| "should", "probably" claims | Run command, show output first         |
-| "Done!" before verification | Run command, show output first         |
-| "Just in case" code         | Delete it                              |
-| Multiple functions          | Delete extras                          |
-| Refactoring                 | Stop - that's Phase 3                  |
-| Test still fails            | Debug (→ systematic-debugger if stuck) |
-| Hardcoded value             | Implement real logic (see below)       |
+| Flag                        | Action                             |
+| --------------------------- | ---------------------------------- |
+| "should", "probably" claims | Run command, show output first     |
+| "Done!" before verification | Run command, show output first     |
+| "Just in case" code         | Delete it                          |
+| Multiple functions          | Delete extras                      |
+| Refactoring                 | Stop - that's Phase 3              |
+| Test still fails            | Debug (→ debugging skill if stuck) |
+| Hardcoded value             | Implement real logic (see below)   |
 
 ### Anti-Pattern: Mock Implementations
 
@@ -253,11 +253,11 @@ Phase 0: L0 → create minimal spec → Phase 1: no new test (existing tests cov
 
 ## Integration
 
-| Scenario                | Handoff               |
-| ----------------------- | --------------------- |
-| Test fails unexpectedly | → systematic-debugger |
-| Review needed           | → quality-reviewer    |
-| Scope expanding         | → Update spec first   |
+| Scenario                | Handoff             |
+| ----------------------- | ------------------- |
+| Test fails unexpectedly | → debugging skill   |
+| Review needed           | → quality-reviewer  |
+| Scope expanding         | → Update spec first |
 
 ---
 

package/templates/skills/safeword-quality-reviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quality-reviewer
-description: Deep code quality review with web research. Use when user explicitly requests verification against latest docs ('double check against latest', 'verify versions', 'check security'), needs deeper analysis beyond automatic hook, or is working on projects without SAFEWORD.md/CLAUDE.md. Fetches current documentation (WebFetch), checks latest versions (WebSearch), and provides deep analysis (performance, security, alternatives).
+description: Deep code review with web research to verify against latest ecosystem. Use when user says 'double check against latest', 'verify versions', 'check security', 'review against docs', or needs deep analysis beyond automatic quality hook.
 allowed-tools: '*'
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: '*'
 
 Deep quality review with web research to verify code against the latest ecosystem state.
 
-**Primary differentiator**: Web research (WebSearch, WebFetch) to verify against current versions, documentation, and best practices.
+**Primary differentiator**: Web research to verify against current versions, documentation, and best practices.
 
 **Triggers**:
 
@@ -16,7 +16,6 @@ Deep quality review with web research to verify code against the latest ecosyste
 - **Deep dive needed**: User wants analysis beyond automatic hook (performance, architecture alternatives, trade-offs)
 - **No SAFEWORD.md/CLAUDE.md**: Projects without context files (automatic hook won't run, manual review needed)
 - **Pre-change review**: User wants review before making changes (automatic hook only triggers after changes)
-- **Model-invoked**: Claude determines web research would be valuable
 
 **Relationship to automatic quality hook**:
 
@@ -43,7 +42,6 @@ Read relevant standards:
 
 - `CLAUDE.md` or `SAFEWORD.md` - Project-specific guidelines
 - `ARCHITECTURE.md` - Architectural principles
-- `@./.safeword/guides/code-philosophy.md` - Core coding principles
 
 ### 3. Evaluate Correctness
 
@@ -92,14 +90,12 @@ Read relevant standards:
 - Are we using libraries correctly?
 - Are we following official documentation?
 
-### 7. Verify Latest Versions ⭐ **PRIMARY VALUE**
+### 7. Verify Latest Versions - PRIMARY VALUE
 
 **CRITICAL**: This is your main differentiator from automatic hook. ALWAYS check versions.
 
-```text
-WebSearch: "[library name] latest stable version 2025"
-WebSearch: "[library name] security vulnerabilities"
-```
+Search for: "[library name] latest stable version 2025"
+Search for: "[library name] security vulnerabilities"
 
 **Flag if outdated:**
 
@@ -110,25 +106,17 @@ WebSearch: "[library name] security vulnerabilities"
 
 **Common libraries**: React, TypeScript, Vite, Next.js, Node.js, Vitest, Playwright, Jest, esbuild
 
-**Check even if dependencies didn't change** - User might be using outdated patterns.
-
-### 8. Verify Latest Documentation ⭐ **PRIMARY VALUE**
+### 8. Verify Latest Documentation - PRIMARY VALUE
 
 **CRITICAL**: This is your main differentiator from automatic hook. ALWAYS verify against current docs.
 
-```text
-WebFetch: https://react.dev (for React)
-WebFetch: https://vitejs.dev (for Vite)
-WebFetch: https://www.electronjs.org/docs (for Electron)
-```
+Fetch and check official documentation sites for the libraries in use.
 
 **Look for:**
 
 - Are we using deprecated APIs?
 - Are there newer, better patterns?
-- Did the library's recommendations change since training data?
-
-**Cache results**: If you checked docs recently in this session, don't re-fetch.
+- Did the library's recommendations change recently?
 
 ## Output Format
 
@@ -147,8 +135,8 @@ WebFetch: https://www.electronjs.org/docs (for Electron)
 **Anti-Bloat:** [✓/⚠️/❌] [Brief assessment]
 **Elegance:** [✓/⚠️/❌] [Brief assessment]
 **Standards:** [✓/⚠️/❌] [Brief assessment]
-**Versions:** [✓/⚠️/❌] [Latest version check with WebSearch]
-**Documentation:** [✓/⚠️/❌] [Current docs check with WebFetch]
+**Versions:** [✓/⚠️/❌] [Latest version check]
+**Documentation:** [✓/⚠️/❌] [Current docs check]
 
 **Verdict:** [APPROVE / REQUEST CHANGES / NEEDS DISCUSSION]
 
@@ -156,52 +144,14 @@ WebFetch: https://www.electronjs.org/docs (for Electron)
 **Suggested improvements:** [List or "None"]
 ```
 
-Use structured format for "double check"/"critique". Use brief format for specific questions.
-
-## Example: Full Review
-
-```markdown
-## Quality Review
-
-**Correctness:** ✓ Logic sound, edge cases covered, error handling adequate
-**Anti-Bloat:** ✓ Minimal dependencies, appropriate abstractions
-**Elegance:** ✓ Clear code, good naming, well-structured
-**Standards:** ✓ Follows CLAUDE.md patterns
-**Versions:** ✓ React 19.0.0 (latest stable), TypeScript 5.7.2 (latest)
-**Documentation:** ✓ Using current React patterns per https://react.dev
-
-**Verdict:** APPROVE - Production ready
-
-**Critical issues:** None
-**Suggested improvements:** None
-```
-
 ## Critical Reminders
 
-1. **Primary value: Web research** - Use WebSearch/WebFetch to verify against current ecosystem (versions, docs, security)
+1. **Primary value: Web research** - Verify against current ecosystem (versions, docs, security)
 2. **Complement automatic hook** - Hook does fast check with existing knowledge, you do deep dive with web research
 3. **Explicit triggers matter** - "double check against latest docs", "verify versions", "check security" = invoke web research
-4. **Projects without SAFEWORD.md** - Automatic hook won't run, you're the only quality check
-5. **Always check latest docs** - Verify patterns are current, not outdated (WebFetch)
-6. **Always verify versions** - Flag outdated dependencies (WebSearch)
-7. **Be thorough but concise** - Cover all areas but keep explanations brief
-8. **Provide actionable feedback** - Specific line numbers, concrete suggestions
-9. **Clear verdict** - Always end with APPROVE/REQUEST CHANGES/NEEDS DISCUSSION
-10. **Separate critical vs nice-to-have** - User needs to know what's blocking vs optional
-
-## Non-Obvious Edge Cases
-
-**User requests review after automatic hook ran:**
-
-- Acknowledge hook ran: "The automatic quality hook already did a fast check. I'll now do deeper analysis with web research..."
-- Focus on what automatic hook doesn't do: fetch latest docs, verify versions, security checks, performance analysis
-
-**WebSearch/WebFetch fails:**
-
-- Continue review without version/docs checks
-- Note: "Couldn't verify latest versions/docs, skipping that check"
-
-**Project has no CLAUDE.md/SAFEWORD.md:**
-
-- Use `@./.safeword/guides/code-philosophy.md` as fallback
-- Note: "No project-specific standards found, using general best practices"
+4. **Always check latest docs** - Verify patterns are current, not outdated
+5. **Always verify versions** - Flag outdated dependencies
+6. **Be thorough but concise** - Cover all areas but keep explanations brief
+7. **Provide actionable feedback** - Specific line numbers, concrete suggestions
+8. **Clear verdict** - Always end with APPROVE/REQUEST CHANGES/NEEDS DISCUSSION
+9. **Separate critical vs nice-to-have** - User needs to know what's blocking vs optional