safeword 0.2.4 → 0.2.5

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

@@ -1,457 +0,0 @@
-# Project Context Files (CLAUDE.md, CURSOR.md, AGENTS.md)
-
-## When to Create Context Files
-
-Create the file(s) that best match your tooling. It’s okay to have more than one if different tools are used.
-
-- `CLAUDE.md` (Claude-specific)
-  - Claude/Desktop or Claude Code-specific guidance (hooks, skills, MCP gateways)
-  - Prompts, behaviors, and non-obvious conventions for Claude
-- `CURSOR.md` (Cursor-specific)
-  - Editor/extension conventions, quick commands, keybindings, gotchas for Cursor
-- `AGENTS.md` (tool-agnostic)
-  - Generic “project context” consumed by multiple agents/editors
-
-All project context files should:
-
-- **CRITICAL:** Reference `.safeword/SAFEWORD.md` at the top
-- Architecture decisions with "why" (not just "what")
-- Design philosophy and conventions
-- Common gotchas specific to this codebase
-- Cross-references to subdirectory files
-
-**Subdirectory files** (e.g., `tests/AGENTS.md`, `packages/app/CLAUDE.md`) - Create when:
-
-- > 3 unique rules that don't fit in root
-- Working in that directory needs specialized context
-- **Skip if:** Directory is straightforward or already covered in root
-
-**Naming convention summary:**
-
-- `CLAUDE.md` for Claude-specific guidance
-- `CURSOR.md` for Cursor-specific guidance
-- `AGENTS.md` for cross-agent compatibility (tests, docs, most projects)
-
-## SAFEWORD Trigger (Required)
-
-**MANDATORY:** Every project-level context file (CLAUDE.md, CURSOR.md, AGENTS.md) must start with a trigger to SAFEWORD:
-
-```markdown
-# Project Name - Developer Context
-
-**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**
-
-The SAFEWORD.md file contains core development patterns, workflows, and conventions.
-Read it BEFORE working on any task in this project.
-
----
-
-[Rest of project-specific content...]
-```
-
-**Why:** `.safeword/SAFEWORD.md` contains universal workflows (TDD, feature development, etc.) that apply across all projects. Project files should only contain project-specific context.
-
-## Agent Context Auto-Loading Behavior
-
-**How Context Loading Works:**
-
-1. Tools typically load a root context file (CLAUDE.md, CURSOR.md, AGENTS.md)
-2. Subdirectory context files may load when working inside those dirs
-3. Hierarchical loading (root + subdirectory) is common
-
-**Example:**
-
-```
-Working in: /project/src/feature/
-Loaded context:
-  ✓ /project/CLAUDE.md (Claude-specific guidance)
-  ✓ /project/src/feature/AGENTS.md (feature-specific rules)
-```
-
-**Design implication:** Subdirectory files should assume root context is available
-
-- Use "See root SAFEWORD.md or AGENTS.md for architecture" cross-references
-- Don't duplicate root content in subdirectory files
-- Focus subdirectory files on specialized conventions for that area
-
-```markdown
-❌ BAD - tests/AGENTS.md duplicates root TDD workflow:
-
-## TDD Workflow
-
-1. Write failing tests first (RED)
-2. Implement minimum code (GREEN)
-3. Refactor while green
-
-✅ GOOD - tests/AGENTS.md references root:
-
-## Testing Conventions
-
-See root AGENTS.md for TDD workflow. This file covers test-specific patterns.
-```
-
-**Reliability note:** Auto-loading works best when you explicitly reference your file in conversation (e.g., "following the guidelines in CLAUDE.md"). Implicit automatic reference can be less reliable.
-
-**Deprecated:** `*.local.md` is no longer recommended - use imports instead for better multi-worktree support
-
-## File Structure Pattern
-
-```
-project/
-├─ SAFEWORD.md                  # Project context (references guides)
-├─ CLAUDE.md                    # Claude-specific context
-├─ CURSOR.md                    # Cursor-specific context (optional)
-└─ tests/AGENTS.md              # Test conventions (cross-agent)
-```
-
-**Modular Approach (Recommended):**
-
-```
-project/
-├─ AGENTS.md / CLAUDE.md        # 50 lines: imports + structure
-├─ docs/architecture.md         # 100 lines: architecture decisions
-└─ docs/conventions.md          # 80 lines: coding conventions
-```
-
-Main context file imports modules:
-
-```markdown
-@docs/architecture.md
-@docs/conventions.md
-```
-
-## Content Guidelines
-
-**Include:**
-
-- "Why" over "what" - Explain architectural trade-offs, not features
-- Project-specific conventions - Unique to THIS codebase
-- Domain requirements - Specialized knowledge (game mechanics, industry standards, UX patterns)
-- Concrete examples - Good vs bad patterns
-- Gotchas - Common mistakes developers make HERE
-- Cross-references - Link to subdirectories, don't duplicate
-
-**Exclude:**
-
-- Generic advice ("follow best practices")
-- Feature lists (put in README.md)
-- Setup instructions (put in README.md)
-- Phase tracking (put in ROADMAP.md)
-- API documentation (put in code comments)
-
-## Target Line Counts
-
-- Root: 100-200 lines (architecture + philosophy)
-- Subdirectories: 60-100 lines (focused conventions)
-- Total project: <500 lines across all files
-- **With imports:** Main file 50 lines, modules 100-150 lines each
-
-**Rule:** If >200 lines, extract to subdirectory or use imports.
-
-**File size:** Keep under 50KB for optimal performance (though no hard limit)
-
-## Anti-Patterns to Avoid
-
-❌ **Redundancy between root and subdirectory files** (#1 source of bloat)
-
-- Don't list all stores in root if packages/web/AGENTS.md covers them
-- Don't document testing patterns in root if tests/AGENTS.md exists
-- Don't repeat gotchas - reference subdirectory for details
-- Each fact stated exactly once, use cross-references elsewhere
-
-❌ **Implementation details in root file**
-
-- File paths (store.ts:127-137) belong in subdirectory files
-- Specific line numbers change frequently
-- File trees and directory structures
-- Line counts and feature status lists
-
-❌ **Testing sections in non-test files**
-
-- Testing philosophy → tests/AGENTS.md (always)
-- Test commands → tests/AGENTS.md or README.md
-- Test patterns → tests/AGENTS.md
-
-❌ **User-facing documentation**
-
-- Setup instructions → README.md
-- Development commands → README.md
-- Feature lists → ROADMAP.md
-- API documentation → Code comments or separate docs
-
-❌ **Generic advice**
-
-- "Use TypeScript" (not project-specific)
-- "Follow best practices" (too vague)
-- "Write tests" (duh - say WHICH tests for WHAT)
-
-❌ **Meta-commentary**
-
-- "Last Updated: 2025-01-19"
-- "This file was reduced from 634 → 152 lines"
-- Commit history (that's what git is for)
-
-❌ **Outdated information**
-
-- Revisit after major architectural changes
-- Remove sections when they no longer apply
-- Update cross-references when files move
-
-## Cross-Reference Pattern
-
-**Root file:**
-
-```markdown
-**Agents** (`app/src/agents/`) - LLM logic. See `/AGENTS.md`.
-```
-
-**Subdirectory file:**
-
-```markdown
-**Context:** Working with AI agents. See root `SAFEWORD.md`/`AGENTS.md` for architecture.
-```
-
-**Import pattern:**
-
-```markdown
-# Project Context
-
-See @README for project overview and @package.json for available npm commands.
-
-## Architecture
-
-@docs/architecture.md
-
-## Coding Standards
-
-@.safeword/guides/llm-prompting.md
-
-## Git Workflow
-
-Details in @docs/git-workflow.md
-```
-
-**Import features:**
-
-- **Relative paths:** `@docs/file.md` (relative to AGENTS.md location)
-- **Absolute paths:** `@/path/to/file.md`
-- **Home directory:** `@.safeword/guides/file.md` (personal conventions across all projects)
-- **Recursive imports:** Imported files can import others (max depth: 5 hops)
-- **Inline usage:** Can reference imports in text, not just standalone lines
-- **Code blocks:** Imports ignored inside `` `code spans` `` and code blocks
-
-## Example: Well-Structured Root (AGENTS.md / CLAUDE.md / CURSOR.md)
-
-```markdown
-# Project Name - Developer Context
-
-**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**
-
-The SAFEWORD.md file contains core development patterns, workflows, and conventions.
-Read it BEFORE working on any task in this project.
-
----
-
-Brief description. Current status.
-
-## Design Philosophy
-
-1. **Test-Driven Development (TDD):** Write tests before implementation
-2. **Core principle:** Why we chose this approach
-3. **Core principle:** Trade-offs we accepted
-
-## Architecture Decisions
-
-### Tech Choice 1
-
-**Decision:** What we chose
-**Why:** Reduces X, improves Y (specific numbers)
-**Trade-off:** Harder to debug, but worth it for UX
-**Gotcha:** Must do Z or it breaks
-
-## Domain Requirements
-
-### Game Mechanics (Blades in the Dark)
-
-- Position/effect system (rulebook p.8-12)
-- Fiction-first approach
-
-**Key principles:**
-
-- Position telegraphed before roll
-- Consequences flow from fiction
-
-### Document Editor UX
-
-- Performance <16ms per keystroke
-- Standard OS text editing conventions
-
-**Key principles:**
-
-- Fast is a feature
-- Don't reinvent native behavior
-
-## Common Gotchas
-
-1. **Thing:** Why it breaks (see Design Philosophy → Section)
-
-## File Organization
-
-**Dir** (`path/`) - Purpose. See `path/AGENTS.md`.
-```
-
-## Maintenance
-
-- Update when architecture changes
-- Remove outdated sections immediately
-- Consolidate if multiple files reference same concept
-- Test: Can new developer understand "why" from reading this?
-- **Use imports** to keep main file under 200 lines
-- Verify loaded context matches intent (check hierarchical loading behavior)
-
----
-
-## Domain Requirements Section (Optional)
-
-**When to add:**
-
-- Project has specialized domain knowledge (game mechanics, industry standards, UX patterns)
-- Domain concerns are non-obvious from codebase alone
-- You find yourself repeatedly explaining domain rules to AI
-
-**When to skip:**
-
-- Domain is obvious from code structure (REST API patterns)
-- Tech stack IS the domain (generic CRUD app)
-- Simple projects without specialized knowledge
-
-**Structure (easy to parse):**
-
-```markdown
-## Domain Requirements
-
-### [Domain Name 1]
-
-- [Key principle or rule]
-- [Key principle or rule]
-- [Resource reference if applicable]
-
-**Key principles:**
-
-- [Specific guideline with rationale]
-- [Specific guideline with rationale]
-
-### [Domain Name 2]
-
-- [Key principle or rule]
-- [Key principle or rule]
-
-**Key principles:**
-
-- [Specific guideline with rationale]
-```
-
-**Examples:**
-
-```markdown
-## Domain Requirements
-
-### Blades in the Dark Mechanics
-
-- Position/effect system (BITD rulebook p.8-12)
-- Stress and harm tracking (p.13-15)
-- Downtime and long-term projects (p.16-20)
-
-**Key principles:**
-
-- Fiction drives mechanics (not dice → narrative)
-- Position must be telegraphed before roll
-- Effect established collaboratively with player
-- Consequences flow from fiction, not arbitrary
-
-### Document Editor UX
-
-- Text editing performance (<16ms per keystroke)
-- Undo/redo granularity (word-level, not character)
-- Selection handling (standard OS conventions)
-
-**Key principles:**
-
-- Performance over features (fast is a feature)
-- Native OS behavior (don't reinvent text editing)
-- Accessibility first (screen readers, keyboard nav)
-
-### Conversational AI Patterns
-
-- GM tone: Collaborative, not dictatorial
-- Player agency: Always offer meaningful choices
-- Emergent narrative: Build on player ideas
-
-**Key principles:**
-
-- Ask questions, don't declare outcomes
-- "Yes, and..." over "No, but..."
-- Telegraph consequences before they happen
-```
-
-**Why this structure:**
-
-- ✅ **Easy to parse** - Simple markdown hierarchy (##, ###, bullets)
-- ✅ **Scannable** - Domain names as headers, principles as bullets
-- ✅ **Rationale included** - Explains "why" not just "what"
-- ✅ **Resource references** - Links to rulebooks, docs, standards
-- ✅ **Concrete** - Specific guidelines, not vague advice
-
-**Integration with auto-quality-review hook:**
-
-- Hook prompts: "Does it adhere to... domain requirements?"
-- Claude checks CLAUDE.md/AGENTS.md for Domain Requirements section
-- If present → Reviews against documented principles
-- If absent → Infers domain from context as usual
-
----
-
-## Writing for LLM Comprehension
-
-**Critical:** These files are instructions consumed by LLMs.
-
-**See:** `@.safeword/guides/llm-instruction-design.md` for 13 core principles for writing LLM-consumable documentation.
-
-### Quality Checklist
-
-Before committing:
-
-- [ ] All decision logic uses MECE principle (mutually exclusive, collectively exhaustive)
-- [ ] All project-specific terms are defined
-- [ ] No contradictions between sections
-- [ ] Rules have concrete examples
-- [ ] Edge cases explicitly covered
-- [ ] Vague terms replaced with actionable principles
-- [ ] No redundancy (each fact stated once)
-- [ ] File under 200 lines (or uses imports)
-
----
-
-## Best Practices from Anthropic
-
-**Conciseness:**
-
-- Use short, declarative bullet points (not narrative paragraphs)
-- Trim redundancy (don't explain obvious folder names like "components folder contains components")
-- Don't include commentary or nice-to-have information
-- Files are loaded with every request - keep lean
-
-**Effectiveness:**
-
-- **Treat as living document** - Constantly refine based on what works
-- Periodically review and refactor for clarity
-- At Anthropic, teams use prompt improver to tune instructions
-- Add emphasis ("IMPORTANT", "YOU MUST") for critical rules
-- Explicitly reference your context file in prompts ("following CLAUDE.md guidelines") for better adherence
-
-**Token Budget:**
-
-- Context files are often prepended to prompts - they consume context with each interaction
-- 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

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

@@ -1,200 +0,0 @@
-# Data Architecture Documentation Guide
-
-**Context:** How to document data architecture decisions, models, and flows for software projects. Applies LLM instruction design principles for clarity and reliability.
-
-**See:** `@.safeword/guides/llm-instruction-design.md` for comprehensive framework on writing LLM-consumable documentation.
-
----
-
-## When to Document Data Architecture
-
-**Decision Tree (Answer IN ORDER, stop at first match):**
-
-1. **Project initialization?** → Create `DATA_ARCHITECTURE.md` or `ARCHITECTURE.md` with data section
-2. **Adding new data store?** (database, cache, file system) → Update architecture doc
-3. **Changing data model?** (schema, entities, relationships) → Update architecture doc
-4. **Data flow integration?** (API, ETL, sync) → Update architecture doc
-5. **Single feature implementation?** → Use design doc (reference architecture doc)
-
-**Tie-breaking rule:** If multiple apply, stop at first match (earlier = more general).
-
-**Edge cases:**
-
-- Single feature but adds 3+ entities → Architecture doc (impacts data model)
-- Bug fix changes schema → Architecture doc (schema changes always documented)
-- Feature uses existing data model → Design doc only
-
----
-
-## Core Principles (Define First, Then Apply)
-
-### 1. Data Quality
-
-**What:** Ensure data is accurate, complete, consistent, and timely.
-
-**Why:** Poor data quality cascades to business logic bugs, corrupted state, and user-facing errors.
-
-**Document:**
-
-- Validation rules (types, constraints, ranges)
-- Data source of truth (which store is canonical)
-- Quality checkpoints (where validation happens)
-
-**Example format:**
-
-```markdown
-**[Entity] state** (source of truth: [storage type])
-
-- `field1`: constraint (e.g., 0-100 integer)
-- `field2[]`: max N entries, validation rule
-  **Validation checkpoint:** `validateFunction()` in `file.ts:line`
-```
-
-### 2. Data Governance
-
-**What:** Policies that govern data access, modification, and lifecycle.
-
-**Why:** Prevents unauthorized access, conflicting writes, and data loss.
-
-**Document:**
-
-- Who can read/write each data entity
-- When data is created/updated/deleted
-- Conflict resolution strategies
-
-**Example format:**
-
-```markdown
-**[Entity] state**:
-
-- Read: [roles with read access]
-- Write: [roles with write access] (via `updateFunction()`)
-- Delete: [strategy] (e.g., soft delete with `deletedAt`)
-- Conflict: [resolution strategy] (e.g., last-write-wins, CRDT merge)
-```
-
-### 3. Data Accessibility
-
-**What:** Ensure data is available when needed, performantly.
-
-**Why:** Users expect instant feedback; slow queries degrade UX.
-
-**Document:**
-
-- Access patterns (how data is queried)
-- Performance targets (max query time)
-- Caching strategies
-
-**Example format:**
-
-```markdown
-**[Entity] list** (accessed on [trigger]):
-
-- Target: <Nms load time
-- Strategy: [database index/optimization]
-- Cache: [caching approach] or "No cache needed"
-```
-
-### 4. Living Documentation
-
-**What:** Documentation stays current with code, not a one-time artifact.
-
-**Why:** Outdated docs are worse than no docs (mislead developers).
-
-**Document:**
-
-- Version/status (Production/Proposed)
-- Last updated date
-- Migration strategy when changing
-
-**Example format:**
-
-```markdown
-**Version:** X.Y
-**Status:** Production (vX) + Proposed (vY)
-**Last Updated:** YYYY-MM-DD
-
-## Current Schema (vX - Production)
-
-## Proposed Schema (vY - Feature Name)
-
-## Migration Strategy
-```
-
----
-
-## What to Document
-
-### 1. Data Models
-
-**Three levels (conceptual → logical → physical):**
-
-- **Conceptual**: High-level entities with descriptions (e.g., "User - person with account", "Order - purchase transaction")
-- **Logical**: Attributes, types, relationships, constraints (e.g., `userId: UUID`, `orders: Order[]` 1:N relationship)
-- **Physical**: Storage technology, tables/collections, indexes, WHY this tech (trade-offs) - see Core Principles → Data Quality (lines 41-47) for format
-
-### 2. Data Flows
-
-**Document:** Sources → Transformations → Destinations + Error Handling
-
-**Include:** Input validation, business logic transformations, persistence steps, UI updates, error handling for each step.
-
-**Example format:**
-
-```markdown
-**[Flow Name]** (trigger: [user action/event])
-
-1. **Input** → Validation (`validateFn()`) | Error: return 400
-2. **Transform** → Business logic | Error: rollback + notify
-3. **Persist** → Database write | Error: retry 3x, then fail
-4. **UI Update** → Optimistic update | Error: revert state
-```
-
-### 3. Data Policies
-
-**Document:** Access control (who reads/writes), validation rules, lifecycle (creation, updates, deletion, purging).
-
-### 4. Data Integration
-
-**Document:** External systems (APIs, files, services), sync strategies, conflict resolution, error handling.
-
----
-
-## Integration with TDD Workflow
-
-**See:** `@.safeword/guides/architecture-guide.md` for full TDD workflow integration.
-
-**Data-specific triggers for updating architecture doc:**
-
-- Adding new data entities
-- Changing schema (new fields, relationships)
-- Changing storage technology
-- Discovering performance bottlenecks
-
----
-
-## Common Mistakes
-
-❌ **No source of truth defined** → Conflicting data in multiple stores
-❌ **Missing validation rules** → Invalid data written to persistence
-❌ **No migration strategy** → Breaking changes brick user data
-❌ **Outdated documentation** → Schema and docs don't match (worse than no docs)
-❌ **Implementation details in architecture doc** → Save for design docs
-❌ **Ignoring performance targets** → Slow queries degrade UX
-
----
-
-## Best Practices Checklist
-
-Before finalizing data architecture doc:
-
-- [ ] Principles follow What/Why/Document/Example format (4 principles minimum)
-- [ ] All entities defined with descriptions (3+ entities for conceptual model)
-- [ ] Each entity has attributes, types, relationships (logical model complete)
-- [ ] Storage tech documented with WHY + trade-offs (physical model includes rationale)
-- [ ] Each data flow includes error handling (not just happy path)
-- [ ] Validation checkpoints specified with line numbers (where validation happens)
-- [ ] Performance targets use concrete numbers (<Nms, not "fast")
-- [ ] 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)