safeword 0.6.8 → 0.7.0

package/templates/SAFEWORD.md

@@ -1,26 +1,79 @@
 # SAFEWORD Agent Instructions
 
-Core guidance for AI coding agents. Uses imports for detailed workflows.
+---
+
+## Code Philosophy
+
+**Optimize for:** Clarity → Simplicity → Correctness (in that order)
+
+| Principle        | Definition                                                       |
+| ---------------- | ---------------------------------------------------------------- |
+| Elegant code     | Readable at a glance; clear naming; minimal cognitive load       |
+| No bloat         | Delete unused code; no premature abstractions; no "just in case" |
+| Explicit errors  | Every catch block re-throws with context OR logs with details    |
+| Self-documenting | Comment only: business rules, workarounds, non-obvious "why"     |
+
+**Tie-breaker:** When in doubt, choose the simpler solution that works today.
 
 ---
 
-## Quick Reference
+## Anti-Patterns
 
-| 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           |
+| Don't                        | Do                                               | Why                       |
+| ---------------------------- | ------------------------------------------------ | ------------------------- |
+| `catch (e) {}`               | `throw new Error(\`Failed to X: ${e.message}\`)` | Silent failures hide bugs |
+| Utility class for 1 function | Single exported function                         | Abstraction without reuse |
+| Factory for simple object    | Direct construction                              | Indirection without value |
+| `data`, `tmp`, `d`           | `userProfile`, `pendingOrder`                    | Names should explain      |
+| Code "for later"             | Delete it; add when needed                       | YAGNI                     |
+| >50 lines for nice-to-have   | Ask user: "Essential now?"                       | Scope creep               |
+
+---
+
+## Before Using Any Library API
+
+Training data is stale. Follow this sequence:
+
+1. Check `package.json` for installed version
+2. Look up docs via Context7 or official site
+3. If uncertain: ask user which version they're using
+
+---
+
+## Guides
+
+**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         |
+
+---
+
+## Templates
+
+**Use the matching template when ANY trigger fires:**
+
+| Trigger                                                    | Template                                           |
+| ---------------------------------------------------------- | -------------------------------------------------- |
+| User asks for user story OR planning new feature scope     | @./.safeword/templates/user-stories-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          |
 
 ---
 
@@ -28,10 +81,20 @@ Core guidance for AI coding agents. Uses imports for detailed workflows.
 
 **Location:** `.safeword/planning/` at project root
 
-- User stories → `.safeword/planning/user-stories/`
-- Test definitions → `.safeword/planning/test-definitions/`
-- Design docs → `.safeword/planning/design/`
-- Issues → `.safeword/planning/issues/`
+| Type             | Path                                   | Contents                          |
+| ---------------- | -------------------------------------- | --------------------------------- |
+| Specs            | `.safeword/planning/specs/`            | `feature-*.md` and `task-*.md`    |
+| Test definitions | `.safeword/planning/test-definitions/` | `feature-*.md` (L2 features only) |
+| Design docs      | `.safeword/planning/design/`           | Complex features (3+ components)  |
+| Issues           | `.safeword/planning/issues/`           | Issue tracking                    |
+
+**Artifact Levels:**
+
+| Level  | Artifacts                                            | Test Location       |
+| ------ | ---------------------------------------------------- | ------------------- |
+| **L2** | Feature Spec + Test Definitions (+ Design Doc if 3+) | `test-definitions/` |
+| **L1** | Task Spec                                            | Inline in spec      |
+| **L0** | Task Spec (minimal)                                  | Existing tests      |
 
 **Archive:** Move completed docs to `archive/` subfolder within each.
 
@@ -76,66 +139,55 @@ status: in_progress
 
 - Log immediately after each action
 - Re-read ticket before significant actions
-- **CRITICAL:** Never mark `done` without user confirmation (prevents premature closure)
-
-**Full template:** `.safeword/templates/ticket-template.md`
+- **CRITICAL:** Never mark `done` without user confirmation
 
 ---
 
-## Feature Development (CRITICAL)
+## Feature Development
 
