safeword 0.7.5 → 0.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safeword",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "CLI for setting up and managing safeword development environments",
   "type": "module",
   "bin": {
@@ -19,18 +19,6 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:e2e": "vitest run tests/e2e/",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run build && npm test"
-  },
   "dependencies": {
     "commander": "^12.1.0"
   },
@@ -48,5 +36,16 @@
     "claude-code"
   ],
   "author": "",
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:e2e": "vitest run tests/e2e/",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "clean": "rm -rf dist"
+  }
+}

package/templates/SAFEWORD.md

@@ -44,21 +44,21 @@ Training data is stale. Follow this sequence:
 
 **Read the matching guide when ANY trigger fires:**
 
-| Trigger                                                   | Guide                                          |
-| --------------------------------------------------------- | ---------------------------------------------- |
-| Starting ANY feature, bug fix, or enhancement             | @./.safeword/guides/development-workflow.md    |
-| Need to write OR review user stories                      | @./.safeword/guides/user-story-guide.md        |
-| Need to write OR review test definitions                  | @./.safeword/guides/test-definitions-guide.md  |
-| Writing tests, doing TDD, or test is failing              | @./.safeword/guides/tdd-best-practices.md      |
-| Creating OR updating a design doc                         | @./.safeword/guides/design-doc-guide.md        |
-| Making architectural decision OR writing ADR              | @./.safeword/guides/architecture-guide.md      |
-| Designing data models, schemas, or database changes       | @./.safeword/guides/data-architecture-guide.md |
-| Calling LLM APIs OR writing LLM-consumable docs           | @./.safeword/guides/llm-guide.md               |
-| Updating CLAUDE.md, SAFEWORD.md, or any context file      | @./.safeword/guides/context-files-guide.md     |
-| Hit same bug 3+ times OR discovered undocumented gotcha   | @./.safeword/guides/learning-extraction.md     |
-| Process hanging, port in use, or zombie process suspected | @./.safeword/guides/zombie-process-cleanup.md  |
-| Using `safeword` CLI commands                             | @./.safeword/guides/cli-reference.md           |
-| Debugging issues OR need git/cross-platform guidance      | @./.safeword/guides/code-philosophy.md         |
+| Trigger                                                   | Guide                                           |
+| --------------------------------------------------------- | ----------------------------------------------- |
+| Starting ANY feature, bug fix, or enhancement             | `./.safeword/guides/development-workflow.md`    |
+| Need to write OR review user stories                      | `./.safeword/guides/user-story-guide.md`        |
+| Need to write OR review test definitions                  | `./.safeword/guides/test-definitions-guide.md`  |
+| Writing tests, doing TDD, or test is failing              | `./.safeword/guides/tdd-best-practices.md`      |
+| Creating OR updating a design doc                         | `./.safeword/guides/design-doc-guide.md`        |
+| Making architectural decision OR writing ADR              | `./.safeword/guides/architecture-guide.md`      |
+| Designing data models, schemas, or database changes       | `./.safeword/guides/data-architecture-guide.md` |
+| Calling LLM APIs OR writing LLM-consumable docs           | `./.safeword/guides/llm-guide.md`               |
+| Updating CLAUDE.md, SAFEWORD.md, or any context file      | `./.safeword/guides/context-files-guide.md`     |
+| Hit same bug 3+ times OR discovered undocumented gotcha   | `./.safeword/guides/learning-extraction.md`     |
+| Process hanging, port in use, or zombie process suspected | `./.safeword/guides/zombie-process-cleanup.md`  |
+| Using `safeword` CLI commands                             | `./.safeword/guides/cli-reference.md`           |
+| Debugging issues OR need git/cross-platform guidance      | `./.safeword/guides/code-philosophy.md`         |
 
 ---
 
@@ -66,15 +66,15 @@ Training data is stale. Follow this sequence:
 
 **Use the matching template when ANY trigger fires:**
 
