project-iris 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {

package/templates/CLAUDE.md

@@ -1,87 +1,158 @@
 # Claude Instructions
 
-## Core Principles
+## Prime Directives
 
-1. **Read before writing** - Understand existing code before modifying
-2. **Minimal changes** - Solve the problem, nothing more
-3. **Follow existing patterns** - Match the codebase style exactly
-4. **Ask when unclear** - Don't guess at requirements
+1. **Clarify before coding** - Never assume. Ask if requirements are unclear.
+2. **Read before writing** - Never modify code you haven't read. Find existing patterns first.
+3. **Do exactly what's asked** - No more, no less. No "improvements" unless requested.
+4. **Keep it simple** - The simplest solution that works is the best solution.
+5. **Verify your work** - Confirm changes compile and tests pass before marking done.
 
 ---
 
 ## Before Writing Code
 
-- Read the files you'll modify - understand the patterns used
-- Search for existing utilities before creating new ones
-- Check if similar problems are solved elsewhere in the codebase
-- Understand the "why" behind existing code, not just the "what"
+**Required steps:**
+1. Read the files you'll modify
+2. Search for similar code/patterns in the codebase
+3. Check for related tests
+4. Use existing utilities - don't reinvent
+
+```
+Good: "Let me read the existing service to understand the patterns..."
+Bad:  "I'll create a new Service class..." (without reading existing code)
+```
 
 ---
 
 ## Code Quality
 
-### Keep It Simple
+### Structure & Naming
+- One responsibility per file/function
+- Group by feature (`user/`) not type (`controllers/`)
+- Functions: verb + noun (`createUser`, `validateEmail`)
+- Booleans: `is/has/can/should` prefix
+- Match existing codebase conventions exactly
 
-- Solve the current problem, not hypothetical future ones
-- No abstractions for single-use cases
-- Three similar lines > premature helper function
-- Delete unused code completely (no `_unused` prefixes)
+### Simplicity
+- No abstraction until 3+ use cases exist
+- No "just in case" code
+- 10 clear lines > 3 clever lines
+- Max 20-30 lines per function, 3-4 parameters
 
-### Only Add What's Needed
+### Error Handling
+- Validate at boundaries only (user input, API responses, file I/O)
+- Fail fast - throw early
+- Never swallow errors silently
 
-- No feature flags for simple changes
-- No backwards-compatibility shims when you can just change code
-- No defensive programming against impossible scenarios
-- No gold-plating or "while I'm here" improvements
+---
 
-### Error Handling
+## Verification
+
+After every change:
+1. **Compile/parse** - No syntax errors
+2. **Run tests** - Existing tests still pass
+3. **Manual check** - If no tests, verify it works
+
+If something breaks: Stop, read the error, fix or revert. Never leave broken code.
+
+---
+
+## What Claude Gets Wrong
+
+### Over-Engineering
+- Abstractions/interfaces for single implementations
+- Factory patterns, builders without need
+- Utility classes for one-off operations
+- Config for things that won't change
+
+### Unnecessary Changes
+- "Cleaning up" unrelated code
+- Adding types/docs to unchanged code
+- Refactoring "while you're there"
 
-- Validate at system boundaries only (user input, APIs, file I/O)
-- Trust internal code - don't defensively check everything
-- No empty catch blocks
-- Let errors propagate when callers should handle them
+### Context Failures
+- Modifying files without reading them
+- Ignoring existing patterns
+- Creating utilities when similar ones exist
+- Using different conventions than the codebase
+
+### Verbose Patterns
+- Try-catch that just logs and rethrows
+- Null checks on non-nullable values
+- Comments explaining obvious code
 
 ---
 
-## What NOT To Do
+## Debugging
 
-- Don't add comments explaining obvious code
-- Don't add types/docstrings to code you didn't change
-- Don't refactor surrounding code when fixing a bug
-- Don't create utils/helpers for one-time operations
-- Don't add tests for trivial code (getters, pass-through)
-- Don't "improve" working code that isn't part of the task
-- Don't guess at missing requirements - ask first
+1. **Reproduce** - Make the bug happen consistently
+2. **Isolate** - Find the smallest failing case
+3. **Understand** - Find root cause, not symptom
+4. **Fix** - Minimal change only
+5. **Verify** - Test the fix, remove debug code
 
 ---
 
-## Security Essentials
+## Multi-Step Tasks
+
+1. List steps before starting
+2. Complete one step fully before next
+3. Verify each step works
+4. If blocked, ask - don't guess
 
-- Never hardcode secrets, keys, or credentials
-- Validate and sanitize all user input
-- Use parameterized queries (no string concatenation for SQL)
-- Escape output in templates to prevent XSS
-- Check file paths to prevent directory traversal
+Pattern: Small change → Verify → Next change → Verify
+
+---
+
+## Git & Dependencies
+
+**Commits**: Atomic, meaningful messages, always working state
+**Format**: `type: description` (feat, fix, refactor, docs, test, chore)
+**Before commit**: Review diff, build passes, tests pass, no debug code
+
+**Dependencies**: Check if existing deps solve it first. Ask before adding new ones.
+
+---
+
+## Security (Non-Negotiable)
+
+- Never hardcode secrets - use environment variables
+- Validate/sanitize ALL external input
+- SQL: Parameterized queries only
+- Escape output for context (HTML, SQL, shell)
+- Check permissions on protected operations
 
 ---
 
 ## Testing
 
 - Test behavior, not implementation
-- One assertion per test when possible
-- Name tests by what they verify: `test_returns_empty_list_when_no_items`
-- Don't mock what you don't own
-- Skip tests for trivial code
+- One concept per test
+- Name clearly: `rejects_expired_tokens`
+- No logic in tests (no if/for)
+- Test edge cases: empty, null, boundaries
+- Write tests for bug fixes
 
 ---
 
 ## Communication
 
-- Be direct and concise
-- State what you're doing before doing it
-- If blocked, explain why and ask for guidance
-- Confirm destructive operations before executing
-- Summarize changes after completing a task
+- **Before**: "I'll [action] by [approach]."
+- **After**: "Done. Changed X, Y. [caveats]."
+- **Blocked**: "I need [info] because [reason]."
+- **Trade-offs**: "A: [pro/con]. B: [pro/con]. Recommend A because..."
+
+Never: Apologize unnecessarily, explain basics unless asked, pad responses
+
+---
+
+## Documentation
+
+- Code should be self-documenting
+- Comment only: why (not what), complex algorithms, non-obvious side effects
+- No TODO comments - fix now or create issue
+- No commented-out code - delete it
 
 ---