-**Always follow this order:**
+**Triage first - answer IN ORDER, stop at first match:**
+
+| Question                                 | Level          | Artifacts                    |
+| ---------------------------------------- | -------------- | ---------------------------- |
+| User-facing feature with business value? | **L2 Feature** | Spec + Test Defs (+ Design)  |
+| Bug, improvement, internal, or refactor? | **L1 Task**    | Spec with inline tests       |
+| Typo, config, or trivial change?         | **L0 Micro**   | Minimal spec, existing tests |
+
+**Then follow this order:**
 
 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)
+2. **Read/create spec** (`.safeword/planning/specs/`)
+3. **Read/create test definitions** (L2 only: `.safeword/planning/test-definitions/`)
+4. **Read/create design doc** if complex (3+ components)
 5. **TDD: RED → GREEN → REFACTOR**
 6. **Update ticket** with progress, ask user to confirm completion
 
 **Edge cases:**
 
-| 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 |
-
-**Full workflow:** @./.safeword/guides/development-workflow.md
+| Situation                 | Action                  |
+| ------------------------- | ----------------------- |
+| Spec exists, no test defs | Create test defs (L2)   |
+| Test defs exist, no spec  | Create spec first       |
+| Neither exist             | Create spec, then tests |
+| L0/L1 task                | Inline tests in spec    |
 
 ---
 
-## Self-Testing (CRITICAL)
+## Self-Testing
 
 **Never ask the user to test what you can test yourself.**
 
-- After fixes → run relevant tests
-- After features → run affected tests
-- Before completion → verify everything passes
+| After...          | Do                       |
+| ----------------- | ------------------------ |
+| Fixes             | Run relevant tests       |
+| Features          | Run affected test suites |
+| Before completion | Verify everything passes |
 
 **Anti-patterns:**
 
 - ❌ "Please refresh and test"
 - ❌ "Can you verify it works?"
-- ✅ "Fixed. Running tests..." → "Tests pass ✓"
-
----
-
-## Code Quality
-
-**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  |
-
-**Rules:**
-
-- 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)
+- ✅ "Fixed. Running tests..." → "Tests pass"
 
 ---
 
@@ -143,11 +195,11 @@ status: in_progress
 
 **Use for:** 3+ step tasks, non-trivial work, multiple user requests.
 