-| Trigger                                                    | Template                                           |
-| ---------------------------------------------------------- | -------------------------------------------------- |
-| Planning new feature scope OR creating feature spec        | @./.safeword/templates/feature-spec-template.md    |
-| Bug, improvement, refactor, or internal task               | @./.safeword/templates/task-spec-template.md       |
-| Need test definitions for a feature OR acceptance criteria | @./.safeword/templates/test-definitions-feature.md |
-| Feature spans 3+ components OR needs technical spec        | @./.safeword/templates/design-doc-template.md      |
-| Making decision with long-term impact OR trade-offs        | @./.safeword/templates/architecture-template.md    |
-| Task needs context anchoring (see Ticket System below)     | @./.safeword/templates/ticket-template.md          |
-| Starting execution of a plan, ticket, or spec              | @./.safeword/templates/work-log-template.md        |
+| Trigger                                                    | Template                                            |
+| ---------------------------------------------------------- | --------------------------------------------------- |
+| Planning new feature scope OR creating feature spec        | `./.safeword/templates/feature-spec-template.md`    |
+| Bug, improvement, refactor, or internal task               | `./.safeword/templates/task-spec-template.md`       |
+| Need test definitions for a feature OR acceptance criteria | `./.safeword/templates/test-definitions-feature.md` |
+| Feature spans 3+ components OR needs technical spec        | `./.safeword/templates/design-doc-template.md`      |
+| Making decision with long-term impact OR trade-offs        | `./.safeword/templates/architecture-template.md`    |
+| Task needs context anchoring (see Ticket System below)     | `./.safeword/templates/ticket-template.md`          |
+| Starting execution of a plan, ticket, or spec              | `./.safeword/templates/work-log-template.md`        |
 
 ---
 
@@ -286,9 +286,19 @@ When markdown lint reports MD040 (missing language), choose:
 
 ---
 
-## Learning Extraction
+## Learnings
 
-**Suggest extraction when ANY apply:**
+**Location:** `.safeword/learnings/`
+
+**Check learnings FIRST when:**
+
+1. Stuck on an issue OR debugging same problem 2+ times
+2. Working with unfamiliar technology in this codebase
+3. Issue involves testing, processes, or integrations
+
+**How:** `ls .safeword/learnings/` then read relevant files.
+
+**Extract new learning when ANY apply:**
 
 - 5+ debug cycles on same issue
 - 3+ approaches tried
@@ -296,3 +306,14 @@ When markdown lint reports MD040 (missing language), choose:
 - Integration struggle between tools
 
 **Before extracting:** Check `.safeword/learnings/` for existing similar learnings—update, don't duplicate.
+
+---
+
+## Always Remember
+
+1. **Clarity → Simplicity → Correctness** (in that order)
+2. **Test what you can test**—never ask user to verify
+3. **RED → GREEN → REFACTOR**—never skip steps
+4. **Commit after each GREEN phase**
+5. **Read the matching guide** when a trigger fires
+6. **End every response** with: `{"proposedChanges": bool, "madeChanges": bool, "askedQuestion": bool}`

package/templates/guides/architecture-guide.md

