safeword 0.1.0 → 0.2.0

package/templates/guides/architecture-guide.md

@@ -0,0 +1,423 @@
+# Architecture & Design Documentation Guide
+
+**See:** `@.safeword/guides/llm-instruction-design.md` for LLM-consumable documentation principles.
+
+---
+
+## Document Type Decision Tree (Follow in Order)
+
+Answer **IN ORDER**. Stop at the first "Yes":
+
+1. **Technology or library choice?** → **Architecture Doc**
+2. **New data model or schema change?** → **Architecture Doc**
+3. **Project-wide pattern or convention?** → **Architecture Doc**
+4. **Implementing a specific feature?** → **Design Doc**
+
+**Tie-breaker:** If a feature requires a new tech/schema choice, document the tech/schema in Architecture Doc first, then reference it in Design Doc.
+
+| Term                 | Definition                                                                 |
+| -------------------- | -------------------------------------------------------------------------- |
+| Technology choice    | Selecting a library, framework, database, or tool                          |
+| Schema change        | Adding/modifying entities, tables, relationships, or data types            |
+| Project-wide pattern | Convention that applies to 2+ features or multiple developers              |
+| Major decision       | Affects 2+ components, costs >$100/month, or cannot be easily reversed     |
+| Living document      | Updated in place (not immutable); changes tracked via version/status       |
+| ADR                  | Architecture Decision Record—legacy pattern of separate files per decision |
+
+---
+
+## Quick Decision Matrix
+
+| Scenario                        | Doc Type                        | Rationale                          |
+| ------------------------------- | ------------------------------- | ---------------------------------- |
+| Choosing between technologies   | Architecture                    | Tech choice affects whole project  |
+| Data model design               | Architecture                    | Schema is project-wide             |
+| Implementing a new feature      | Design                          | Feature-scoped implementation      |
+| Recording a trade-off           | Architecture                    | Trade-offs inform future decisions |
+| Project-wide principles         | Architecture                    | Principles apply everywhere        |
+| Component breakdown for feature | Design                          | Implementation detail              |
+| Feature needs new schema        | Architecture first, then Design | Schema in Arch, feature in Design  |
+
+---
+
+## Architecture Document
+
+**Use when**: Project-wide decisions, data models, system design
+
+**Characteristics**:
+
+- One per project/package (in monorepos)
+- Living document (updated in place—not immutable ADRs)
+- Documents WHY behind all major decisions
+- Includes version, status, table of contents
+
+**Location**: Project root (`ARCHITECTURE.md`)
+
+**Edge cases:**
+
+- Schema change for one feature → Architecture Doc (schema is project-wide)
+- Library for one feature → Architecture Doc if precedent-setting; Design Doc if one-off
+- Performance optimization → Architecture Doc if changes patterns; Design Doc if feature-specific
+
+### Required Sections
+
+- **Header**: Version, Last Updated, Status (Production/Design/Proposed/Deprecated)
+- **Table of Contents**: Section links
+- **Overview**: Technology choices, data model philosophy, high-level architecture
+- **Data Model / Schema**: Tables, types, relationships
+- **Key Decisions**: What, Why, Trade-off, Alternatives Considered
+- **Best Practices**: Domain-specific patterns
+- **Migration Strategy**: How to evolve architecture
+
+---
+
+## Design Document
+
+**Use when**: Designing a specific feature implementation
+
+**Characteristics**:
+
+- Feature-focused (~121 lines)
+- Implementation details (components, data flow, user flow)
+- References architecture doc (don't duplicate)
+
+**Location**: `planning/design/` or `docs/design/`
+
+**Edge cases:**
+
+- Feature needs new data model → Schema in Architecture Doc first, then reference
+- Feature spans 3+ components → Still Design Doc (component count doesn't change doc type)
+- Feature establishes pattern others follow → Pattern in Architecture Doc, implementation in Design Doc
+
+**See:** `@.safeword/guides/design-doc-guide.md` for detailed guidance
+
+---
+
+## Best Practices
+
+### 1. One Architecture Doc Per Project/Package
+
+**✅ GOOD:**
+
+```
+project/
+├── ARCHITECTURE.md
+└── docs/design/
+    ├── feature-a.md
+    └── feature-b.md
+```
+
+**❌ BAD:** `docs/adr/001-use-typescript.md, 002-adopt-monorepo.md...` (50+ files = fragmented context)
+
+### 2. Living Document (Not Immutable)
+
+Update in place with version/status tracking:
+
+```markdown
+### Decision: State Management
+
+**Status**: Active (Updated 2025-01-20)
+**What**: Migrated from localStorage to IndexedDB
+**Why**: Hit 5MB limit, needed unlimited storage
+**Migration**: Completed 2025-01-20, users auto-migrated on load
+```
+
+**Edge cases:**
+
+- Decision reversed → Update original with "Superseded" status
+- Major shift → Bump version (v1 → v2), add migration section
+- Affects multiple subsystems → Update main Architecture Doc, not separate files
+
+### 3. Document WHY, Not Just WHAT
+
+**✅ GOOD:**
+
+```markdown
+### Principle: Separation of Concerns
+
+**What**: Static data → immutable storage; Mutable state → persistent storage
+**Why**: Static data saves NKB per instance; updates affect all instances instantly
+**Trade-off**: More complex loading (fetch static + query persistent)
+**Alternatives Considered**: All localStorage (rejected: 5MB limit); All IndexedDB (rejected: overkill for config)
+```
+
+**❌ BAD:** `Database: PostgreSQL, State: Zustand, UI: React` (no rationale)
+
+**Required fields:**
+
+| Field        | Required        | Description                                 |
+| ------------ | --------------- | ------------------------------------------- |
+| What         | Always          | The decision (1-2 sentences)                |
+| Why          | Always          | Rationale with specifics (numbers, metrics) |
+| Trade-off    | Always          | What we gave up or accepted                 |
+| Alternatives | Major decisions | Other options and why rejected              |
+| Migration    | If breaking     | How to evolve from previous state           |
+
+**Edge cases:**
+
+- Obvious choice → Still document; future devs may question
+- Inherited decision → Document as "Inherited: [reason]"
+- Temporary decision → Mark "Temporary" with planned review date
+
+### 4. Include Code References
+
+**✅ GOOD:**
+
+```markdown
+**Implementation**: See `src/stores/gameStore.ts:12-45`
+**Usage example**: See `src/components/GamePanel.tsx`
+```
+
+**❌ BAD:** "We use Zustand for state management" (no reference to actual code)
+
+- Key patterns → file + line range
+- Simple utilities → file path only (no line numbers)
+- Frequently changing code → file path only (line numbers go stale)
+
+### 5. Version and Track Status
+
+| Status     | Meaning                            |
+| ---------- | ---------------------------------- |
+| Design     | Initial draft, not yet implemented |
+| Production | Live in production                 |
+| Proposed   | Planned extension to production    |
+| Deprecated | Being phased out                   |
+
+**Version bumps:** Major schema changes → v1 → v2; New sections → v1.0 → v1.1; Clarifications → no bump
+
+---
+
+## TDD Workflow Integration
+
+**Workflow Order**:
+
+1. User Stories → What we're building
+2. Test Definitions → How we'll verify
+3. Design Doc → How we'll build it
+4. Check Architecture Doc → New tech/schema needed?
+5. Implement (RED → GREEN → REFACTOR)
+6. Update Architecture Doc if needed
+
+### When to Update Architecture Doc
+
+| Trigger                                     | Example                          |
+| ------------------------------------------- | -------------------------------- |
+| New data model concept                      | New "Subscription" entity        |
+| Technology choice                           | "Chose Resend for email"         |
+| New pattern/convention                      | "All forms use react-hook-form"  |
+| Architectural insight during implementation | "IndexedDB needed for offline"   |
+| Performance bottleneck requiring change     | "Migrated to Redis for sessions" |
+
+### When NOT to Update
+
+| Scenario                        | Where Instead            |
+| ------------------------------- | ------------------------ |
+| Single feature implementation   | Design Doc               |
+| Bug fix                         | Code comments if complex |
+| Refactor without pattern change | PR description           |
+
+**Edge case:** Bug fix reveals architectural flaw → Document flaw and fix in Architecture Doc.
+
+---
+
+## Common Mistakes
+
+### Architecture Doc Anti-Patterns
+
+| Anti-Pattern             | Fix                                 |
+| ------------------------ | ----------------------------------- |
+| ADR sprawl (001, 002...) | One comprehensive `ARCHITECTURE.md` |
+| No decision rationale    | Add What/Why/Trade-off              |
+| Missing version/status   | Add header with Version and Status  |
+| Implementation details   | Move to Design Doc or code          |
+
+**❌ BAD:** `GET /api/users → Returns users from PostgreSQL` (implementation detail)
+
+**✅ GOOD:** `API Design: RESTful routes with input validation at boundary` (principle)
+
+### Design Doc Anti-Patterns
+
+| Anti-Pattern                   | Fix                              |
+| ------------------------------ | -------------------------------- |
+| Repeating architecture content | Reference Architecture Doc       |
+| Skipping user flow             | Include step-by-step interaction |
+| Missing test mapping           | Link to test definitions         |
+| >200 lines                     | Split or extract to Architecture |
+
+---
+
+## Re-evaluation Path (When Unclear)
+
+Answer **IN ORDER**:
+
+1. **Affects 2+ features?** → Architecture Doc (stop)
+2. **Technology/data model choice?** → Architecture Doc (stop)
+3. **Future developers need this for whole project?** → Architecture Doc
+4. **Only for this feature?** → Design Doc
+
+**Tie-breaker:** When still unclear, default to Design Doc. Easier to promote later than to split.
+
+### Worked Example: Adding User Notifications
+
+**Scenario:** Add email notifications when users complete a purchase.
+
+1. **Affects 2+ features?** No, only checkout → Continue
+2. **Tech choice?** Yes, need to choose email service (SendGrid vs SES) → **Architecture Doc**
+
+**Result:**
+
+- `ARCHITECTURE.md` → "Email Service: SendGrid (Why: deliverability, cost, SDK quality)"
+- `planning/design/checkout-notifications.md` → Feature implementation referencing email decision
+
+---
+
+## File Organization
+
+```
+project/
+├── ARCHITECTURE.md              # Single comprehensive doc
+├── .safeword/planning/
+│   ├── user-stories/
+│   ├── test-definitions/
+│   └── design/                  # Feature-specific design docs
+└── src/
+```
+
+---
+
+## Layers & Boundaries
+
+**Purpose:** Define architectural layers and enforce dependency rules to prevent circular dependencies, god modules, and leaky abstractions.
+
+### Layer Definitions
+
+| Layer  | Directory     | Responsibility                 |
+| ------ | ------------- | ------------------------------ |
+| app    | `src/app/`    | UI, routing, composition       |
+| domain | `src/domain/` | Business rules, pure logic     |
+| infra  | `src/infra/`  | IO, APIs, DB, external SDKs    |
+| shared | `src/shared/` | Utilities usable by all layers |
+
+### Allowed Dependencies
+
+| From   | To     | Allowed | Rationale                                         |
+| ------ | ------ | ------- | ------------------------------------------------- |
+| app    | domain | ✅      | UI composes business logic                        |
+| app    | infra  | ✅      | UI triggers side effects                          |
+| app    | shared | ✅      | Utilities available everywhere                    |
+| domain | app    | ❌      | Domain must be framework-agnostic                 |
+| domain | infra  | ❌      | Domain contains pure logic only                   |
+| domain | shared | ✅      | Utilities available everywhere                    |
+| infra  | domain | ✅      | Adapters may use domain types                     |
+| infra  | app    | ❌      | Infra should not depend on UI                     |
+| infra  | shared | ✅      | Utilities available everywhere                    |
+| shared | \*     | ❌      | Shared has no dependencies (except external libs) |
+
+**Note:** This template allows direct app→infra. Alternative: force app→domain→infra for stricter separation (hexagonal/ports-adapters pattern).
+
+### Edge Cases
+
+| Scenario                             | Solution                                                                  |
+| ------------------------------------ | ------------------------------------------------------------------------- |
+| Project doesn't fit 3-layer model    | Document actual layers, same boundary rules apply                         |
+| Feature module needs another feature | Import via public API (`index.ts`) only                                   |
+| Shared utilities                     | Create `shared/` layer, all layers may import                             |
+| Brownfield adoption                  | Start with warnings-only mode, fix violations incrementally, then enforce |
+| Monorepo with multiple apps          | Each app has own layers; shared packages are explicit dependencies        |
+
+### Enforcement with eslint-plugin-boundaries
+
+**Setup:**
+
+1. Install: `npm install --save-dev eslint-plugin-boundaries`
+
+2. Add to `eslint.config.mjs`:
+
+```javascript
+import boundaries from 'eslint-plugin-boundaries';
+
+export default defineConfig([
+  // ... other configs ...
+  {
+    name: 'boundaries-config',
+    files: ['**/*.{js,ts,tsx}'],
+    plugins: { boundaries },
+    settings: {
+      'boundaries/include': ['src/**/*'],
+      'boundaries/elements': [
+        { type: 'app', pattern: 'src/app/**/*' },
+        { type: 'domain', pattern: 'src/domain/**/*' },
+        { type: 'infra', pattern: 'src/infra/**/*' },
+        { type: 'shared', pattern: 'src/shared/**/*' },
+      ],
+    },
+    rules: {
+      'boundaries/element-types': [
+        'error',
+        {
+          default: 'disallow',
+          rules: [
+            { from: 'app', allow: ['domain', 'infra', 'shared'] },
+            { from: 'domain', allow: ['shared'] },
+            { from: 'infra', allow: ['domain', 'shared'] },
+            { from: 'shared', allow: [] },
+          ],
+        },
+      ],
+      'boundaries/no-unknown-files': 'error',
+    },
+  },
+]);
+```
+
+3. Define layers in `ARCHITECTURE.md` (see template)
+
+4. Errors appear in IDE + CI automatically
+
+**Common Issues:**
+
+| Issue                            | Fix                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| "Unknown file" errors            | Ensure all source files are in defined layers                            |
+| False positives on tests         | Exclude test files: `'boundaries/include': ['src/**/*', '!**/*.test.*']` |
+| External library imports flagged | External deps are allowed by default; check `boundaries/ignore` setting  |
+
+---
+
+## Data Architecture
+
+**For data-heavy projects**, see `@.safeword/guides/data-architecture-guide.md` for:
+
+- Core principles (data quality, governance, accessibility)
+- What to document (conceptual/logical/physical models, flows, policies)
+- Integration with TDD workflow
+
+---
+
+## Quality Checklist
+
+**Architecture Doc:**
+
+- [ ] Sequential decision tree or clear structure
+- [ ] All decisions have What/Why/Trade-off
+- [ ] Version and Status in header
+- [ ] Code references for key patterns
+- [ ] No implementation details
+
+**Design Doc:**
+
+- [ ] References Architecture Doc (no duplication)
+- [ ] User flow step-by-step
+- [ ] Test mapping links
+- [ ] ~121 lines target
+
+---
+
+## Key Takeaway
+
+**One comprehensive architecture document per project** > many scattered ADR files:
+
+✅ Full context in one place
+✅ Living document (update in place)
+✅ LLMs consume entire architecture at once
+✅ Sequential decision trees prevent ambiguity

package/templates/guides/code-philosophy.md

@@ -0,0 +1,195 @@
+# Code Philosophy & Practices
+
+**Note:** This file provides instructions for LLM-based coding agents. For comprehensive framework on writing clear, actionable LLM-consumable instructions, see `@.safeword/guides/llm-instruction-design.md`.
+
+---
+
+## Communication Style
+
+- Be concise, clear, direct, technical, friendly, and educational
+- Show reasoning when it adds value, otherwise just deliver results
+- No emojis unless explicitly requested
+
+## Response Format
+
+At the end of EVERY response, include a JSON summary with this exact structure:
+
+```json
+{"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
+```
+
+Where (all fields describe **this response only**, not cumulative):
+
+- `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:
+
+- 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}`
+
+## Code Philosophy
+
+- **Elegant code and architecture** - Prioritize developer experience
+- **AVOID BLOAT** - Simple, focused solutions over complex ones
+- **Self-documenting code** - Minimal inline comments, clear naming and structure
+- **Explicit error handling** - NEVER suppress or swallow errors silently
+
+**Error handling examples:**
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| `catch (e) {}` (swallowed) | `catch (e) { throw new Error(\`Failed to read ${filePath}: ${e.message}\`) }`|
+|`catch (e) { console.log(e) }`|`catch (e) { logger.error('Payment failed', { userId, amount, error: e }) }` |
+| Generic "Something went wrong" | "Failed to save user profile: database connection timeout" |
+
+**Naming examples:**
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| `calcTot` | `calculateTotalWithTax` |
+| `d`, `tmp`, `data` | `userProfile`, `pendingOrders` |
+| `handleClick` | `submitPaymentForm` |
+| `process()` | `validateAndSaveUser()` |
+
+**When to comment:**
+
+- ✅ Non-obvious business logic ("Tax exempt for orders >$500 per policy X")
+- ✅ Workarounds ("Safari requires this delay due to bug #123")
+- ❌ Obvious code (`// increment counter` before `i++`)
+- ❌ Restating the function name
+
+**Bloat examples (avoid these):**
+| ❌ Bloat | ✅ Instead |
+|----------|-----------|
+| Utility class for one function | Single function |
+| Factory pattern for simple object | Direct construction |
+| Abstract base class with one implementation | Concrete class |
+| Config file for 2 options | Hardcode or simple params |
+| "Future-proofing" unused code paths | Delete, add when needed |
+
+**When to push back:** If a feature request would add >50 lines for a "nice to have", ask: "Is this essential now, or can we add it later?"
+
+## Documentation Verification (CRITICAL)
+
+- **Always look up current documentation** for libraries, tools, and frameworks
+- Do NOT assume API compatibility - verify the actual version being used
+- Check docs unless they're already loaded in the context window
+- **NEVER assume features exist** - Training data is at least 1 year old; when uncertain, verify first
+
+**How to verify:**
+
+1. Check `package.json` (or equivalent) for installed version
+2. Use Context7 MCP or official docs for current API
+3. If uncertain, ask user: "Which version of X are you using?"
+
+## Testing Philosophy
+
+**Test what matters** - Focus on user experience and delivered features, not implementation details.
+
+**Test-Driven Development (TDD):**
+
+- Write tests BEFORE implementing features (RED → GREEN → REFACTOR)
+- Tests define expected behavior, code makes them pass
+- Refactor with confidence knowing tests catch regressions
+
+**Always test what you build** - Run tests yourself before completion. Don't ask the user to verify.
+
+**NEVER modify or skip tests without approval:**
+
+- ❌ Changing test expectations to match broken code
+- ❌ Adding `.skip()` or `.todo()` to make failures go away
+- ❌ Deleting tests you can't get passing
+- ✅ If a test fails, fix the implementation—not the test
+- ✅ If a test seems wrong or requirements changed, explain why and ask before changing it
+
+**Workflow:** See `@.safeword/guides/testing-methodology.md` for comprehensive TDD workflow (RED → GREEN → REFACTOR phases)
+
+## Debugging & Troubleshooting
+
+**Debug Logging:**
+
+- When debugging, log **actual vs expected** values (not just pass/fail)
+- Use JSON.stringify() for complex objects to see structure
+- Remove debug logging after fixing (keep production code clean)
+
+```javascript
+// ❌ Bad: console.log('here')
+// ✅ Good: console.log('validateUser', { expected: 'admin', actual: user.role })
+```
+
+**Cross-Platform Development:**
+
+- Test on all target platforms early (macOS, Windows, Linux)
+- Never assume Unix-style paths (`/`) - handle both `/` and `\`
+- Be aware of runtime environment (browser vs Node.js, client vs server)
+
+```javascript
+// ❌ Bad: dir + '/' + filename
+// ✅ Good: path.join(dir, filename)
+```
+
+## Best Practices (Always Apply)
+
+Before implementing, research and apply:
+
+- **Tool-specific best practices** - Use libraries/frameworks as intended
+- **Domain best practices** - Follow conventions for the type of app (CLI, web editor, API, etc.)
+- **UX best practices** - Prioritize user experience in design decisions
+
+**How to research:** Use Context7 MCP or official docs. Check for established patterns before inventing your own.
+
+## Self-Review Checklist
+
+Before completing any work, verify:
+
+- ✓ Is it correct? Will it actually work?
+- ✓ Is it elegant? Does it avoid bloat?
+- ✓ Does it follow best practices?
+- ✓ Are you using the right docs/versions?
+- ✓ Have you tested the user-facing functionality?
+
+**Blockers:** If something can't be fixed now, note it explicitly: "Deferred: [issue] because [reason]"
+
+## Asking Questions
+
+- **Be proactive and self-sufficient** - Don't be lazy
+- Only ask questions when you genuinely can't find the answer through:
+  - Online documentation and research
+  - Reading the codebase
+  - Running tests or experiments
+- Ask non-obvious questions that require user domain knowledge or preferences
+- **When asking, show what you tried:** "I checked X and Y but couldn't determine Z. What's your preference?"
+
+## Tools & CLIs
+
+**Keep these updated** (check before starting new projects):
+
+- GitHub CLI (`gh`)
+- AWS CLI
+- Railway CLI
+- PostHog CLI
+
+**Update workflow:**
+
+1. Check current version: `gh --version`, `aws --version`, etc.
+2. Check for updates: `brew upgrade gh` or tool-specific update command
+3. Review changelog for breaking changes before major version updates
+4. If breaking changes affect your workflow, pin to current version until migration planned
+
+**When to pin versions:** If a tool is used in CI/automation, pin to specific version in scripts to avoid surprise breakages.
+
+## Git Workflow
+
+- Commit whenever work is completed
+- Commit often to checkpoint progress
+- Use descriptive commit messages
+- Make atomic commits (one logical change per commit)
+
+```
+# ❌ Bad: "misc fixes"
+# ✅ Good: "fix: login button not responding to clicks"
+```