safeword 0.1.0 → 0.2.0

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

@@ -0,0 +1,256 @@
+# User Story Guide for Claude Code
+
+## How to Fill Out Feature User Stories
+
+**Template:** `@.safeword/templates/user-stories-template.md`
+
+**When user asks:** "Create user stories for issue #N" or "Create user stories for [feature]"
+
+**What you do:**
+
+1. Read `@.safeword/templates/user-stories-template.md`
+2. Fill in feature name, issue number, status
+3. Create numbered stories (Story 1, Story 2, etc.)
+4. Add acceptance criteria with ✅/❌ checkboxes for tracking
+5. Include test file references
+6. Add summary with completion % and phases
+7. Save to project location (e.g., `planning/user-stories/45-feature-name.md`)
+
+**DO include:**
+
+- Status tracking (✅/❌ per story and AC)
+- Test file references
+- Implementation status
+- Completion percentage
+- Phase tracking
+- Next steps
+
+---
+
+## INVEST Validation (Do This Before Saving)
+
+After filling out story, mentally check:
+
+✅ **Independent** - Can be done without other stories?
+✅ **Negotiable** - Are details left for conversation?
+✅ **Valuable** - Does "So that" clearly state value?
+✅ **Estimable** - Can team estimate this (1-5 days)?
+✅ **Small** - Completable in one sprint?
+✅ **Testable** - Are acceptance criteria specific?
+
+**If ANY check fails → Refine or split the story**
+
+---
+
+## Writing Good Acceptance Criteria
+
+**✅ GOOD - Specific, user-facing, testable:**
+
+- User can switch campaigns without page reload
+- Response time is under 200ms
+- Current campaign is visually highlighted
+- Error message explains what went wrong
+
+**❌ BAD - Vague, technical, or implementation:**
+
+- Campaign switching works ← Too vague
+- Use Zustand for state ← Implementation detail
+- Database is fast ← Not user-facing
+- Code is clean ← Not testable
+
+---
+
+## Size Guidelines
+
+| Indicator           | Too Big | Just Right | Too Small |
+| ------------------- | ------- | ---------- | --------- |
+| Acceptance Criteria | 6+      | 1-5        | 0         |
+| Personas/Screens    | 3+      | 1-2        | N/A       |
+| Duration            | 6+ days | 1-5 days   | <1 hour   |
+| **Action**          | Split   | ✅ Ship    | Combine   |
+
+**Decision rule:** When borderline (e.g., 5 AC but 2 personas), err on the side of splitting. Smaller stories are easier to estimate and complete.
+
+---
+
+## Examples
+
+### ✅ GOOD Story
+
+**As a** player with multiple campaigns
+**I want** to switch between campaigns from the sidebar
+**So that** I can quickly resume different games
+
+**Acceptance Criteria:**
+
+- [ ] Sidebar shows all campaigns with last-played date
+- [ ] Clicking campaign loads it within 200ms
+- [ ] Current campaign is highlighted
+
+### ❌ BAD Story (Too Big)
+
+**As a** user
+**I want** a complete campaign management system
+**So that** I can organize my games
+
+**Acceptance Criteria:**
+
+- [ ] Create, edit, delete campaigns
+- [ ] Share campaigns with other players
+- [ ] Export/import campaign data
+- [ ] Search and filter campaigns
+- [ ] Tag campaigns by theme
+
+**Problem:** This is 5+ separate stories. Split it.
+
+### ❌ BAD Story (No Value)
+
+**As a** developer
+**I want** to refactor the GameStore
+**So that** code is cleaner
+
+**Problem:**
+
+- Developer is not a user
+- "Cleaner code" is not user-facing value
+- This is a technical task, not a user story
+
+### ✅ BETTER (Technical Story)
+
+**Technical Task:** Refactor GameStore to use Immer
+
+**Why:** Prevent state mutation bugs (3 bugs in last sprint)
+**Effort:** 2-3 hours
+**Test:** All existing tests pass, no new mutations
+
+---
+
+## Conversation Starter, Not Contract
+
+**Remember:** User story is a placeholder for conversation.
+
+**During planning, discuss:**
+
+- Edge cases not in acceptance criteria
+- Technical approach (but don't document it in story)
+- Open questions or dependencies
+- How to split if too big
+
+**The story should NOT contain:**
+
+- Technical implementation details
+- Test strategies
+- UI mockups (link to them instead)
+- Definition of done (that's team-wide)
+
+---
+
+## Technical Constraints Section
+
+**Purpose:** Capture non-functional requirements that inform test definitions. These are NOT user stories but constrain how stories are implemented.
+
+**When to use:** Fill in constraints BEFORE writing test definitions. Delete sections that don't apply—keep it lean.
+
+### Categories
+
+| Category       | What It Captures                 | Examples                                        |
+| -------------- | -------------------------------- | ----------------------------------------------- |
+| Performance    | Speed, throughput, capacity      | Response time < 200ms, 1000 concurrent users    |
+| Security       | Auth, validation, rate limiting  | Sanitized inputs, session required, 100 req/min |
+| Compatibility  | Browsers, devices, accessibility | Chrome 100+, iOS 14+, WCAG 2.1 AA               |
+| Data           | Privacy, retention, compliance   | GDPR delete in 72h, 90-day log retention        |
+| Dependencies   | Existing systems, restrictions   | Use AuthService, no new packages                |
+| Infrastructure | Resources, offline, deployment   | < 512MB memory, offline-capable                 |
+
+### ✅ GOOD Constraints (Specific, Testable)
+
+```markdown
+### Performance
+
+- [ ] API response < 200ms at P95 under 100 concurrent users
+- [ ] Initial page load < 3s on simulated 3G
+
+### Security
+
+- [ ] All user inputs sanitized via DOMPurify
+- [ ] Rate limited: 100 requests/min per IP
+```
+
+### ❌ BAD Constraints (Vague, Untestable)
+
+```markdown
+### Performance
+
+- [ ] Should be fast ← How fast? Under what conditions?
+- [ ] Good performance ← Not measurable
+
+### Security
+
+- [ ] Secure ← What does this mean?
+- [ ] Protected from hackers ← Not specific
+```
+
+### Decision Rule
+
+**Include a constraint if:**
+
+- It affects how you write tests (performance tests, security tests)
+- It limits implementation choices (must use X, can't use Y)
+- Violating it would fail an audit or break SLAs
+
+**Skip if:**
+
+- It's a project-wide standard already in ARCHITECTURE.md
+- It's obvious (don't document "code must compile")
+
+### Tie-Breaking
+
+**If constraint fits multiple categories:** Choose the most specific one.
+
+| Constraint                 | Could Fit                     | Best Category  | Why                             |
+| -------------------------- | ----------------------------- | -------------- | ------------------------------- |
+| API rate limit 100 req/min | Security, Performance         | Security       | Rate limiting is access control |
+| Page load < 3s on 3G       | Performance, Compatibility    | Performance    | Speed is primary concern        |
+| Must work offline          | Infrastructure, Compatibility | Infrastructure | Offline is deployment concern   |
+
+**Edge case:** If truly cross-cutting (e.g., "GDPR compliance" spans Data + Security), pick one and add a note: "See also: Security constraints"
+
+---
+
+## LLM Optimization Tips
+
+**Core principle:** User stories are instructions that LLMs read and follow. Apply LLM instruction design best practices.
+
+**See:** `@.safeword/guides/llm-instruction-design.md` for comprehensive framework on writing LLM-consumable documentation.
+
+**When filling templates:**
+
+- Use specific, concrete language (not vague)
+- Avoid generic phrases ("improve UX", "make better")
+- Include numbers where relevant (200ms, 3 items, under 5 clicks)
+- Use concrete examples over abstract rules
+- Define all terms explicitly
+- Write for humans, not robots
+
+**Token efficiency:**
+
+- Template is 9 lines (minimal prompt caching cost)
+- No nested sections (flat structure)
+- No validation metadata in file
+
+---
+
+## File Naming Convention
+
+Save stories as: `.safeword/planning/user-stories/[slug].md`
+
+**Good filenames:**
+
+- `campaign-switching.md`
+- `export-character-pdf.md`
+- `stress-tracking.md`
+
+**Bad filenames:**
+
+- `user-story-1.md` ← Not descriptive
+- `STORY_CAMPAIGN_SWITCHING_FINAL_v2.md` ← Bloated

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

@@ -0,0 +1,219 @@
+# Zombie Process Cleanup (Multi-Project Environments)
+
+**When to use:** Working on multiple projects simultaneously, especially when they share tech stacks (Next.js, Playwright, etc.)
+
+---
+
+## The Problem
+
+When running dev servers and E2E tests across multiple projects, zombie processes accumulate:
+
+- Dev servers holding ports
+- Playwright browser instances
+- Test runners stuck in background
+- Build processes from previous sessions
+
+**CRITICAL:** NEVER use `killall node` or `pkill -9 node` when working on multiple projects - this kills processes from ALL projects.
+
+---
+
+## Port-Based Cleanup (Safest for Multi-Project)
+
+**Prerequisite:** Each project must use a different port (e.g., Project A: 3000, Project B: 3001)
+
+**Port convention:** Dev and test instances use different ports within the same project:
+
+- **Dev port**: Project's configured port (e.g., 3000, 5173, 8080) - manual testing
+- **Test port**: Dev port + 1000 (e.g., 4000, 6173, 9080) - Playwright managed
+
+See `testing-methodology.md` → "E2E Testing with Persistent Dev Servers" for full port isolation strategy.
+
+**Decision rule:** If unsure which cleanup method to use → port-based first (safest), then project script, then tmux.
+
+**Recommended cleanup pattern** (replace ports with your project's ports):
+
+```bash
+# Kill both dev server AND test server ports
+# Example: Next.js (3000/4000), Vite (5173/6173), or your project's ports
+lsof -ti:3000 -ti:4000 | xargs kill -9 2>/dev/null
+
+# Kill Playwright processes launched from THIS directory
+pkill -f "playwright.*$(pwd)" 2>/dev/null
+
+# Wait for cleanup
+sleep 2
+```
+
+**Why this works:**
+
+- ✅ Dev + test ports are unique to this project → safe to kill
+- ✅ `$(pwd)` ensures only THIS project's tests are killed
+- ✅ Other projects completely untouched
+
+---
+
+## Project-Specific Cleanup Script
+
+For frequent cleanup needs, create `scripts/cleanup.sh` in each project:
+
+```bash
+#!/bin/bash
+# scripts/cleanup.sh - Kill only THIS project's processes
+
+DEV_PORT=3000                    # Dev server port (change per project)
+TEST_PORT=$((DEV_PORT + 1000))   # Test server port (Playwright managed)
+PROJECT_DIR="$(pwd)"
+
+echo "Cleaning up $PROJECT_DIR (dev: $DEV_PORT, test: $TEST_PORT)..."
+
+# Kill both dev and test servers by port
+lsof -ti:$DEV_PORT -ti:$TEST_PORT | xargs kill -9 2>/dev/null
+
+# Kill Playwright browsers for this project
+ps aux | grep -E "(playwright|chromium)" | grep "$PROJECT_DIR" | grep -v grep | awk '{print $2}' | xargs kill -9 2>/dev/null
+
+# Kill test runners
+pgrep -f "playwright test.*$(basename $PROJECT_DIR)" | xargs kill -9 2>/dev/null
+
+echo "Cleanup complete!"
+```
+
+**Make executable:** `chmod +x scripts/cleanup.sh`
+
+**Usage:** `./scripts/cleanup.sh`
+
+---
+
+## Common Patterns by Tech Stack
+
+### Next.js Projects
+
+```bash
+# Kill Next.js dev server (port 3000)
+lsof -ti:3000 | xargs kill -9 2>/dev/null
+
+# Kill Next.js build processes for this project
+ps aux | grep "next dev" | grep "$(pwd)" | grep -v grep | awk '{print $2}' | xargs kill -9 2>/dev/null
+```
+
+### Playwright E2E Tests
+
+```bash
+# Kill Playwright browsers and test runners
+pkill -f "playwright.*$(pwd)" 2>/dev/null
+
+# Or more specific (by project name)
+pkill -f "playwright.*my-project-name" 2>/dev/null
+```
+
+### Vite Projects
+
+```bash
+# Kill Vite dev server (typically port 5173)
+lsof -ti:5173 | xargs kill -9 2>/dev/null
+```
+
+### React Native / Expo
+
+```bash
+# Kill Metro bundler (port 8081)
+lsof -ti:8081 | xargs kill -9 2>/dev/null
+
+# Kill Expo dev tools (port 19000-19006)
+lsof -ti:19000-19006 | xargs kill -9 2>/dev/null
+```
+
+---
+
+## Alternative: tmux/Screen Sessions
+
+For complete isolation, run each project in its own terminal session:
+
+```bash
+# Start project in named session
+tmux new -s project-name
+# Run dev server here
+
+# Kill everything in this session only
+tmux kill-session -t project-name
+```
+
+**Pros:**
+
+- ✅ Complete isolation between projects
+- ✅ One command kills everything
+- ✅ Can detach/reattach sessions
+
+**Cons:**
+
+- ⚠️ Requires learning tmux
+- ⚠️ Different workflow
+
+---
+
+## Best Practices
+
+1. **Assign unique ports** - Set `PORT=3000` in one project, `PORT=3001` in another
+2. **Use port-based cleanup first** - Simplest and safest
+3. **Create project cleanup scripts** - Reusable, documented
+4. **Never `killall node`** - Too broad when working on multiple projects
+5. **Clean up before starting** - Run cleanup script before `npm run dev`
+6. **Check what's running** - Use `lsof -i:PORT` to see what's using a port
+
+---
+
+## Debugging Zombie Processes
+
+### Find What's Using a Port
+
+```bash
+# Check what's on port 3000
+lsof -i:3000
+
+# More details
+lsof -i:3000 -P -n
+```
+
+### Find All Node Processes
+
+```bash
+# List all node processes
+ps aux | grep -E "(node|playwright|chromium)"
+
+# More detailed (with working directory)
+lsof -p $(pgrep node) | grep cwd
+```
+
+### Find Processes by Project Directory
+
+```bash
+# Find processes running in specific directory
+ps aux | grep "/Users/alex/projects/my-project"
+```
+
+---
+
+## Quick Reference
+
+| Situation                                | Command                                                          |
+| ---------------------------------------- | ---------------------------------------------------------------- |
+| Kill dev + test servers (use your ports) | `lsof -ti:$DEV_PORT -ti:$TEST_PORT \| xargs kill -9 2>/dev/null` |
+| Kill Playwright (this project)           | `pkill -f "playwright.*$(pwd)"`                                  |
+| Kill all for this project                | `./scripts/cleanup.sh`                                           |
+| Check what's on port                     | `lsof -i:3000`                                                   |
+| Find zombie processes                    | `ps aux \| grep -E "(node\|playwright\|chromium)"`               |
+| Kill by process ID                       | `kill -9 <PID>`                                                  |
+
+---
+
+## What NOT to Do
+
+❌ **DON'T:** `killall node` (kills all projects)
+❌ **DON'T:** `pkill -9 node` (kills all projects)
+❌ **DON'T:** Kill processes without checking working directory
+❌ **DON'T:** Assume zombie browsers will clean themselves up (they won't)
+
+✅ **DO:** Use port-based cleanup
+✅ **DO:** Filter by project directory with `$(pwd)`
+✅ **DO:** Create project-specific cleanup scripts
+✅ **DO:** Clean up before AND after development sessions

package/templates/hooks/agents-md-check.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Safeword AGENTS.md self-healing hook
+# Ensures the AGENTS.md link is always present
+
+LINK='**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**'
+
+if [ ! -d ".safeword" ]; then
+  # Not a safeword project, skip
+  exit 0
+fi
+
+if [ ! -f "AGENTS.md" ]; then
+  # AGENTS.md doesn't exist, create it
+  echo "$LINK" > AGENTS.md
+  echo "SAFEWORD: Created AGENTS.md with safeword link"
+  exit 0
+fi
+
+# Check if link is present
+if ! grep -q "@./.safeword/SAFEWORD.md" AGENTS.md; then
+  # Link missing, prepend it
+  CONTENT=$(cat AGENTS.md)
+  echo -e "$LINK\n\n$CONTENT" > AGENTS.md
+  echo "SAFEWORD: Restored AGENTS.md link (was removed)"
+fi
+
+exit 0

package/templates/hooks/inject-timestamp.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
-# Inject Timestamp - Notification Hook
-# Outputs current Unix timestamp at session start for Claude's context awareness
+# Inject Timestamp - UserPromptSubmit Hook
+# Outputs current Unix timestamp for Claude's context awareness
 # Helps with accurate ticket timestamps and time-based reasoning
 
 echo "Current time: $(date +%s) ($(date -u +%Y-%m-%dT%H:%M:%SZ))"
-

package/templates/hooks/post-tool.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Safeword post-tool hook
+# Placeholder for post-tool validations
+exit 0

package/templates/hooks/pre-commit.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Safeword pre-commit hook
+# Runs architecture checks before commit
+
+# Run linting if available
+if [ -f "package.json" ] && grep -q '"lint"' package.json; then
+  npm run lint --silent || exit 1
+fi
+
+exit 0

package/templates/lib/common.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Safeword common utilities for hook scripts
+
+# Output JSON response for Claude Code hooks
+# Usage: json_response '{"key": "value"}'
+json_response() {
+  echo "$1"
+}
+
+# Check if running in a safeword project
+is_safeword_project() {
+  [ -d ".safeword" ]
+}
+
+# Get project root (directory containing .safeword)
+get_project_root() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.safeword" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  return 1
+}

package/templates/lib/jq-fallback.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Fallback JSON output when jq is not available
+# Uses printf for safe JSON string escaping
+
+# Escape a string for JSON output
+json_escape() {
+  local str="$1"
+  str="${str//\\/\\\\}"
+  str="${str//\"/\\\"}"
+  str="${str//$'\n'/\\n}"
+  str="${str//$'\t'/\\t}"
+  echo "$str"
+}
+
+# Output a simple JSON object with one key-value pair
+json_kv() {
+  local key="$1"
+  local value="$2"
+  printf '{"proposedChanges": false, "madeChanges": false, "askedQuestion": false, "%s": "%s"}\n' "$key" "$(json_escape "$value")"
+}

package/templates/markdownlint.jsonc

@@ -0,0 +1,25 @@
+{
+  // Safeword markdownlint configuration
+  "default": true,
+
+  // Allow inline HTML (needed for some markdown features)
+  "MD033": false,
+
+  // Allow multiple headings with same content
+  "MD024": {
+    "siblings_only": true
+  },
+
+  // Line length - be lenient
+  "MD013": {
+    "line_length": 120,
+    "code_blocks": false,
+    "tables": false
+  },
+
+  // Allow trailing punctuation in headings
+  "MD026": false,
+
+  // Allow emphasis as heading
+  "MD036": false
+}

package/templates/prompts/arch-review.md

@@ -0,0 +1,43 @@
+# Architecture Review Prompt
+
+Review the following code changes for architectural issues.
+
+## Check for:
+
+1. **Misplaced logic** - Business rules in wrong layer?
+2. **God module** - Too many responsibilities (>10 dependents or >500 lines)?
+3. **Leaky abstraction** - Implementation details exposed to callers?
+4. **Tight coupling** - Changes would cascade unnecessarily?
+5. **Boundary violation** - Import from disallowed layer?
+
+## Context
+
+Read the project's ARCHITECTURE.md for:
+
+- Defined layers and their responsibilities
+- Allowed dependencies between layers
+- Project-specific patterns and conventions
+
+## Response Format
+
+Return JSON:
+
+```json
+{
+  "issues": [
+    {
+      "type": "misplaced_logic | god_module | leaky_abstraction | tight_coupling | boundary_violation",
+      "location": "file:line or module name",
+      "description": "What's wrong",
+      "fix": "How to fix it"
+    }
+  ],
+  "verdict": "clean | minor | refactor_needed"
+}
+```
+
+### Verdict definitions:
+
+- **clean**: No issues found
+- **minor**: Small issues that should be noted but don't block commit
+- **refactor_needed**: Significant issues that should be addressed before commit

package/templates/prompts/quality-review.md

@@ -0,0 +1,10 @@
+# Quality Review Prompt
+
+Double check and critique your work just in case.
+
+- Is it correct?
+- Is it elegant?
+- Does it adhere to the latest documentation and best practices for the relevant stack items, UX principles, domain requirements, and testing practices?
+- Ask me any non-obvious questions you can't research yourself in the codebase or online.
+- Think hard.
+- Avoid bloat.