@@ -413,11 +413,9 @@ export default defineConfig([
 
 ---
 
-## Key Takeaway
+## Key Takeaways
 
-**One comprehensive architecture document per project** > many scattered ADR files:
-
-✅ Full context in one place
-✅ Living document (update in place)
-✅ LLMs consume entire architecture at once
-✅ Sequential decision trees prevent ambiguity
+- One Architecture Doc per project—not scattered ADRs
+- Every decision needs: What / Why / Trade-off / Alternatives
+- Update when adding: technology, schema, or project-wide pattern
+- Living document—update in place with version/status tracking

package/templates/guides/cli-reference.md

@@ -33,3 +33,11 @@ Common flags:
 - `-y, --yes` - Skip confirmations (setup, reset)
 - `-v, --verbose` - Show detailed output (diff)
 - `-q, --quiet` - Suppress output (sync)
+
+---
+
+## Key Takeaways
+
+- Always use `@latest` for setup/check/upgrade/diff to get current CLI
+- Run `sync` after adding/removing frameworks to update linting plugins
+- Use `diff` before `upgrade` to preview changes

package/templates/guides/code-philosophy.md

@@ -196,3 +196,12 @@ Before completing any work, verify:
 # ❌ Bad: "misc fixes"
 # ✅ Good: "fix: login button not responding to clicks"
 ```
+
+---
+
+## Key Takeaways
+
+- Clarity → Simplicity → Correctness (in that order)
+- Delete unused code—no "just in case" abstractions
+- Commit often with descriptive messages
+- Verify library versions before using APIs (training data is stale)

package/templates/guides/context-files-guide.md

@@ -455,3 +455,12 @@ Before committing:
 - Bloated files cost more tokens and introduce noise
 - Keep under 50KB for optimal performance (though no hard limit)
 - Use imports to modularize instead of monolithic files
+
+---
+
+## Key Takeaways
+
+- Keep context files under 200 lines—use imports to modularize
+- Short declarative bullets, not narrative paragraphs
+- Update immediately when architecture changes (stale docs = confusion)
+- Put critical rules at the END of documents (recency bias)

package/templates/guides/data-architecture-guide.md

@@ -198,3 +198,12 @@ Before finalizing data architecture doc:
 - [ ] Migration strategy covers both additive and breaking changes
 - [ ] Version and status match codebase (verify with git/deployment)
 - [ ] Cross-referenced from root ARCHITECTURE.md or SAFEWORD.md (link exists)
+
+---
+
+## Key Takeaways
+
+- Data quality, governance, accessibility are core principles
+- Every entity needs: attributes, types, relationships, constraints
+- Performance targets use concrete numbers (e.g., <100ms, not "fast")
+- Migration strategy covers both additive and breaking changes

package/templates/guides/design-doc-guide.md

@@ -1,5 +1,17 @@
 # Design Doc Guide for Claude Code
 
+## Escalation Check
+
+**STOP if ANY apply—use `architecture-guide.md` first:**
+
+- [ ] Need to choose a technology or library
+- [ ] Need to design a data model or schema
+- [ ] Pattern will affect 2+ features
+
+Then return here.
+
+---
+
 ## How to Fill Out Design Doc
 
 **Template:** `@.safeword/templates/design-doc-template.md`
@@ -169,3 +181,12 @@ Before saving, verify:
 **Important:** Design docs are instructions that LLMs read and follow.
 
 **See:** `@.safeword/guides/llm-guide.md` for comprehensive framework on writing clear, actionable documentation that LLMs can reliably follow.
+
+---
+
+## Key Takeaways
+
+- Escalate to Architecture Doc if: new tech, new schema, or pattern affects 2+ features
+- Reference user stories and test definitions—don't duplicate them
+- Every decision needs: what, why, trade-off
+- ~121 lines target (concise, LLM-optimized)

package/templates/guides/development-workflow.md

@@ -616,3 +616,12 @@ npm run test:e2e # E2E tests only
 
 1. **Global** (`~/.claude/development-workflow.md`) - Universal methodology (test type selection, TDD workflow)
 2. **Project** (`tests/SAFEWORD.md`) - Specific stack, commands, patterns
+
+---
+
+## Key Takeaways
+
+- RED → GREEN → REFACTOR (never skip steps)
+- Choose test type by answering questions IN ORDER (unit → integration → E2E)
+- Never use arbitrary timeouts—poll until condition is met
+- Test behavior, not implementation details

package/templates/guides/learning-extraction.md

@@ -550,3 +550,12 @@ This is a **living process** - iterate and refine based on what works.
 - Refactor when multiple learnings cover similar topics (consolidate)
 - Split when learning file >200 lines (focus on single concept)
 - Update SAFEWORD.md references when learnings move or merge
+
+---
+
+## Key Takeaways
+
+- Extract after 5+ debug cycles or 3+ approaches tried
+- Check existing learnings first—update, don't duplicate
+- One concept per file, under 200 lines
+- Extract immediately while fresh (don't defer to "later")

package/templates/guides/llm-guide.md

@@ -259,6 +259,44 @@ When LLMs hit dead ends, provide concrete next steps.
    - Login form → Dashboard → E2E test (multi-page)"
 ```
 
+### 14. Position-Aware Writing (Recency Bias)
+
+LLMs retain information at the **beginning and end** of context better than the middle. Structure documents accordingly.
+
+```markdown
+❌ BAD - Critical rules buried in middle:
+
+# Guide
+
+## Background (100 lines)
+
+## Details (200 lines)
+
+## Critical Rules (10 lines) ← forgotten
+
+## Appendix (50 lines)
+
+✅ GOOD - Critical rules at end:
+
+# Guide
+
+## Background (100 lines)
+
+## Details (200 lines)
+
+## Appendix (50 lines)
+
+## Key Takeaways (10 lines) ← retained
+```
+
+**Application:**
+
+- CLAUDE.md / SAFEWORD.md: Put "Always Remember" section last
+- Guides: End with "Key Takeaways" section
+- Templates: Put most important sections at top OR bottom, not middle
+
+**Research basis:** "Lost in the middle" phenomenon—models show <40% recall for middle content vs >80% for beginning/end content.
+
 ---
 
 ## Anti-Patterns
@@ -267,6 +305,7 @@ When LLMs hit dead ends, provide concrete next steps.
 ❌ **Undefined jargon** - "Technical debt", "code smell" need definitions
 ❌ **Competing guidance** - Multiple decision frameworks that contradict each other
 ❌ **Outdated references** - Remove concepts, but forget to update all mentions
+❌ **Critical info in the middle** - Most important rules buried between background and appendix
 
 ---
 
@@ -283,6 +322,7 @@ Before saving/committing LLM-consumable documentation:
 - [ ] Tie-breaking rules provided
 - [ ] Complex decisions (3+ branches) have lookup tables
 - [ ] Dead-end paths have re-evaluation steps with examples
+- [ ] Critical rules positioned at END of document (recency bias)
 
 ---
 
@@ -310,3 +350,12 @@ Edge cases:
 - React components with React Testing Library → Integration (not E2E, no real browser)
 - Non-deterministic functions (Date.now()) → Unit test with mocked time
 ```
+
+---
+
+## Key Takeaways
+
+- Decision trees: sequential, MECE, with tie-breakers
+- Every rule needs concrete examples (good vs bad)
+- Define all terms explicitly—assume nothing is obvious
+- Put critical rules at the END of documents (recency bias)

package/templates/guides/tdd-best-practices.md

@@ -613,4 +613,12 @@ Before writing a story, verify it passes all six criteria:
 - **Unit:** Single function/module logic (fast, cheap, low-level confidence)
 
 **Ratio guidance:** 70% unit, 20% integration, 10% E2E (adjust based on project)
-````
+
+---
+
+## Key Takeaways
+
+- RED → GREEN → REFACTOR (commit after each GREEN)
+- Test behavior, not implementation details
+- One assertion per test; test names describe behavior
+- User stories pass INVEST checklist before writing tests

package/templates/guides/test-definitions-guide.md

@@ -332,4 +332,12 @@ npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
 - Concrete examples over abstract rules
 - Edge cases must be explicit
 - Actionable over vague language
-````
+
+---
+
+## Key Takeaways
+
+- Map each user story acceptance criterion to specific tests
+- Include tests for technical constraints (performance, security, etc.)
+- Test behavior, not implementation details
+- Every skipped test needs documented rationale

package/templates/guides/user-story-guide.md

@@ -254,3 +254,12 @@ Save specs as: `.safeword/planning/specs/feature-[slug].md`
 
 - `user-story-1.md` ← Not descriptive
 - `STORY_CAMPAIGN_SWITCHING_FINAL_v2.md` ← Bloated
+
+---
+
+## Key Takeaways
+
+- INVEST checklist: Independent, Negotiable, Valuable, Estimable, Small, Testable
+- "As a [role], I want [action], so that [value]"—always include the "so that"
+- 1-3 acceptance criteria per story; split if >3
+- Include technical constraints (performance, security, etc.) when relevant

package/templates/guides/zombie-process-cleanup.md

@@ -217,3 +217,12 @@ ps aux | grep "/Users/alex/projects/my-project"
 ✅ **DO:** Filter by project directory with `$(pwd)`
 ✅ **DO:** Create project-specific cleanup scripts
 ✅ **DO:** Clean up before AND after development sessions
+
+---
+
+## Key Takeaways
+
+- Use port-based cleanup, not `killall node` (affects all projects)
+- Filter by project directory: `pkill -f "playwright.*$(pwd)"`
+- Clean up before AND after development sessions
+- Create project-specific `scripts/cleanup.sh` for consistent cleanup