safeword 0.6.3 → 0.6.5

package/templates/SAFEWORD.md

@@ -1,134 +1,57 @@
-# Global Instructions for AI Coding Agents
+# SAFEWORD Agent Instructions
 
-This file provides core guidance for all AI coding agent sessions. Organized modularly for maintainability.
+Core guidance for AI coding agents. Uses imports for detailed workflows.
 
 ---
 
-## Planning Documentation Location
+## Quick Reference
 
-**All planning markdown files go in `.safeword/planning/` at project root:**
-
-- User stories → `.safeword/planning/user-stories/`
-- Test definitions → `.safeword/planning/test-definitions/`
-- Design docs → `.safeword/planning/design/`
-- Issue capture → `.safeword/planning/issues/`
-
-**Archive completed work:** When planning docs are completed and no longer actively referenced, move to:
-
-- `.safeword/planning/user-stories/archive/`
-- `.safeword/planning/test-definitions/archive/`
-- `.safeword/planning/design/archive/`
-- `.safeword/planning/issues/archive/`
-
-**Why archive:** Prevents bloat in active planning folders while preserving history for reference.
-
-**Fallback:** If project uses `docs/` structure instead, follow existing convention.
+| Task                     | Guide                                          |
+| ------------------------ | ---------------------------------------------- |
+| Feature development      | @./.safeword/guides/development-workflow.md    |
+| User stories             | @./.safeword/guides/user-story-guide.md        |
+| Test definitions         | @./.safeword/guides/test-definitions-guide.md  |
+| TDD patterns / examples  | @./.safeword/guides/tdd-best-practices.md      |
+| Design docs              | @./.safeword/guides/design-doc-guide.md        |
+| Architecture decisions   | @./.safeword/guides/architecture-guide.md      |
+| Data architecture        | @./.safeword/guides/data-architecture-guide.md |
+| LLM integration & docs   | @./.safeword/guides/llm-guide.md               |
+| Context file maintenance | @./.safeword/guides/context-files-guide.md     |
+| Learning extraction      | @./.safeword/guides/learning-extraction.md     |
+| Process cleanup          | @./.safeword/guides/zombie-process-cleanup.md  |
+| Code standards           | @./.safeword/guides/code-philosophy.md         |
+| Safeword CLI             | @./.safeword/guides/cli-reference.md           |
 
 ---
 
-## Setup Scripts (Project Initialization)
-
-**Purpose:** Self-contained setup scripts for installing Claude Code hooks and configurations in your projects.
-
-**Available scripts:**
-
-- `setup-safeword.sh` - **One-command installer** (copies guides/templates, planning/tickets/learnings, adds triggers)
-- `setup-claude.sh` - Sets up Claude hooks, Arcade MCP gateway, CLAUDE.md trigger
-- `setup-linting.sh` - Auto-linting on file changes (ESLint + Prettier)
-- `setup-quality.sh` - Quality review prompts (Stop hook) and settings
-
-**Usage:**
-
-**One-command setup (recommended):**
-
-```bash
-cd /path/to/your/project
-bash ./framework/scripts/setup-safeword.sh            # Install SAFEWORD structure + docs
-bash ./framework/scripts/setup-claude.sh              # Install Claude hooks (+ MCP gateway)
-```
-
-**Auto-detection:** Automatically detects project type from package.json and config files:
-
-- Next.js → if next in dependencies (ESLint + React plugins)
-- Electron → if electron in dependencies
-- Astro → if astro in dependencies
-- React → if react in dependencies
-- TypeScript → if typescript in dependencies or tsconfig.json exists
-- Minimal → otherwise
-
-**Individual scripts (advanced):**
-
-```bash
-cd /path/to/your/project
-bash ./framework/scripts/setup-linting.sh --typescript  # Linting only
-bash ./framework/scripts/setup-quality.sh               # Quality review only
-```
-
-**Linting:** Auto-detects TypeScript, React, Astro from package.json.
-
-- Two-file architecture:
-  - `.safeword/eslint/eslint-base.mjs` - Auto-generated every run (DO NOT EDIT)
-  - `eslint.config.mjs` - Your config (customize freely, never overwritten)
-- After adding/removing frameworks: just re-run `bash setup-linting.sh`
-- Override detection: `--no-typescript`, `--no-react`, `--no-astro`
-
-**What they create:**
-
-- `.safeword/SAFEWORD.md` - Global patterns and workflows (copied from this file)
-- `.safeword/guides/` - Reference documentation
-- `.claude/hooks/` - Hook scripts (with version comments)
-- `.claude/commands/` - Slash commands (`/lint`, `/review`, `/architecture`)
-- `.claude/settings.json` - Hook configuration (appends to existing)
-- `SAFEWORD.md` or `CLAUDE.md` - Project context file with ALWAYS trigger for @./.safeword/SAFEWORD.md
-  - If CLAUDE.md exists → prepends trigger
-  - If SAFEWORD.md exists → ensure it references @./.safeword/SAFEWORD.md
-  - If neither exists → creates SAFEWORD.md with trigger
-- Config files if needed (`eslint.config.mjs`, `.prettierrc`)
-
-**Key features:**
-
-- ✅ **Fully standalone** - All files copied to project, no external dependencies
-- ✅ **Version tracking** - Generated files include version comments
-- ✅ **Idempotent** - Safe to run multiple times, won't duplicate hooks
-- ✅ **Append-only** - Preserves existing custom hooks
-- ✅ **Order-independent** - Can run scripts in any order
-
-**Documentation:**
+## Planning Documentation
 
