docs(openspec): add complexity management guidelines and update templates

feat(cli): add update command

openspec/README.md

@@ -10,6 +10,23 @@ OpenSpec is an AI-native system for change-driven development where:
 - **AI drives the process** - You generate proposals, humans review and approve
 - **Specs are living documentation** - Always kept in sync with deployed code
 
+## Start Simple
+
+**Default to minimal implementations:**
+- New features should be <100 lines of code initially
+- Use the simplest solution that works
+- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)
+- Choose boring technology over cutting-edge solutions
+
+**Complexity triggers** - Only add complexity when you have:
+- **Performance data** showing current solution is too slow
+- **Scale requirements** with specific numbers (>1000 users, >100MB data)
+- **Multiple use cases** requiring the same abstraction
+- **Regulatory compliance** mandating specific patterns
+- **Security threats** that simple solutions cannot address
+
+When triggered, document the specific justification in your change proposal.
+
 ## Directory Structure
 
 ```
@@ -72,6 +89,11 @@ Before any task:
 - Adding tests for existing behavior
 - Documentation fixes
 
+**Complexity assessment:**
+- If your solution requires >100 lines of new code, justify the complexity
+- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
+- Default to single-file implementations until proven insufficient
+
 ### 3. Creating a Change Proposal
 
 When a user requests a significant change:
@@ -383,10 +405,12 @@ Progress communication:
 - "Implementing approved changes..."
 
 ### For AI Assistants
+- **Bias toward simplicity** - Propose the minimal solution that works
 - Use your exploration tools liberally before proposing
 - Batch operations for efficiency
 - Communicate your progress
 - It's OK to revise proposals based on discoveries
+- **Question complexity** - If your solution feels complex, simplify first
 
 ## Edge Case Handling
 
@@ -442,6 +466,7 @@ Proposal REQUIRED if:
 - Specs must always reflect deployed reality
 - Changes are proposed, not imposed
 - Impact analysis prevents surprises
-- The simplicity is the power - just markdown files
+- Simplicity is the power - just markdown files, minimal solutions
+- Start simple, add complexity only when justified
 
 By following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.

openspec/changes/add-complexity-guidelines/tasks.md

@@ -1,9 +1,9 @@
 # Implementation Tasks
 
 ## 1. Update OpenSpec README
-- [ ] 1.1 Add "Start Simple" section after Core Principle
-- [ ] 1.2 Add complexity triggers to "When to Create Change Proposals" section
-- [ ] 1.3 Update AI workflow guidance to emphasize minimal implementations
+- [x] 1.1 Add "Start Simple" section after Core Principle
+- [x] 1.2 Add complexity triggers to "When to Create Change Proposals" section
+- [x] 1.3 Update AI workflow guidance to emphasize minimal implementations
 
 ## 2. Update CLAUDE.md
-- [ ] 2.1 Add complexity management rules to project instructions
+- [x] 2.1 Add complexity management rules to project instructions

openspec/changes/add-update-command/tasks.md

@@ -1,20 +0,0 @@
-# Implementation Tasks
-
-## 1. Update Command Implementation
-- [ ] 1.1 Create `src/core/update.ts` with `UpdateCommand` class
-- [ ] 1.2 Check if `openspec` directory exists (use `FileSystemUtils.directoryExists`)
-- [ ] 1.3 Write `readmeTemplate` to `openspec/README.md` using `FileSystemUtils.writeFile`
-- [ ] 1.4 Update `CLAUDE.md` using markers via `FileSystemUtils.updateFileWithMarkers` and `TemplateManager.getClaudeTemplate()`
-- [ ] 1.5 Display ASCII-safe success message: `Updated OpenSpec instructions`
-
-## 2. CLI Integration
-- [ ] 2.1 Register `update` command in `src/cli/index.ts`
-- [ ] 2.2 Add command description: `Update OpenSpec instruction files`
-- [ ] 2.3 Handle errors with `ora().fail(...)` and exit code 1 (missing `openspec` directory, file write errors)
-
-## 3. Testing
-- [ ] 3.1 Verify `openspec/README.md` is fully replaced with latest template
-- [ ] 3.2 Verify `CLAUDE.md` OpenSpec block updates without altering user content outside markers
-- [ ] 3.3 Verify idempotency (running twice yields identical files, no duplicate markers)
-- [ ] 3.4 Verify error when `openspec` directory is missing with friendly message
-- [ ] 3.5 Verify success message displays properly in ASCII-only terminals

openspec/changes/archive/2025-01-11-add-update-command/tasks.md

@@ -0,0 +1,20 @@
+# Implementation Tasks
+
+## 1. Update Command Implementation
+- [x] 1.1 Create `src/core/update.ts` with `UpdateCommand` class
+- [x] 1.2 Check if `openspec` directory exists (use `FileSystemUtils.directoryExists`)
+- [x] 1.3 Write `readmeTemplate` to `openspec/README.md` using `FileSystemUtils.writeFile`
+- [x] 1.4 Update `CLAUDE.md` using markers via `FileSystemUtils.updateFileWithMarkers` and `TemplateManager.getClaudeTemplate()`
+- [x] 1.5 Display ASCII-safe success message: `Updated OpenSpec instructions`
+
+## 2. CLI Integration
+- [x] 2.1 Register `update` command in `src/cli/index.ts`
+- [x] 2.2 Add command description: `Update OpenSpec instruction files`
+- [x] 2.3 Handle errors with `ora().fail(...)` and exit code 1 (missing `openspec` directory, file write errors)
+
+## 3. Testing
+- [x] 3.1 Verify `openspec/README.md` is fully replaced with latest template
+- [x] 3.2 Verify `CLAUDE.md` OpenSpec block updates without altering user content outside markers
+- [x] 3.3 Verify idempotency (running twice yields identical files, no duplicate markers)
+- [x] 3.4 Verify error when `openspec` directory is missing with friendly message
+- [x] 3.5 Verify success message displays properly in ASCII-only terminals

openspec/specs/cli-update/spec.md

@@ -0,0 +1,59 @@
+# Update Command Specification
+
+## Purpose
+
+As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions.
+
+## Core Requirements
+
+### Update Behavior
+
+The update command SHALL update OpenSpec instruction files to the latest templates.
+
+WHEN a user runs `openspec update` THEN the command SHALL:
+- Check if the `openspec` directory exists
+- Replace `openspec/README.md` with the latest template (complete replacement)
+- Update the OpenSpec-managed block in `CLAUDE.md` using markers
+  - Preserve user content outside markers
+  - Create `CLAUDE.md` if missing
+- Display ASCII-safe success message: "Updated OpenSpec instructions"
+
+### Prerequisites
+
+The command SHALL require:
+- An existing `openspec` directory (created by `openspec init`)
+
+IF the `openspec` directory does not exist THEN:
+- Display error: "No OpenSpec directory found. Run 'openspec init' first."
+- Exit with code 1
+
+### File Handling
+
+The update command SHALL:
+- Completely replace `openspec/README.md` with the latest template
+- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
+- Use the default directory name `openspec`
+- Be idempotent (repeated runs have no additional effect)
+
+## Edge Cases
+
+### File Permissions
+IF file write fails THEN let the error bubble up naturally with file path.
+
+### Missing CLAUDE.md
+IF CLAUDE.md doesn't exist THEN create it with the template content.
+
+### Custom Directory Name
+Not supported in this change. The default directory name `openspec` SHALL be used.
+
+## Success Criteria
+
+Users SHALL be able to:
+- Update OpenSpec instructions with a single command
+- Get the latest AI agent instructions
+- See clear confirmation of the update
+
+The update process SHALL be:
+- Simple and fast (no version checking)
+- Predictable (same result every time)
+- Self-contained (no network required)

src/cli/index.ts

@@ -3,6 +3,7 @@ import ora from 'ora';
 import path from 'path';
 import { promises as fs } from 'fs';
 import { InitCommand } from '../core/init.js';
+import { UpdateCommand } from '../core/update.js';
 
 const program = new Command();
 
@@ -44,4 +45,19 @@ program
     }
   });
 
+program
+  .command('update [path]')
+  .description('Update OpenSpec instruction files')
+  .action(async (targetPath = '.') => {
+    try {
+      const resolvedPath = path.resolve(targetPath);
+      const updateCommand = new UpdateCommand();
+      await updateCommand.execute(resolvedPath);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

src/core/templates/claude-template.ts

@@ -4,4 +4,23 @@ This document provides instructions for AI coding assistants on how to use OpenS
 
 This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
 
-See @openspec/README.md for detailed conventions and guidelines.`;
+See @openspec/README.md for detailed conventions and guidelines.
+
+## Complexity Management
+
+**Default to minimal solutions:**
+- Propose <100 lines of new code for features
+- Prefer single-file implementations until proven insufficient
+- Avoid frameworks, abstractions, and optimizations without clear justification
+- Choose boring, well-understood patterns over novel approaches
+
+**Question requests for complexity:**
+- Caching? → Ask for performance data and targets
+- New framework? → Suggest plain code first
+- Extra layers? → Start with the thinnest viable design
+
+**Justify complexity with data:**
+- Performance metrics showing current solution is too slow
+- Concrete scale requirements (e.g., >1000 users, >100MB data)
+- Multiple proven use cases requiring an abstraction
+`;

src/core/templates/readme-template.ts

@@ -10,6 +10,23 @@ OpenSpec is an AI-native system for change-driven development where:
 - **AI drives the process** - You generate proposals, humans review and approve
 - **Specs are living documentation** - Always kept in sync with deployed code
 
+## Start Simple
+
+**Default to minimal implementations:**
+- New features should be <100 lines of code initially
+- Use the simplest solution that works
+- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)
+- Choose boring technology over cutting-edge solutions
+
+**Complexity triggers** - Only add complexity when you have:
+- **Performance data** showing current solution is too slow
+- **Scale requirements** with specific numbers (>1000 users, >100MB data)
+- **Multiple use cases** requiring the same abstraction
+- **Regulatory compliance** mandating specific patterns
+- **Security threats** that simple solutions cannot address
+
+When triggered, document the specific justification in your change proposal.
+
 ## Directory Structure
 
 \`\`\`
@@ -72,6 +89,11 @@ Before any task:
 - Adding tests for existing behavior
 - Documentation fixes
 
+**Complexity assessment:**
+- If your solution requires >100 lines of new code, justify the complexity
+- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
+- Default to single-file implementations until proven insufficient
+
 ### 3. Creating a Change Proposal
 
 When a user requests a significant change:
@@ -383,10 +405,12 @@ Progress communication:
 - "Implementing approved changes..."
 
 ### For AI Assistants
+- **Bias toward simplicity** - Propose the minimal solution that works
 - Use your exploration tools liberally before proposing
 - Batch operations for efficiency
 - Communicate your progress
 - It's OK to revise proposals based on discoveries
+- **Question complexity** - If your solution feels complex, simplify first
 
 ## Edge Case Handling
 
@@ -442,7 +466,8 @@ Proposal REQUIRED if:
 - Specs must always reflect deployed reality
 - Changes are proposed, not imposed
 - Impact analysis prevents surprises
-- The simplicity is the power - just markdown files
+- Simplicity is the power - just markdown files, minimal solutions
+- Start simple, add complexity only when justified
 
 By following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.
 `;