-**Rules:**
-
-- Create as first tool call
-- One task `in_progress` at a time
-- Mark completed immediately (don't batch)
+| Rule                             | Why                     |
+| -------------------------------- | ----------------------- |
+| Create as first tool call        | Plan before acting      |
+| One task `in_progress` at a time | Focus                   |
+| Mark completed immediately       | Don't batch completions |
 
 ---
 
@@ -159,18 +211,36 @@ End every response with:
 {"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
 ```
 
-- `proposedChanges`: suggested changes to files in this response
-- `madeChanges`: modified files using Write/Edit tools
-- `askedQuestion`: asked question, need response before proceeding
+| Field           | True when...                                    |
+| --------------- | ----------------------------------------------- |
+| proposedChanges | Suggested changes to files in this response     |
+| madeChanges     | Modified files using Write/Edit tools           |
+| askedQuestion   | Asked question, need response before proceeding |
 
 ---
 
 ## Commit Frequently
 
-- After each GREEN phase
-- Before refactoring
-- After successful refactor
-- When switching tasks
+Commit after: GREEN phase, before/after refactoring, when switching tasks.
+
+---
+
+## Code Fence Languages (MD040)
+
+When markdown lint reports MD040 (missing language), choose:
+
+| Content Type             | Language Hint                |
+| ------------------------ | ---------------------------- |
+| TypeScript/JavaScript    | `typescript` or `javascript` |
+| Shell commands           | `bash`                       |
+| JSON, YAML, TOML configs | `json`, `yaml`, `toml`       |
+| SQL queries              | `sql`                        |
+| Directory trees          | `plaintext`                  |
+| Templates, pseudocode    | `text`                       |
+| Command output, logs     | `text`                       |
+| Truly ambiguous          | `text`                       |
+
+**Why this matters:** Language hints help LLMs understand code context. Use real languages for real code, `text` for everything else.
 
 ---
 
@@ -184,5 +254,3 @@ End every response with:
 - Integration struggle between tools
 
 **Before extracting:** Check `.safeword/learnings/` for existing similar learnings—update, don't duplicate.
-
-**Full workflow:** @./.safeword/guides/learning-extraction.md

package/templates/commands/architecture.md

@@ -20,7 +20,7 @@ When the user invokes this command:
 
 ## Example Usage
 
-```
+```text
 /architecture
 ```
 

package/templates/commands/lint.md

@@ -27,6 +27,7 @@ npm run lint:md 2>&1 || true
 ## Summary
 
 After running, report:
+
 1. Any ESLint errors that couldn't be auto-fixed
 2. Any formatting issues
 3. Type errors (if TypeScript)

package/templates/commands/quality-review.md

@@ -23,7 +23,7 @@ When the user invokes this command:
 
 ## Example Usage
 
-```
+```text
 /quality-review
 ```
 

package/templates/cursor/rules/safeword-core.mdc

@@ -0,0 +1,5 @@
+---
+alwaysApply: true
+---
+
+@.safeword/SAFEWORD.md

package/templates/doc-templates/architecture-template.md

@@ -76,7 +76,7 @@ Boundaries enforced via `eslint-plugin-boundaries`. See `.safeword/guides/archit
 
 ### Relationships
 
-```
+```text
 [Entity A] 1──n [Entity B]
 [Entity B] n──n [Entity C]
 ```

package/templates/doc-templates/task-spec-template.md

@@ -0,0 +1,151 @@
+# Task: [Name]
+
+**Guide**: `@./.safeword/guides/development-workflow.md`
+**Template**: `@./.safeword/templates/task-spec-template.md`
+
+---
+
+## Standard Task (L1)
+
+Use for: bugs, improvements, internal work, refactors.
+
+```markdown
+# Task: [Name]
+
+**Type:** Bug | Improvement | Internal | Refactor
+
+**Scope:** [1-2 sentences describing what this task accomplishes]
+
+**Out of Scope:** [Explicit boundaries - what this task does NOT include]
+
+**Done When:**
+
+- [ ] [Observable outcome 1]
+- [ ] [Observable outcome 2]
+
+**Tests:**
+
+- [ ] [Test scenario 1 - what behavior to verify]
+- [ ] [Test scenario 2 - edge case or secondary behavior]
+```
+
+**Location:** `.safeword/planning/specs/task-[name].md`
+
+---
+
+## Micro Task (L0)
+
+Use for: typos, config changes, trivial fixes. Still scoped to prevent creep.
+
+```markdown
+# Task: [Name]
+
+**Type:** Micro
+
+**Scope:** [One sentence - exactly what is changing]
+
+**Out of Scope:** [Boundaries - prevents "while I'm here" expansion]
+
+**Done When:**
+
+- [ ] [Single observable outcome]
+
+**Tests:**
+
+- [ ] Existing tests pass (no new test needed)
+```
+
+**Location:** `.safeword/planning/specs/task-[name].md`
+
+---
+
+## Examples
+
+### L1: Bug Fix
+
+```markdown
+# Task: Fix login timeout after 30 minutes
+
+**Type:** Bug
+
+**Scope:** Session refresh logic in auth middleware. User stays logged in if active.
+
+**Out of Scope:** Session duration settings, auth flow changes, UI modifications.
+
+**Done When:**
+
+- [ ] User stays logged in if active within session window
+- [ ] Session refreshes on API calls
+
+**Tests:**
+
+- [ ] Unit: session refresh extends expiry timestamp
+- [ ] Unit: inactive session expires correctly after timeout
+```
+
+### L1: Improvement
+
+```markdown
+# Task: Add retry logic to API client
+
+**Type:** Improvement
+
+**Scope:** Add exponential backoff retry for failed API requests in http client.
+
+**Out of Scope:** Circuit breaker, rate limiting, request queuing, UI loading states.
+
+**Done When:**
+
+- [ ] Failed requests retry up to 3 times with exponential backoff
+- [ ] Permanent failures (4xx) do not retry
+
+**Tests:**
+
+- [ ] Unit: retries on 5xx errors with backoff
+- [ ] Unit: does not retry on 4xx errors
+- [ ] Unit: gives up after max retries
+```
+
+### L0: Micro
+
+```markdown
+# Task: Fix typo in auth error message
+
+**Type:** Micro
+
+**Scope:** Typo in login error ("authetication" → "authentication").
+
+**Out of Scope:** Error handling logic, other error messages, refactoring.
+
+**Done When:**
+
+- [ ] Typo fixed in error message string
+
+**Tests:**
+
+- [ ] Existing auth tests pass
+```
+
+---
+
+## Why L0 Needs Scope
+
+Even trivial tasks need boundaries. Without explicit "Out of Scope":
+
+- "Fix typo" becomes "improve all error messages"
+- "Update config" becomes "refactor config system"
+- "Rename variable" becomes "rename all related functions"
+
+The spec takes 30 seconds to write and prevents hours of scope creep.
+
+---
+
+## Relationship to Feature Specs
+
+| Type                  | Use When                                | Artifacts                            |
+| --------------------- | --------------------------------------- | ------------------------------------ |
+| **Feature Spec (L2)** | User-facing feature with business value | Feature spec + test definitions file |
+| **Task Spec (L1)**    | Bug, improvement, internal, refactor    | Task spec with inline tests          |
+| **Task Spec (L0)**    | Typo, config, trivial                   | Minimal task spec, existing tests    |
+
+For L2 features, use: `@./.safeword/templates/user-stories-template.md`

package/templates/doc-templates/ticket-template.md

@@ -30,7 +30,7 @@ last_modified: YYYY-MM-DDTHH:MM:SSZ
 
 **Examples:**
 
-```
+```text
 - 2025-11-24T18:50:00Z Started: Changing button background to red
 - 2025-11-24T18:51:30Z Tried: Added `background: red` to Button.css
 - 2025-11-24T18:52:00Z Found: Button now has white text on red (unreadable)
@@ -62,9 +62,7 @@ last_modified: YYYY-MM-DDTHH:MM:SSZ
 
 **In scope:**
 
--
-
-**Out of scope:**
+- **Out of scope:**
 
 -
 

package/templates/guides/architecture-guide.md

@@ -99,7 +99,7 @@ Answer **IN ORDER**. Stop at the first "Yes":
 
 **✅ GOOD:**
 
-```
+```plaintext
 project/
 ├── ARCHITECTURE.md
 └── docs/design/
@@ -273,7 +273,7 @@ Answer **IN ORDER**:
 
 ## File Organization
 
-```
+```plaintext
 project/
 ├── ARCHITECTURE.md              # Single comprehensive doc
 ├── .safeword/planning/

package/templates/guides/code-philosophy.md

@@ -192,7 +192,7 @@ Before completing any work, verify:
 - Use descriptive commit messages
 - Make atomic commits (one logical change per commit)
 
-```
+```text
 # ❌ Bad: "misc fixes"
 # ✅ Good: "fix: login button not responding to clicks"
 ```

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

@@ -61,7 +61,7 @@ Read it BEFORE working on any task in this project.
 
 **Example:**
 
-```
+```text
 Working in: /project/src/feature/
 Loaded context:
   ✓ /project/CLAUDE.md (Claude-specific guidance)
@@ -96,7 +96,7 @@ See root AGENTS.md for TDD workflow. This file covers test-specific patterns.
 
 ## File Structure Pattern
 
-```
+```plaintext
 project/
 ├─ SAFEWORD.md                  # Project context (references guides)
 ├─ CLAUDE.md                    # Claude-specific context
@@ -106,7 +106,7 @@ project/
 
 **Modular Approach (Recommended):**
 
-```
+```plaintext
 project/
 ├─ AGENTS.md / CLAUDE.md        # 50 lines: imports + structure
 ├─ docs/architecture.md         # 100 lines: architecture decisions

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

@@ -137,14 +137,14 @@
 
 **Creating design doc:**
 
-```
+```text
 User: "Create design doc for three-pane layout"
 You: [Read user stories and test definitions, then create design doc]
 ```
 
 **Updating design doc:**
 
-```
+```text
 User: "Update design doc to add error handling section"
 You: [Read existing design doc, add Implementation Notes section with error handling]
 ```

package/templates/guides/development-workflow.md

@@ -46,7 +46,7 @@ Tests are the specification. When a test fails, the implementation is wrong—no
 
 ### Test Speed Hierarchy (Fast → Slow)
 
-```
+```text
 Unit (milliseconds)      ← Pure functions, no I/O
   ↓
 Integration (seconds)    ← Multiple modules, database, API calls
@@ -186,7 +186,7 @@ function calculateTotal(amount: number, taxRate: number): number {
 
 Answer these questions in order to choose the test type. Questions are mutually exclusive - stop at the first match. If multiple seem to apply, use the tie-breaking rule (line 19): choose the faster one.
 
-```
+```text
 1. Does this test AI-generated content quality (tone, reasoning, creativity)?
    └─ YES → LLM Evaluation
       Examples: Narrative quality, prompt effectiveness, conversational naturalness

package/templates/guides/learning-extraction.md

@@ -103,7 +103,7 @@ ls ./.safeword/learnings/*keyword*.md
 
 **Found existing learning** → Read and apply it:
 
-```
+```text
 "I found an existing learning about [concept] at [path]. Let me read it and apply to your case..."
 [Read the file]
 "Based on the learning, here's how to handle this: [specific guidance from learning]"
@@ -113,7 +113,7 @@ ls ./.safeword/learnings/*keyword*.md
 
 **Similar but different** → Reference and note difference:
 
-```
+```text
 "This is similar to the [existing learning] at [path], but differs in [specific way].
 The existing learning covers [X], but your case involves [Y]."
 ```
@@ -122,7 +122,7 @@ The existing learning covers [X], but your case involves [Y]."
 
 **Scenario 1: Found relevant learning**
 
-```
+```text
 User: "I'm getting an async state update error with React hooks"
 → Check: ls .safeword/learnings/*react*.md *hooks*.md *async*.md
 → Found: react-hooks-async.md
@@ -133,7 +133,7 @@ User: "I'm getting an async state update error with React hooks"
 
 **Scenario 2: No existing learning**
 
-```
+```text
 User: "IndexedDB quota is behaving strangely in Safari"
 → Check: ls .safeword/learnings/*indexeddb*.md *safari*.md *quota*.md
 → Not found
@@ -142,7 +142,7 @@ User: "IndexedDB quota is behaving strangely in Safari"
 
 **Scenario 3: Update existing learning**
 
-```
+```text
 User: Debugging for 6 cycles, discovers new IndexedDB quirk
 → Suggest extraction
 → Check: ls .safeword/learnings/*indexeddb*.md
@@ -162,7 +162,7 @@ User: Debugging for 6 cycles, discovers new IndexedDB quirk
 
 ## Decision Tree
 
-```
+```text
 Just learned something valuable
 │
 ├─ Forward-looking? (useful on FUTURE work, not just this bug)
@@ -260,7 +260,7 @@ Actual: [What happened]
 
 [One-sentence takeaway]
 
-````
+````text
 
 ---
 
@@ -481,7 +481,7 @@ Project-specific gotchas in `.safeword/learnings/`:
 
 ## Directory Structure
 
-```
+```plaintext
 # Global learnings (all projects)
 .safeword/learnings/
 ├── react-state-async.md
@@ -506,7 +506,7 @@ Project-specific gotchas in `.safeword/learnings/`:
 
 **When to Split**:
 
-```
+```text
 # TOO BIG (250 lines covering 3 separate concepts)
 .safeword/learnings/electron-gotchas.md