-- Consolidated setup guide: `README.md` (this folder)
+**Location:** `.safeword/planning/` at project root
 
-**For teams:**
-
-1. Get setup scripts (clone repo temporarily or download scripts)
-2. In each project, run one command:
-   ```bash
-   cd /path/to/project
-   bash ./framework/scripts/setup-safeword.sh  # One command, full setup
-   ```
-3. **Result**: Project becomes standalone with:
-   - `.safeword/SAFEWORD.md` - Global patterns (copy of this file)
-   - `.safeword/guides/` - Reference documentation
-   - `.claude/` - Hooks and commands
-
-- `SAFEWORD.md` or `CLAUDE.md` - Project context with @./.safeword/SAFEWORD.md reference
+- User stories → `.safeword/planning/user-stories/`
+- Test definitions → `.safeword/planning/test-definitions/`
+- Design docs → `.safeword/planning/design/`
+- Issues → `.safeword/planning/issues/`
 
-4. **COMMIT to repo**: Commit `.safeword/` and `.claude/` for team consistency
-5. **Delete source**: Can delete setup scripts/repo after running - project is fully portable
+**Archive:** Move completed docs to `archive/` subfolder within each.
 
 ---
 
-## Ticket System (Context Anchor for Non-Trivial Work)
+## Ticket System
 
-**Purpose:** Tickets serve as persistent memory to prevent context loss when work becomes complex, requires multiple attempts, or might spiral.
+**Purpose:** Context anchor to prevent LLM loops during complex work.
 
-**Not for archival** - Tickets are session anchors to prevent LLM loops and confusion.
+**Location:** `.safeword/tickets/{id}-{slug}.md`
 
-**Location:** `.safeword/tickets/`
+**Create ticket? Answer IN ORDER, stop at first match:**
 
-**Naming convention:** `{id}-{slug}.md`
+1. Multiple attempts likely needed? → Create ticket
+2. Multi-step with dependencies? → Create ticket
+3. Investigation/debugging required? → Create ticket
+4. Risk of losing context mid-session? → Create ticket
+5. None of above? → Skip ticket
 
-- Example: `001-fix-login-bug.md`, `002-add-oauth.md`, `003-debug-slow-query.md`
-- Planning docs (if needed) share same prefix: `002-add-oauth.md` in planning subfolders
+**Examples:** "Fix typo" → skip. "Debug slow login" → ticket. "Add OAuth" → ticket.
 
 **Minimal structure:**
 
@@ -136,641 +59,130 @@ bash ./framework/scripts/setup-quality.sh               # Quality review only
 ---
 id: 001
 status: in_progress
-created: 2025-11-24T19:00:00Z
-last_modified: 2025-11-24T19:09:00Z
 ---
 
-# Fix Login Button Not Responding
-
-**Goal:** Make login button respond to clicks
+# [Title]
 
-**Why:** Users can't log in - button does nothing on click
+**Goal:** [one sentence]
 
 ## Work Log
 