src/core/update.ts

@@ -0,0 +1,35 @@
+import path from 'path';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { TemplateManager } from './templates/index.js';
+import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
+import { readmeTemplate } from './templates/readme-template.js';
+
+export class UpdateCommand {
+  async execute(projectPath: string): Promise<void> {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const openspecDirName = OPENSPEC_DIR_NAME;
+    const openspecPath = path.join(resolvedProjectPath, openspecDirName);
+
+    // 1. Check openspec directory exists
+    if (!await FileSystemUtils.directoryExists(openspecPath)) {
+      throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
+    }
+
+    // 2. Update README.md (full replacement)
+    const readmePath = path.join(openspecPath, 'README.md');
+    await FileSystemUtils.writeFile(readmePath, readmeTemplate);
+
+    // 3. Update CLAUDE.md (marker-based)
+    const claudePath = path.join(resolvedProjectPath, 'CLAUDE.md');
+    const claudeContent = TemplateManager.getClaudeTemplate();
+    await FileSystemUtils.updateFileWithMarkers(
+      claudePath,
+      claudeContent,
+      OPENSPEC_MARKERS.start,
+      OPENSPEC_MARKERS.end
+    );
+
+    // 4. Success message (ASCII-safe)
+    console.log('Updated OpenSpec instructions');
+  }
+}