safeword 0.2.3 → 0.2.4

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

@@ -0,0 +1,405 @@
+# 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/.safeword/guides/data-architecture-guide.md

@@ -0,0 +1,183 @@
+# 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)