-- 2025-11-24T19:00:15Z Started: Investigating button click issue
-- 2025-11-24T19:02:30Z Found: onClick handler missing in Button component
-- 2025-11-24T19:05:00Z RED: Added test for button click (refs: tests/button.test.ts)
-- 2025-11-24T19:08:15Z GREEN: Added onClick handler; test passing (refs: 7f3e2a9)
-- 2025-11-24T19:09:00Z Complete: Button fixed, verified with test
-```
-
-**For complex features, add optional sections:**
-
-```markdown
-### Planning Docs
-
-- .safeword/planning/user-stories/002-oauth-login.md
-- .safeword/planning/test-definitions/002-oauth-login.md
-
-### Scope
-
-**In scope:** Google OAuth, account linking, token refresh
-**Out of scope:** Other providers (separate ticket)
-
-### Acceptance Criteria
-
-- [ ] All user stories completed
-- [ ] Security review passed
+- [timestamp] Started: [task]
+- [timestamp] Found: [finding]
+- [timestamp] Complete: [result]
 ```
 
-**Template:** Use `.safeword/templates/ticket-template.md` when creating a ticket.
-
-**Work Log is critical:** Log immediately after each action. Re-read ticket frequently to prevent loops.
-
-**When to create tickets (context-loss risk assessment):**
-
-**Create ticket if ANY of these apply:**
-
-- Work might require multiple attempts/approaches (styling bugs, performance issues)
-- Work has multiple steps with dependencies (A must work before B)
-- Investigation/debugging required (unknown cause, non-obvious solution)
-- Anything that might cause you to lose context or loop mid-session
-
-**Skip ticket if:**
-
-- Obvious one-shot change (fix typo, update constant, change text label)
-- Takes <2 minutes with zero risk of confusion or cascading issues
-- No investigation needed, solution is clear
-
-**Examples:**
-
-- "Fix typo in README" → No ticket (obvious, one-shot)
-- "Make button red" → Ticket (might break mobile, cascade issues)
-- "Debug slow login" → Ticket (investigation needed, multiple hypotheses)
-- "Add OAuth" → Ticket (complex, multi-step, planning docs needed)
-
-**Relationship to planning docs:**
-
-- **Ticket** = Context anchor (prevents loops, tracks attempts)
-- **Planning docs** = Detailed specs for complex features (user stories, test definitions)
-- **TodoWrite** = Task-level tracking within current work session
-
-**Workflow:**
-
-1. **Create ticket:** `.safeword/tickets/{id}-{slug}.md`
-2. **Fill in Goal + Why** (one sentence each) - This is your anchor
-3. **Add initial work log entry:** "Started: [task]"
-4. **Re-read ticket before EVERY significant action** - Check what you're trying to do
-5. **Log immediately** after each attempt, finding, commit, or blocker
-6. **For complex features:** Add planning docs, reference them in optional sections
-7. **When stuck:** Re-read work log - what have you tried? What's the goal?
-8. **When complete:** Log final entry, update status to `done`, ask user to confirm
-9. **After confirmation:** Move to `.safeword/tickets/completed/{id}-{slug}.md`
-
-**CRITICAL:** NEVER mark ticket as `done` or archive without explicit user confirmation. User must verify:
-
-- All acceptance criteria met
-- All tests passing
-- Feature works as expected
-- No regressions introduced
-
-**Archiving:**
-
-- Completed tickets → `.safeword/tickets/completed/`
-- Blocked/cancelled tickets → `.safeword/tickets/archived/`
-- Active tickets stay in `.safeword/tickets/`
-
-**Why confirm:** Prevents premature closure and ensures quality standards met.
-
----
-
-## Feature Development Workflow (CRITICAL - Always Follow)
-
-**When to read:** ALWAYS - Before starting ANY new feature, bug fix, or code change. This is the entry point for all development work.
-
-### Starting a New Feature
-
-**When user requests a new feature or references an issue number:**
-
-**IN ORDER:**
-
-**0. Check for Ticket / Create If Needed** (context-loss prevention)
-
-- Search `.safeword/tickets/` for matching ticket file
-- **If found:**
-  - **Read ticket first** - What's the goal? What have I tried?
-  - Check work log for previous attempts/findings
-  - Log: "Resumed work on [task]"
-  - **Re-read ticket before each significant action**
-  - For complex features: Follow planning docs if referenced
-- **If not found:**
-  - **Assess context-loss risk:**
-    - Obvious one-shot (<2 min, no investigation)? → Skip ticket, skip to TDD (step 4)
-    - Might require multiple attempts? → Create ticket, skip to TDD (step 4)
-    - Investigation/debugging needed? → Create ticket, skip to TDD (step 4)
-    - Complex feature (multi-story)? → Create ticket, continue to planning docs (step 1)
-
-1. **User Stories + Technical Constraints** - Search `.safeword/planning/user-stories/` or `docs/user-stories/`
-   - Not found → Ask user if they exist elsewhere or offer to create
-   - Found → Read them (including Technical Constraints section)
-   - **Technical Constraints:** Non-functional requirements (performance, security, compatibility) that inform test definitions
-   - **Guide:** `@./.safeword/guides/user-story-guide.md`
-
-2. **Test Definitions** - Search `.safeword/planning/test-definitions/` or `docs/test-definitions/`
-   - Not found → Ask user if they exist elsewhere or offer to create
-   - Found → Read them
-   - **Guide:** `@./.safeword/guides/test-definitions-guide.md`
-
-3. **Design Doc** (complex features only) - Search `.safeword/planning/design/` or `docs/design/`
-   - Complex = >3 components, spans 2+ user stories, new data model, or architectural decisions
-   - Not found → Ask if needed, create if yes
-   - Found → Read it
-   - **Guide:** `@./.safeword/guides/design-doc-guide.md`
-
-4. **Follow STRICT TDD Workflow** (RED → GREEN → REFACTOR)
-   - Write failing tests first (RED phase)
-   - Implement minimum code to pass (GREEN phase)
-   - Refactor while keeping tests green
-   - **Workflow:** `@./.safeword/guides/testing-methodology.md` (comprehensive TDD guidance and test type decision tree)
-
-5. **Update Ticket** (if applicable)
-   - **Re-read ticket frequently** - Before each action, check: What's the goal? What have I tried?
-   - **Log immediately** after each action - Don't batch; log as you go
-   - Log: attempts (tried X, result Y), findings (found Z), commits, blockers, decisions
-   - When work complete: Log final entry, update status to `done`
-   - **Ask user to confirm** completion before archiving
-   - After confirmation: Move to `.safeword/tickets/completed/`
-
-**IMPORTANT:** Do not skip to implementation without user stories and test definitions. Follow TDD strictly.
-
-**Edge cases:**
-
-- User stories exist but test definitions don't → Create test definitions before implementation
-- User stories missing Technical Constraints → Add constraints before test definitions
-- Test definitions exist but user stories don't → Ask if user stories needed
-- Neither exist → Create both before implementation
-- Ticket references non-existent planning docs → Create them first
-
----
-
-### Commit Frequently
-
-**Commit early, commit often:** Small, atomic commits after each meaningful change.
-
-**When to commit:**
-
-- After each test passes (GREEN phase)
-- Before refactoring (safe point to revert)
-- After successful refactor
-- When switching context or tasks
-- After completing a logical unit of work
-
-**Why:** Prevents work loss, enables easy rollback, creates reviewable history.
-
----
-
-### When to Update Architecture Docs
-
-**Update project/package ARCHITECTURE.md when:**
-
-- Making technology choices (state management, database, frameworks)
-- Designing data models or schemas
-- Establishing project-wide patterns/conventions
-- Discovering architectural insights during implementation
-- Recording "why" behind major decisions
-
-**Use Design Doc instead when:**
-
-- Implementing a specific feature
-- Documenting component interactions for one feature
-- Feature-specific technical decisions
-- Implementation details (not project-wide principles)
-
-**Quick Decision Matrix:**
-
-| Question                    | Architecture Doc | Design Doc    |
-| --------------------------- | ---------------- | ------------- |
-| Tech/framework choice?      | ✅               | —             |
-| Data model design?          | ✅               | References it |
-| New feature implementation? | —                | ✅            |
-| Component breakdown?        | —                | ✅            |
-
-**Tie-breaking rule:** If decision affects 2+ features or multiple developers → Architecture doc. If feature-specific only → Design doc.
-
-**Reference:** `@./.safeword/guides/architecture-guide.md`
-
----
-
-### Layers & Boundaries
-
-**When to read:**
-
-- Setting up code organization for a new project
-- Questions about layer structure (app, domain, infra, shared)
-- Dependency rules between layers
-- Setting up `eslint-plugin-boundaries` for enforcement
-- Architectural boundary violations in code review
-
-4-layer architecture (app, domain, infra, shared), allowed dependency matrix, and static enforcement via ESLint.
-
-**Guide:** `@./.safeword/guides/architecture-guide.md` → Layers & Boundaries section
-
----
-
-### Architecture Review (LLM)
-
-**When to read:**
-
-- Running semantic architecture review on code changes
-- Setting up pre-commit hook for architecture enforcement
-- Setting up CI workflow for PR architecture checks
-- Understanding architecture review verdicts (clean/minor/refactor_needed)
-- Checking for: god modules, leaky abstractions, misplaced logic, tight coupling
-
-**Command:** `/architecture`
-**Prompt:** `.safeword/prompts/architecture.md`
-**CI Template:** `.safeword/templates/ci/architecture-check.yml`
-
----
-
-### Creating Documentation (Explicit User Requests)
-
-**Note**: When user explicitly requests documentation, skip the workflow questions and create directly.
-
-**User Stories:**
-
-- **Trigger (Create):** User says "Create user stories for issue #N" or "Create user stories for [feature]"
-- **Trigger (Review):** User asks "Is this story good?" or "Review my user story"
-- **Trigger (Constraint Review):** User asks "Is this constraint good?" or "Review my constraints"
-- Skip the "Do user stories exist?" question (user is explicitly requesting creation)
-- **Include Technical Constraints:** Fill in performance, security, compatibility, data, dependencies, infrastructure constraints that will inform test definitions
-- **Template:** `@./.safeword/templates/user-stories-template.md`
-- **Guide:** `@./.safeword/guides/user-story-guide.md`
-
-**Test Definitions:**
-
-- **Trigger:** User says "Create test definitions for issue #N" or "Create test definitions for [feature]"
-- Skip the "Do test definitions exist?" question (user is explicitly requesting creation)
-- **Template:** `@./.safeword/templates/test-definitions-feature.md`
-- **Guide:** `@./.safeword/guides/test-definitions-guide.md`
+**Rules:**
 
-**Design Doc:**
+- Log immediately after each action
+- Re-read ticket before significant actions
+- **CRITICAL:** Never mark `done` without user confirmation (prevents premature closure)
 
-- **Trigger:** User says "Create design doc for [feature]" or "Design [system/component]"
-- Skip the "Does design doc exist?" question (user is explicitly requesting creation)
-- **Prerequisites:** Verify user stories and test definitions exist first (create if not)
-
-**Required sections checklist:**
-
-- [ ] **Architecture** — 1-2 paragraphs on high-level approach
-- [ ] **Components** — [N] and [N+1] examples with name, responsibility, interface, dependencies
-- [ ] **User Flow** — Step-by-step with concrete examples
-- [ ] **Key Decisions** — What, why, trade-off, alternatives considered
-- [ ] **Data Model** — (if applicable) State shape, relationships
-- [ ] **Component Interaction** — (if applicable) How components communicate
-- [ ] **Implementation Notes** — (if applicable) Constraints, error handling, gotchas
-
-- **Template:** `@./.safeword/templates/design-doc-template.md`
-- **Guide:** `@./.safeword/guides/design-doc-guide.md`
-
-**Architecture Doc:**
-
-- **Trigger (Create):** Starting a new project/package, or no `ARCHITECTURE.md` exists yet
-- **Trigger (Update):** User says "Update architecture doc" or "Document [architectural decision]"
-- **Trigger (Implicit):** After discussing architectural decisions, proactively ask: "Should I document this in ARCHITECTURE.md?"
-- **Recognize architectural discussions when user mentions:**
-  - Technology choices (state management, database, frameworks)
-  - Data model design
-  - Project-wide patterns/conventions
-
-**Required sections checklist** (verify all present when creating/reviewing):
-
-- [ ] **Header** — Version, Last Updated, Status (Production/Design/Proposed)
-- [ ] **Table of Contents** — Section links
-- [ ] **Overview** — Technology choices, data model philosophy, high-level architecture
-- [ ] **Data Architecture Principles** — What, Why, Trade-off for each principle
-- [ ] **Data Model / Schema** — Tables, types, relationships
-- [ ] **Component Design** — Major components and responsibilities
-- [ ] **Data Flow Patterns** — How data moves through the system
-- [ ] **Key Decisions** — What, Why, Trade-off, Alternatives Considered
-- [ ] **Best Practices** — Domain-specific patterns
-- [ ] **Migration Strategy** — How to evolve architecture
-- [ ] **Code References** — Link to implementations (`src/file.ts:line` or function names)
-
-**Anti-patterns to avoid:**
-
-- ❌ ADR sprawl (many separate files) → consolidate into one doc
-- ❌ Missing rationale → every decision needs "Why" with specifics
-- ❌ Implementation details → keep high-level principles only
-
-- **Template:** `@./.safeword/templates/architecture-template.md`
-- **Guide:** `@./.safeword/guides/architecture-guide.md`
-
-**Data Architecture Doc:**
-
-- **Trigger (Explicit):** User says "Document data architecture" or "Design data model"
-- **Trigger (Implicit):** When discussing database schema, data flows, or storage decisions
-- **Recognize data architecture discussions when user mentions:**
-  - Database/storage technology choices
-  - Schema design (entities, relationships, constraints)
-  - Data validation rules, access policies, lifecycle
-  - Data flows (sources, transformations, destinations)
-- **Section in ARCHITECTURE.md or separate file** - Depends on project complexity
-- **Guide:** `@./.safeword/guides/data-architecture-guide.md`
+**Full template:** `.safeword/templates/ticket-template.md`
 
 ---
 
-## TodoWrite Best Practices
-
-**When to use:** Complex multi-step tasks (3+ distinct steps), non-trivial tasks requiring planning, or when user provides multiple tasks.
-
-**Critical rules:**
+## Feature Development (CRITICAL)
 
-- ✓ **Create as first tool call** - For multi-step tasks, create TODO list before starting work
-- ✓ **Use VERY frequently** - Track tasks and give user visibility into progress
-- ✓ **Mark in_progress BEFORE work** - Ideally only ONE task in_progress at a time
-- ✓ **Complete immediately** - Mark completed as soon as done, don't batch
-- ✓ **Two forms required** - `content` (imperative: "Run tests") + `activeForm` (continuous: "Running tests")
-- ✓ **Replace entire list** - Updates replace complete list, not incremental changes
+**Always follow this order:**
 
-**When NOT to use:**
+1. **Check/create ticket** if context-loss risk exists (see decision tree above)
+2. **Read user stories** (`.safeword/planning/user-stories/`)
+3. **Read test definitions** (`.safeword/planning/test-definitions/`)
+4. **Read design doc** if complex (>3 components OR 2+ user stories)
+5. **TDD: RED → GREEN → REFACTOR**
+6. **Update ticket** with progress, ask user to confirm completion
 
-- Single straightforward task
-- Trivial operations (1-2 simple steps)
-- Purely conversational requests
+**Edge cases:**
 
-**Example:**
+| Situation                           | Action                            |
+| ----------------------------------- | --------------------------------- |
+| User stories exist, test defs don't | Create test defs first            |
+| Test defs exist, user stories don't | Ask if user stories needed        |
+| Neither exist                       | Create both before implementation |
 
-```json
-{
-  "todos": [
-    {
-      "content": "Write failing tests",
-      "status": "completed",
-      "activeForm": "Writing failing tests"
-    },
-    {
-      "content": "Implement minimum code to pass",
-      "status": "in_progress",
-      "activeForm": "Implementing minimum code"
-    },
-    {
-      "content": "Refactor while keeping tests green",
-      "status": "pending",
-      "activeForm": "Refactoring code"
-    }
-  ]
-}
-```
+**Full workflow:** @./.safeword/guides/development-workflow.md
 
 ---
 
-## Response Format (CRITICAL - Always Include)
-
-At the end of EVERY response, include a JSON summary with this exact structure:
+## Self-Testing (CRITICAL)
 
-```json
-{"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
-```
+**Never ask the user to test what you can test yourself.**
 
-Where (all fields describe **this response only**, not cumulative):
+- After fixes → run relevant tests
+- After features → run affected tests
+- Before completion → verify everything passes
 
-- `proposedChanges`: `true` if you suggested/proposed changes to specific files **in this response**
-- `madeChanges`: `true` if you **modified files in this response** using Write/Edit tools
-- `askedQuestion`: `true` if you asked the user a question and need their response before proceeding
-
-Examples:
+**Anti-patterns:**
 
-- Discussed approach only: `{"proposedChanges": false, "madeChanges": false, "askedQuestion": false}`
-- Proposed edits but waiting for approval: `{"proposedChanges": true, "madeChanges": false, "askedQuestion": false}`
-- Made edits directly: `{"proposedChanges": false, "madeChanges": true, "askedQuestion": false}`
-- Proposed AND made edits: `{"proposedChanges": true, "madeChanges": true, "askedQuestion": false}`
-- Asked user a question: `{"proposedChanges": false, "madeChanges": false, "askedQuestion": true}`
-- **Quality review response** (no new changes): `{"proposedChanges": false, "madeChanges": false, "askedQuestion": false}`
+- ❌ "Please refresh and test"
+- ❌ "Can you verify it works?"
+- ✅ "Fixed. Running tests..." → "Tests pass ✓"
 
 ---
 
-## Avoid Over-Engineering
-
-**Trigger:** Before adding any abstraction, utility, or "future-proofing" code.
+## Code Quality
 
-**Decision:** Is this the simplest solution that works?
+**Avoid over-engineering:**
 
 | ❌ Over-engineering               | ✅ Keep it simple   |
 | --------------------------------- | ------------------- |
 | Utility class for one function    | Single function     |
 | Factory/builder for simple object | Direct construction |
 | Config file for 2 options         | Hardcode or params  |
-| Abstract class with one impl      | Concrete class      |
-
-**When to push back:** If feature adds >50 lines for "nice to have", ask user if essential now.
-
-**Self-documenting code:** Use descriptive names (`calculateTotalWithTax` not `calcTot`). Comment only non-obvious logic.
-
-**Error handling:** Never swallow errors. Include context: `Failed to read ${filePath}: ${e.message}`
 
-**Debug logging:** Log actual vs expected values. Remove debug logs after fixing.
+**Rules:**
 
-**Cross-platform:** Use `path.join()` not string concat. No hardcoded `/` or `\`.
-
-**Guide:** `@./.safeword/guides/code-philosophy.md`
+- If feature adds >50 lines for "nice to have", ask user first
+- Never swallow errors—include context: `Failed to X: ${e.message}`
+- Verify library APIs against package.json version + Context7 (training data is stale)
 
 ---
 
-## Self-Testing (CRITICAL - Always Test Your Own Work)
-
-**The user's time is precious. Always test your own work before declaring it complete.**
-
-**Core principle:** NEVER ask the user to verify or test something you can test yourself. Run tests, verify fixes, and confirm functionality before reporting completion.
-
-**When to self-test:**
-
-- ✓ **After fixing bugs** - Run the relevant tests to verify the fix works
-- ✓ **After implementing features** - Run all affected tests (unit, integration, E2E)
-- ✓ **After making changes** - Verify the change has the intended effect
-- ✓ **Before declaring completion** - Always run tests yourself, don't ask the user to do it
-- ✓ **When uncertain** - If you're not sure it works, TEST IT before claiming success
-
-**Tools for self-testing:**
-
-- E2E tests: `pnpm test:e2e` or specific test files
-- Unit tests: `pnpm test` or `pnpm test:unit`
-- Integration tests: `pnpm test:integration`
-- Manual verification: Use curl, check browser console, verify API responses
-- Dev server: Check compilation errors, hot reload, runtime errors
-
-**Capturing test output:**
-
-Don't pipe through `head`/`tail` directly—capture to a timestamped log file first, then analyze:
-
-```bash
-# ✅ GOOD - Capture to file, then analyze
-mkdir -p /tmp/test-logs
-LOG=/tmp/test-logs/$(date +%s)-e2e.log
-pnpm test:e2e 2>&1 | tee $LOG
-tail -100 $LOG  # Check summary
-cat $LOG        # Full output if needed
-
-# ❌ BAD - Can't dig deeper without re-running tests
-pnpm test:e2e 2>&1 | tail -50
-```
-
-**Anti-patterns:**
-
-- ❌ **DON'T:** "I've made the changes. Please refresh your browser and test."
-- ❌ **DON'T:** "The fix should work now. Can you verify?"
-- ❌ **DON'T:** "Try it now and let me know if it works."
+## TodoWrite
 
-**Correct patterns:**
+**Use for:** 3+ step tasks, non-trivial work, multiple user requests.
 
-- ✅ **DO:** "I've fixed the issue. Let me run the tests to verify..." [runs tests] "Tests pass ✓"
-- ✅ **DO:** "Fixed the bug. Running E2E tests to confirm..." [runs tests] "All tests passing ✓"
-- ✅ **DO:** "Implemented the feature. Testing now..." [runs tests] "Tests confirm it works ✓"
+**Rules:**
 
-**Example workflow:**
-
-```
-1. User reports bug: "Button doesn't enable when typing"
-2. Investigate and fix the bug
-3. Run tests yourself: AUTH_MODE=demo pnpm exec playwright test
-4. Verify tests pass
-5. Report to user: "Fixed. Tests confirm button now enables correctly ✓"
-```
-
-**Edge cases:**
-
-- If tests require special setup (API keys, credentials): Mention requirements but still run what you can
-- If tests are slow (>5 min): Run them in background, show progress, report when done
-- If no automated tests exist: Create them as part of the fix, then run them
-
-**Remember:** The user should only test when they want to verify the UX/experience themselves, not to confirm your code works. Your code working is YOUR responsibility to verify.
-
-**Before declaring complete:** Run self-review checklist (correctness, elegance, best practices, docs/versions, tests). Note any deferred issues.
+- Create as first tool call
+- One task `in_progress` at a time
+- Mark completed immediately (don't batch)
 
 ---
 
-## Code Philosophy & Practices
-
-**When to read:** Before writing code, when making architectural decisions, or when unsure about coding standards and best practices.
-
-**Documentation verification:** Before using any library API, check `package.json` for version and verify with Context7 or official docs. Training data is stale.
-
-Core coding principles, testing philosophy (TDD), communication style, best practices, and tooling currency.
+## Response Format
 
-@./.safeword/guides/code-philosophy.md
+End every response with:
 
----
-
-## TDD Templates & Best Practices Reference
-
-**When to read:** When creating user stories, test definitions, design docs, or evaluations. Provides templates and examples of good vs bad practices.
-
-**Triggers:**
-
-- Creating user stories, test definitions, or design docs
-- User asks "Which template should I use?" or "What doc type for X?"
-- Need examples of good vs bad user stories or tests
-
-User story templates (As a X / Given-When-Then), test definition patterns, and concrete examples.
-
-@./.safeword/guides/tdd-best-practices.md
-
----
-
-## Testing Methodology
-
-**When to read:** Before starting ANY feature (TDD workflow), when choosing test type (unit/integration/E2E/LLM eval), or when writing tests.
-
-Comprehensive TDD workflow (RED → GREEN → REFACTOR), test pyramid, decision trees, async testing, project-specific docs guidance.
-
-@./.safeword/guides/testing-methodology.md
-
----
-
-## LLM Prompting Best Practices
-
-**When to read:** When working with AI features, writing prompts, implementing LLM evaluations, or optimizing AI costs.
-
-Prompt engineering, cost optimization (caching strategies), and testing AI outputs (LLM-as-judge).
-
-@./.safeword/guides/llm-prompting.md
-
----
-
-## Writing Instructions for LLMs
-
-**When to read:** When creating or updating ANY documentation that LLMs will read (CLAUDE.md, AGENTS.md, user stories, test definitions, design docs, architecture docs, guides).
-
-13 core principles for LLM-consumable documentation: MECE decision trees, explicit definitions, concrete examples, no contradictions, edge cases explicit, actionable language, sequential decision trees, tie-breaking rules, lookup tables, no caveats in tables, percentages with context, specific technical terms, and re-evaluation paths.
-
-@./.safeword/guides/llm-instruction-design.md
-
----
-
-## AGENTS.md/CLAUDE.md File Structure & Maintenance
-
-**When to read:** When creating or updating project AGENTS.md/CLAUDE.md files, organizing documentation, or setting up new projects.
-
-How to write, organize, and maintain AGENTS.md/CLAUDE.md files across projects. Anti-patterns, examples, and modular approaches.
-
-@./.safeword/guides/context-files-guide.md
-
----
-
-## Project Memory
-
-**Context:** After extracting learnings (see Learning Extraction section below), add them to project documentation for team knowledge sharing.
-
-**Where to add:**
-
-- Architecture decisions: Add to ARCHITECTURE.md (or AGENTS.md if no ARCHITECTURE.md exists)
-- Common gotchas (1-2 sentences): Add to AGENTS.md → Common Gotchas section
-- Detailed learnings (needs examples): Extract to `.safeword/learnings/` and cross-reference in SAFEWORD.md
+```json
+{"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
+```
 
-**See:** Learning Extraction section below for full workflow
+- `proposedChanges`: suggested changes to files in this response
+- `madeChanges`: modified files using Write/Edit tools
+- `askedQuestion`: asked question, need response before proceeding
 
 ---
 
-## Zombie Process Cleanup
-
-**When to read:**
-
-- Working on multiple projects simultaneously
-- Port already in use errors (`EADDRINUSE`, `address already in use`)
-- Stuck processes (dev server won't start, tests hang)
-- Tech stacks: Next.js, Playwright, Vite, Expo
-
-Port-based cleanup strategies, project-specific scripts, and multi-project isolation techniques.
+## Commit Frequently
 
-@./.safeword/guides/zombie-process-cleanup.md
+- After each GREEN phase
+- Before refactoring
+- After successful refactor
+- When switching tasks
 
 ---
 
 ## Learning Extraction
 
-**When to read:** When experiencing debugging complexity (5+ debug cycles, user says "stuck"), discovering gotchas, trying multiple approaches, or during significant implementation work. Use to determine if/where to extract learnings and check for existing learnings.
-
-**Suggest extraction when you observe:**
-
-1. **Observable debugging complexity** - User says "stuck", 5+ debug cycles, 3+ error states, or 3+ files modified
-2. **Trial and error** - Tried 3+ different approaches
-3. **Undocumented gotcha** - Not in official library/framework docs
-4. **Integration struggle** - Two tools don't work together smoothly
-5. **Testing trap** - Tests pass but UX broken (or vice versa)
-6. **Architectural insight** - Discovered during implementation, not planned upfront
-
-**CRITICAL: Before extracting, ALWAYS check for existing learnings** to prevent duplication:
-
-- **Before debugging** - Check if similar issue has learning: `ls .safeword/learnings/*[technology]*.md`
-- **When user mentions technology/pattern** - Check for `*hooks*.md`, `*electron*.md`, etc.
-- **During architectural discussions** - Check for `*pattern*.md`, `*architecture*.md`
-- **After suggesting extraction** - Check if learning already exists, update instead of duplicate
-
-**When to reference existing learnings:**
-
-- Found → Read and apply: "I found an existing learning about [concept] at [path]. Applying it now."
-- Similar but different → Reference and note difference
-
-**Where to extract:**
-
-- `.safeword/learnings/[concept].md` - General patterns and best practices (React patterns, Git workflows, testing)
-- `.safeword/learnings/[concept].md` - Project-specific (custom architecture, unique patterns for this codebase)
+**Suggest extraction when ANY apply:**
 
-**Maintenance triggers:**
+- 5+ debug cycles on same issue
+- 3+ approaches tried
+- Undocumented gotcha discovered
+- Integration struggle between tools
 
-- Learning file >200 lines → Split into focused files
-- Multiple learnings cover similar topic → Consolidate
-- Technology deprecated → Archive with "OBSOLETE:" prefix
+**Before extracting:** Check `.safeword/learnings/` for existing similar learnings—update, don't duplicate.
 
-**Full workflow, templates, decision trees, and examples:** @./.safeword/guides/learning-extraction.md
+**Full workflow:** @./.safeword/guides/learning-extraction.md