safeword 0.2.4 → 0.2.5

package/README.md

@@ -1,347 +0,0 @@
-# SAFEWORD - Claude Code Framework
-
-**Problem**: AI agents write code without tests, skip design validation, and lack consistency across projects.
-
-**Solution**: Portable patterns and guides that enforce TDD workflow, quality standards, and best practices across all your projects.
-
-**Repository**: https://github.com/TheMostlyGreat/safeword (private)
-
----
-
-## Quick Start (30 seconds)
-
-**1. Install in your project:**
-
-```bash
-cd /path/to/your/project
-bash ./framework/scripts/setup-safeword.sh
-```
-
-**2. Verify installation:**
-
-```bash
-# Check for SAFEWORD files and hooks
-test -f .safeword/SAFEWORD.md && echo ".safeword/SAFEWORD.md ✓"
-test -f .claude/settings.json && echo ".claude/settings.json ✓"
-```
-
-**Result**: Your project now has:
-
-- `.safeword/SAFEWORD.md` - Global patterns and workflows
-- `.safeword/guides/` - TDD methodology, testing, code philosophy
-- `.claude/hooks/` - Auto-linting and quality review
-- `SAFEWORD.md` or `CLAUDE.md` - Project context with framework reference
-
-**Commit these to your repo** for team consistency.
-
----
-
-## How It Works
-
-**Project-local framework**: Scripts write to `.safeword/` and `.claude/` in your project (no global install needed)
-
-**Team consistency**: Teammates get the framework from your project repo (no global install needed)
-
-**Living documentation**: Update guides as you learn, extract learnings from debugging, archive completed work
-
----
-
-## What's Inside
-
-Key directories created in your project:
-
-- `.safeword/guides/` - Core methodology and best practices
-- `.safeword/templates/` - Fillable document structures
-- `.safeword/planning/` - Planning documentation (user-stories, test-definitions, design, issues)
-- `.claude/hooks/` - Automation scripts
-
----
-
-## Core Guides
-
-**Purpose**: Reusable methodology applicable to all projects
-
-| Guide                      | Purpose                                                         | When to Read            |
-| -------------------------- | --------------------------------------------------------------- | ----------------------- |
-| **code-philosophy.md**     | Core coding principles, TDD philosophy, self-review checklist   | Before writing code     |
-| **testing-methodology.md** | TDD workflow (RED/GREEN/REFACTOR), test pyramid, decision trees | Starting any feature    |
-| **tdd-best-practices.md**  | User story + test definition patterns and examples              | Creating tests/stories  |
-| **learning-extraction.md** | Extract learnings from debugging, recognition triggers          | After complex debugging |
-
----
-
-## Documentation Guides
-
-**Purpose**: Writing effective feature documentation
-
-| Guide                          | Purpose                                            | When to Read                   |
-| ------------------------------ | -------------------------------------------------- | ------------------------------ |
-| **user-story-guide.md**        | Writing effective user stories (INVEST criteria)   | Creating user stories          |
-| **test-definitions-guide.md**  | Writing test definitions (unit/integration/E2E)    | Planning test suites           |
-| **design-doc-guide.md**        | Design doc structure and best practices            | Designing complex features     |
-| **architecture-guide.md**      | Architecture decisions (tech choices, data models) | Making architectural decisions |
-| **data-architecture-guide.md** | Data model design (schemas, validation, flows)     | Database/schema design         |
-
----
-
-## Meta Guides
-
-**Purpose**: Working with LLMs and documentation structure
-
-| Guide                         | Purpose                                                                  | When to Read                |
-| ----------------------------- | ------------------------------------------------------------------------ | --------------------------- |
-| **llm-prompting.md**          | Prompt engineering, LLM cost optimization, caching                       | Building AI features        |
-| **llm-instruction-design.md** | 13 principles for LLM-consumable docs (MECE, examples)                   | Creating SAFEWORD.md/guides |
-| **context-files-guide.md**    | CLAUDE.md/CURSOR.md/AGENTS.md structure, anti-patterns, modular approach | Setting up projects         |
-| **zombie-process-cleanup.md** | Port-based cleanup, multi-project isolation                              | Managing dev servers        |
-
----
-
-## Templates
-
-**Purpose**: Fillable structures for feature documentation
-
-| Template                        | Purpose                                          | Used By                   |
-| ------------------------------- | ------------------------------------------------ | ------------------------- |
-| **user-stories-template.md**    | User story structure (As a X / Given-When-Then)  | user-story-guide.md       |
-| **test-definitions-feature.md** | Test definition structure (suites, tests, steps) | test-definitions-guide.md |
-| **design-doc-template.md**      | Design doc structure (architecture, components)  | design-doc-guide.md       |
-
----
-
-## Learnings
-
-**Purpose**: Extracted knowledge that compounds across sessions
-
-**Location**: `.safeword/learnings/[concept].md`
-
-**What goes here**:
-
-- Debugging discoveries (non-obvious gotchas, integration struggles)
-- Trial-and-error findings (tried 3+ approaches before right one)
-- Architecture insights (discovered during implementation)
-- Testing traps (tests pass but UX broken, or vice versa)
-
-**How to extract**: Follow `learning-extraction.md` recognition triggers and templates
-
-**Example learnings**:
-
-- React hooks async behavior
-- Electron IPC patterns
-- Browser storage quota quirks
-- E2E test zombie processes
-- ProseMirror fragment traversal
-
----
-
-## Planning
-
-**Purpose**: Feature planning and design documentation
-
-**Structure**:
-
-```
-planning/
-├── user-stories/       User story documents
-├── test-definitions/   Test definition documents
-├── design/            Design docs and research
-└── issues/            Issue capture and tracking
-```
-
-Each directory has an `archive/` subfolder for completed work.
-
-**What goes here**:
-
-- User stories for features
-- Test definitions for TDD workflow
-- Design documents for complex features
-- Research and analysis documents
-- Issue tracking and capture
-
----
-
-## Hooks & Skills
-
-**Hooks**: Automation scripts triggered by Claude Code events
-
-- `auto-quality-review.sh` - Automated quality control on responses
-
-**Skills**: Specialized agent capabilities
-
-- `quality-reviewer/` - Deep code quality review with web research
-
----
-
-## Advanced Setup
-
-### Custom Installation Options
-
-```bash
-cd /path/to/your/project
-# SAFEWORD structure + (optionally) Claude Code hooks
-bash ./framework/scripts/setup-safeword.sh
-# Claude Code hooks only (if SAFEWORD already configured)
-bash ./framework/scripts/setup-claude.sh --linting-mode biome
-bash ./framework/scripts/setup-claude.sh --skip-linting
-```
-
-**Auto-detection**: Automatically detects project type from `package.json`:
-
-- Biome → if `@biomejs/biome` installed
-- Next.js → if `next` in dependencies
-- 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
-
-### Reference Guides in Project SAFEWORD.md
-
-```markdown
-# Import guides from .safeword (SAFEWORD.md)
-
-@./.safeword/guides/testing-methodology.md
-@./.safeword/guides/code-philosophy.md
-@./.safeword/guides/user-story-guide.md
-@./.safeword/guides/test-definitions-guide.md
-@./.safeword/guides/design-doc-guide.md
-```
-
-Claude Code will auto-load these guides as context.
-
-### Check for Existing Learnings
-
-```bash
-# Project learnings (this repo)
-ls .safeword/learnings/
-```
-
-### Extract New Learning
-
-1. Follow recognition triggers in `learning-extraction.md`
-2. Create `.safeword/learnings/[concept].md`
-3. Use template: Problem → Gotcha → Examples → Testing Trap
-
-### Create Planning Documentation
-
-```bash
-# User stories
-mkdir -p .safeword/planning/user-stories && touch .safeword/planning/user-stories/feature-name.md
-# Test definitions
-mkdir -p .safeword/planning/test-definitions && touch .safeword/planning/test-definitions/feature-name.md
-# Design docs
-mkdir -p .safeword/planning/design && touch .safeword/planning/design/feature-name.md
-```
-
----
-
-## Syncing Across Machines
-
-Commit `.safeword/` and `.claude/` in your project repo for team consistency.
-
----
-
-## Integration with Project Context
-
-**Project SAFEWORD.md/CLAUDE.md**: Created by `setup-safeword.sh` or manually, references `.safeword/SAFEWORD.md`
-
-**How it works**:
-
-1. Project SAFEWORD.md imports core guides via `@./.safeword/guides/`
-2. Guides reference templates via `@./.safeword/templates/`
-3. Guides cross-reference each other via `@./.safeword/guides/`
-4. Learnings referenced via `ls .safeword/learnings/`
-
-**Result**: Modular, maintainable documentation with clear separation of concerns
-
----
-
-## Principles
-
-1. **Guides** - Reusable methodology (test pyramid, TDD workflow)
-2. **Templates** - Fillable structures (user stories, test definitions)
-3. **Learnings** - Extracted knowledge (gotchas, discoveries)
-4. **Planning** - Feature planning and design (user stories, test definitions, design docs)
-5. **Hooks/Skills** - Automation and specialized capabilities
-
-**Living Documentation**: Update as you learn, archive completed work, consolidate when needed
-
-**Cross-Agent Compatible**: Works with Claude Code, Cursor, and other AI coding agents
-
----
-
-## LLM Eval Testing
-
-**Purpose**: Validate that guides are effective for LLM consumption using promptfoo.
-
-### Running Evals
-
-```bash
-# Run all eval tests
-npm run eval
-
-# Run without cache (fresh API calls)
-npm run eval:no-cache
-
-# Open web UI to view results
-npm run eval:view
-```
-
-### What's Tested
-
-The eval suite tests that LLMs correctly follow guide instructions:
-
-| Category               | Tests   | What's Validated                                                                       |
-| ---------------------- | ------- | -------------------------------------------------------------------------------------- |
-| Architecture           | 21      | Doc type selection, layers, dependencies, ESLint, LLM review, pre-commit, CI, template |
-| Code Philosophy        | 14      | Bloat avoidance, error handling, TDD, self-review, git workflow                        |
-| Testing Methodology    | 13      | Test type selection, TDD phases, test integrity, cost controls                         |
-| Zombie Process         | 7       | Port-based cleanup, scripts, tmux isolation, best practices                            |
-| User Stories           | 13      | INVEST validation, size guidelines, templates, technical constraints                   |
-| LLM Instruction Design | 15      | MECE trees, tie-breaking, lookup tables, anti-patterns                                 |
-| TDD Best Practices     | 10      | Template selection, story formats, data builders                                       |
-| Design Doc             | 10      | Prerequisites, template, components, user flow, decisions                              |
-| Context Files          | 11      | File selection, triggers, imports, size, cross-references                              |
-| Data Architecture      | 7       | Decision tree, principles, flows, policies, checklist                                  |
-| Learning Extraction    | 11      | Triggers, templates, precedence, cross-references                                      |
-| LLM Prompting          | 10      | Caching, structured outputs, LLM-as-judge, costs                                       |
-| Test Definitions       | 12      | Suites, status, naming, mapping, LLM-friendly                                          |
-| **Total**              | **154** |                                                                                        |
-
-### Adding New Tests
-
-Edit `promptfoo.yaml` and add a test case:
-
-```yaml
-- description: 'test-id: Description'
-  vars:
-    input: 'User prompt to test'
-    context: |
-      Relevant excerpt from guide
-  assert:
-    - type: llm-rubric
-      value: |
-        EXCELLENT: Best response criteria
-        ACCEPTABLE: Minimum passing criteria
-        POOR: Failing criteria
-```
-
-### Requirements
-
-- `ANTHROPIC_API_KEY` environment variable set
-- Tests use Claude Sonnet 4 by default
-
-### Interpreting Results
-
-- **PASS**: LLM followed guide correctly
-- **FAIL**: Guide may need improvement (clearer instructions, examples, tie-breakers)
-
-Results saved to `eval-results.json` after each run.
-
----
-
-## Getting Help
-
-- **Claude Code docs**: https://docs.claude.com/en/docs/claude-code
-- **Issues**: https://github.com/anthropics/claude-code/issues
-- **This repo**: https://github.com/TheMostlyGreat/safeword (private)