project-iris 0.2.1 → 0.2.3

package/lib/installer.js

@@ -230,6 +230,47 @@ async function installVSCodeExtension(selectedToolKeys) {
   return installed;
 }
 
+/**
+ * Install CLAUDE.md to .claude/ folder
+ * This provides Claude with project-agnostic quality guidelines
+ * @returns {boolean} Whether file was installed
+ */
+async function installClaudeMd() {
+  const sourcePath = path.join(__dirname, '..', 'templates', 'CLAUDE.md');
+  const targetDir = '.claude';
+  const targetPath = path.join(targetDir, 'CLAUDE.md');
+
+  // Check if source exists
+  if (!await fs.pathExists(sourcePath)) {
+    console.log(theme.dim('  CLAUDE.md template not found, skipping...'));
+    return false;
+  }
+
+  // Ensure .claude directory exists
+  await fs.ensureDir(targetDir);
+
+  // Check if CLAUDE.md already exists
+  if (await fs.pathExists(targetPath)) {
+    // Read existing content to check if it's ours
+    const existing = await fs.readFile(targetPath, 'utf8');
+    if (existing.includes('installed by iris') || existing.includes('project-iris')) {
+      // Our file, safe to overwrite
+      await fs.copy(sourcePath, targetPath, { overwrite: true });
+      CLIUtils.displayStatus('', 'Updated CLAUDE.md', 'success');
+      return true;
+    } else {
+      // User's own CLAUDE.md, don't overwrite
+      console.log(theme.dim('  Existing CLAUDE.md found, skipping (won\'t overwrite user file)'));
+      return false;
+    }
+  }
+
+  // Install fresh
+  await fs.copy(sourcePath, targetPath);
+  CLIUtils.displayStatus('', 'Installed CLAUDE.md with quality guidelines', 'success');
+  return true;
+}
+
 async function install() {
   // Initialize analytics (respects opt-out env vars)
   analytics.init();
@@ -316,6 +357,9 @@ async function install() {
   try {
     const filesCreated = await installFlow(selectedFlow, selectedToolKeys);
 
+    // Install CLAUDE.md with quality guidelines
+    await installClaudeMd();
+
     // Install VS Code extension if applicable
     await installVSCodeExtension(selectedToolKeys);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-iris",
-  "version": "0.2.1",
+  "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": {
@@ -38,6 +38,7 @@
     "flows/",
     "lib/",
     "scripts/",
+    "templates/",
     "README.md"
   ],
   "dependencies": {

package/templates/CLAUDE.md

@@ -0,0 +1,159 @@
+# Claude Instructions
+
+## Prime Directives
+
+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
+
+**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
+
+### 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
+
+### 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
+
+### Error Handling
+- Validate at boundaries only (user input, API responses, file I/O)
+- Fail fast - throw early
+- Never swallow errors silently
+
+---
+
+## 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"
+
+### 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
+
+---
+
+## Debugging
+
+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
+
+---
+
+## 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
+
+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 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
+
+- **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
+
+---
+
+<!-- installed by iris (project-iris) - safe to update with: npx project-iris install -->