diff --git a/openspec/changes/update-agent-instructions/design.md b/openspec/changes/update-agent-instructions/design.md
new file mode 100644
index 00000000..3293b10d
--- /dev/null
+++ b/openspec/changes/update-agent-instructions/design.md
@@ -0,0 +1,130 @@
+# Design: Agent Instructions Update
+
+## Approach
+
+### Information Architecture
+- **Front-load critical information** - Three-stage workflow comes first
+- **Clear hierarchy** - Core Workflow → Quick Start → Commands → Details → Edge Cases
+- **50% length reduction** - Target ~285 lines from current ~575 lines
+- **Imperative mood** - "Create proposal" vs "You should create a proposal"
+- **Bullet points over paragraphs** - Scannable, concise information
+
+### Three-Stage Workflow Documentation
+The workflow is now prominently featured as a core concept:
+1. **Creating** - Proposal generation phase
+2. **Implementing** - Code development phase with explicit steps:
+   - Read proposal.md for understanding
+   - Read design.md for technical context
+   - Read tasks.md for checklist
+   - Implement tasks sequentially
+   - Mark complete immediately after each task
+3. **Archiving** - Post-deployment finalization phase
+
+This structure helps agents understand the lifecycle and their role at each stage. The implementation phase is particularly detailed to prevent common mistakes like skipping documentation or batching task completion.
+
+### CLI Documentation Updates
+- **Comprehensive command coverage** - All 9 primary commands documented
+- **`openspec list` prominence** - Essential for discovering changes and specs
+- **Interactive mode documentation** - How agents can use prompts effectively
+- **Complete flag documentation** - All options like --json, --type, --skip-specs
+- **Deprecation cleanup** - Remove noun-first patterns (openspec change show)
+
+### Agent-Specific Enhancements
+Based on industry best practices for coding agents (Claude Code, Cursor, etc.):
+
+**Implementation Workflow**
+- Explicit steps prevent skipping critical context
+- Reading proposal/design first ensures understanding before coding
+- Sequential task completion maintains focus
+- Immediate marking prevents losing track of progress
+- Addresses common failure mode: jumping straight to code
+
+**Spec Discovery Workflow**
+- Always check existing specs before creating new ones
+- Use `openspec list --specs` to discover current capabilities
+- Prefer modifying existing specs over creating duplicates
+- Prevents fragmentation and maintains coherent architecture
+
+**Decision Clarity**
+- Clear decision trees eliminating ambiguous conditions
+- Concrete examples for each decision branch
+- Simplified bug vs feature determination
+
+**Tool Usage Guidance**
+- Tool selection matrix (when to use Grep vs Glob vs Read)
+- Error recovery patterns for common failures
+- Verification workflows to confirm correctness
+
+**Context Management**
+- "Before Any Task" checklist for gathering context
+- What to read before starting any work
+- How to maintain state across interactions
+
+**Spec File Structure Documentation**
+- Complete examples with ADDED/MODIFIED/REMOVED sections
+- Critical scenario formatting (#### Scenario: headers)
+- Delta file location clarity (changes/{name}/specs/)
+- Addresses most common creation errors from retrospective
+
+**Troubleshooting and Debugging**
+- Common error messages with solutions
+- Delta detection debugging steps
+- Validation best practices
+- JSON output for inspection
+- Prevents hours of frustration from silent failures
+
+**Best Practices**
+- Be concise (one-line answers when appropriate)
+- Be specific (file.ts:42 line references)
+- Start simple (<100 lines, single-file defaults)
+- Justify complexity (require metrics/data)
+
+## Design Rationale
+
+### Why These Changes Matter
+
+**Cognitive Load Reduction**
+- Agents process instructions better with clear structure
+- Front-loading critical info reduces scanning time
+- Decision trees eliminate analysis paralysis
+
+**Industry Alignment**
+- Follows patterns proven effective in Claude Code, Cursor, GitHub Copilot
+- Addresses common failure modes (ambiguous decisions, missing context)
+- Optimizes for LLM strengths (pattern matching) vs weaknesses (calculations)
+
+**Addressing Critical Pain Points (from Retrospective)**
+- **Scenario formatting** - Biggest struggle, now explicitly documented with examples
+- **Complete spec structure** - Full examples prevent structural errors
+- **Delta detection issues** - Debugging commands help diagnose problems
+- **Silent parsing failures** - Troubleshooting section explains common issues
+
+**Practical Impact**
+- Faster agent comprehension of tasks
+- Fewer misinterpretations of requirements
+- More consistent implementation quality
+- Better error recovery when things go wrong
+- Prevents the most common errors identified in user experience
+
+## Trade-offs
+
+### What We're Removing
+- Lengthy explanations of concepts that can be inferred
+- Redundant examples that don't add clarity
+- Verbose edge case documentation (moved to reference section)
+- Deprecated command documentation
+
+### What We're Keeping
+- All critical workflow steps
+- Complete CLI command reference
+- Complexity management principles
+- Directory structure visualization
+- Quick reference summary
+
+## Implementation Notes
+
+The CLAUDE.md template is intentionally more concise than README.md since:
+- It appears in every project root
+- Agents can reference the full README.md for details
+- It needs to load quickly in AI context windows
+- Focus is on immediate actionable guidance
\ No newline at end of file
diff --git a/openspec/changes/update-agent-instructions/proposal.md b/openspec/changes/update-agent-instructions/proposal.md
new file mode 100644
index 00000000..0ac9e58b
--- /dev/null
+++ b/openspec/changes/update-agent-instructions/proposal.md
@@ -0,0 +1,117 @@
+# Update OpenSpec Agent Instructions
+
+## Why
+
+The current OpenSpec agent instructions need updates to follow best practices for AI assistant instructions (brevity, clarity, removing ambiguity), ensure CLI commands are current with the actual implementation, and properly document the three-stage workflow pattern that agents should follow.
+
+## What Changes
+
+### Core Structure Improvements
+- **Front-load the 3-stage workflow** as the primary mental model:
+  1. Creating a change proposal (proposal.md, spec deltas, design.md, tasks.md)
+  2. Implementing a change proposal:
+     - First read proposal.md to understand the change
+     - Read design.md if it exists for technical context
+     - Read tasks.md for the implementation checklist
+     - Complete tasks one by one
+     - Mark each task complete immediately after finishing
+  3. Archiving the change proposal (using archive command after deployment)
+- **Reduce instruction length by 50%** while maintaining all critical information
+- **Restructure with clear hierarchy**: Core Workflow → Quick Start → Commands → Details → Edge Cases
+
+### Decision Clarity Enhancements
+- **Add clear decision trees** for common scenarios (bug vs feature, proposal needed vs not)
+- **Remove ambiguous conditions** that confuse agent decision-making
+- **Add "Before Any Task" checklist** for context gathering
+- **Add "Before Creating Specs" rule** - Always check existing specs first to avoid duplicates
+
+### CLI Documentation Updates
+- **Complete command documentation** with all current functionality:
+  - `openspec init [path]` - Initialize OpenSpec in a project
+  - `openspec list` - List all active changes (default)
+  - `openspec list --specs` - List all specifications
+  - `openspec show [item]` - Display change or spec with auto-detection
+  - `openspec show` - Interactive mode for selection
+  - `openspec diff [change]` - Show spec differences for a change
+  - `openspec validate [item]` - Validate changes or specs
+  - `openspec archive [change]` - Archive completed change after deployment
+  - `openspec update [path]` - Update OpenSpec instruction files
+- **Document all flags and options**:
+  - `--json` output format for programmatic use
+  - `--type change|spec` for disambiguation
+  - `--skip-specs` for tooling-only archives
+  - `--strict` for strict validation mode
+  - `--no-interactive` to disable prompts
+- **Remove deprecated command references** (noun-first patterns like `openspec change show`)
+- **Add concrete examples** for each command variation
+- **Document debugging commands**:
+  - `openspec show [change] --json --deltas-only` for inspecting deltas
+  - `openspec validate [change] --strict` for comprehensive validation
+
+### Spec File Structure Documentation
+- **Complete spec file examples** showing proper structure:
+  ```markdown
+  ## ADDED Requirements
+  ### Requirement: Clear requirement statement
+  The system SHALL provide the functionality...
+  
+  #### Scenario: Descriptive scenario name
+  - **WHEN** condition occurs
+  - **THEN** expected outcome
+  - **AND** additional outcomes
+  ```
+- **Scenario formatting requirements** (critical - most common error):
+  - MUST use `#### Scenario:` headers (4 hashtags)
+  - NOT bullet lists or bold text
+  - Each requirement MUST have at least one scenario
+- **Delta file location** - Clear explanation:
+  - Spec files go in `changes/{name}/specs/` directory
+  - Deltas are automatically extracted from these files
+  - Use operation prefixes: ADDED, MODIFIED, REMOVED, RENAMED
+
+### Troubleshooting Section
+- **Common errors and solutions**:
+  - "Change must have at least one delta" → Check specs/ directory exists with .md files
+  - "Requirement must have at least one scenario" → Check scenario uses `#### Scenario:` format
+  - Silent scenario parsing failures → Verify exact header format
+- **Delta detection debugging**:
+  - Use `openspec show [change] --json --deltas-only` to inspect parsed deltas
+  - Check that spec files have operation prefixes (## ADDED Requirements)
+  - Verify specs/ subdirectory structure
+- **Validation best practices**:
+  - Always use `--strict` flag for comprehensive checks
+  - Use JSON output for debugging: `--json | jq '.deltas'`
+
+### Agent-Specific Improvements
+- **Implementation workflow** - Clear step-by-step process:
+  1. Read proposal.md to understand what's being built
+  2. Read design.md (if exists) for technical decisions
+  3. Read tasks.md for the implementation checklist
+  4. Implement tasks one by one in order
+  5. Mark each task complete immediately: `- [x] Task completed`
+  6. Never skip ahead or batch task completion
+- **Spec discovery workflow** - Always check existing specs before creating new ones:
+  - Use `openspec list --specs` to see all current specs
+  - Check if capability already exists before creating
+  - Prefer modifying existing specs over creating duplicates
+- **Tool selection matrix** - When to use Grep vs Glob vs Read
+- **Error recovery patterns** - How to handle common failures
+- **Context management guide** - What to read before starting tasks
+- **Verification workflows** - How to confirm changes are correct
+
+### Best Practices Section
+- **Be concise** - One-line answers when appropriate
+- **Be specific** - Use exact file paths and line numbers (file.ts:42)
+- **Start simple** - Default to <100 lines, single-file implementations
+- **Justify complexity** - Require data/metrics for any optimization
+
+## Impact
+
+- Affected specs: None (this is a tooling/documentation change)
+- Affected code: 
+  - `src/core/templates/claude-template.ts` - Update CLAUDE.md template
+- Affected documentation:
+  - `openspec/README.md` - Main OpenSpec instructions
+  - CLAUDE.md files generated by `openspec init` command
+
+Note: This is a tooling/infrastructure change that doesn't require spec updates. When archiving, use `openspec archive update-agent-instructions --skip-specs`.
\ No newline at end of file
diff --git a/openspec/changes/update-agent-instructions/tasks.md b/openspec/changes/update-agent-instructions/tasks.md
new file mode 100644
index 00000000..a2eee26a
--- /dev/null
+++ b/openspec/changes/update-agent-instructions/tasks.md
@@ -0,0 +1,69 @@
+# Implementation Tasks
+
+## 1. Restructure OpenSpec README.md
+- [ ] 1.1 Front-load the three-stage workflow as primary content
+- [ ] 1.2 Restructure with hierarchy: Core Workflow → Quick Start → Commands → Details → Edge Cases
+- [ ] 1.3 Reduce total length by 50% (target: ~285 lines from current ~575)
+- [ ] 1.4 Add "Before Any Task" context-gathering checklist
+- [ ] 1.5 Add "Before Creating Specs" rule to check existing specs first
+
+## 2. Add Decision Clarity  
+- [ ] 2.1 Create clear decision trees for "Create Proposal?" scenarios
+- [ ] 2.2 Remove ambiguous conditions that confuse agents
+- [ ] 2.3 Add concrete examples for each decision branch
+- [ ] 2.4 Simplify bug vs feature determination logic
+- [ ] 2.5 Add explicit Stage 2 implementation steps (read → implement → mark complete)
+
+## 3. Update CLI Documentation
+- [ ] 3.1 Document `openspec list` and `openspec list --specs` commands
+- [ ] 3.2 Document `openspec show` with all flags and interactive mode
+- [ ] 3.3 Document `openspec diff [change]` for viewing spec differences
+- [ ] 3.4 Document `openspec archive` with --skip-specs option
+- [ ] 3.5 Document `openspec validate` with --strict and batch modes
+- [ ] 3.6 Document `openspec init` and `openspec update` commands
+- [ ] 3.7 Remove all deprecated noun-first command references
+- [ ] 3.8 Add concrete usage examples for each command variation
+- [ ] 3.9 Document all flags: --json, --type, --no-interactive, etc.
+- [ ] 3.10 Document debugging commands: `show --json --deltas-only`
+
+## 4. Add Spec File Documentation
+- [ ] 4.1 Add complete spec file structure example with ADDED/MODIFIED sections
+- [ ] 4.2 Document scenario formatting requirements (#### Scenario: headers)
+- [ ] 4.3 Explain delta file location (changes/{name}/specs/ directory)
+- [ ] 4.4 Show how deltas are automatically extracted
+- [ ] 4.5 Include warning about most common error (scenario formatting)
+
+## 5. Add Troubleshooting Section
+- [ ] 5.1 Document common errors and their solutions
+- [ ] 5.2 Add delta detection debugging steps
+- [ ] 5.3 Include validation best practices (--strict flag)
+- [ ] 5.4 Show how to use JSON output for debugging
+- [ ] 5.5 Add examples of silent parsing failures
+
+## 6. Add Agent-Specific Sections
+- [ ] 6.1 Add implementation workflow (read docs → implement tasks → mark complete)
+- [ ] 6.2 Add spec discovery workflow (check existing before creating)
+- [ ] 6.3 Create tool selection matrix (Grep vs Glob vs Read)
+- [ ] 6.4 Add error recovery patterns section
+- [ ] 6.5 Add context management guide
+- [ ] 6.6 Add verification workflows section
+- [ ] 6.7 Add best practices section (concise, specific, simple)
+
+## 7. Update CLAUDE.md Template
+- [ ] 7.1 Update `src/core/templates/claude-template.ts` with streamlined content
+- [ ] 7.2 Include three-stage workflow prominently
+- [ ] 7.3 Add comprehensive CLI quick reference (list, show, diff, archive, etc.)
+- [ ] 7.4 Add "Before Any Task" checklist
+- [ ] 7.5 Add "Before Creating Specs" rule
+- [ ] 7.6 Keep complexity management principles
+- [ ] 7.7 Add critical scenario formatting note (#### Scenario: headers)
+- [ ] 7.8 Include debugging command reference
+
+## 8. Testing and Validation
+- [ ] 8.1 Test all documented CLI commands for accuracy
+- [ ] 8.2 Run `openspec init` to verify CLAUDE.md generation
+- [ ] 8.3 Validate instruction clarity with example scenarios
+- [ ] 8.4 Ensure no critical information was lost in streamlining
+- [ ] 8.5 Verify decision trees eliminate ambiguity
+- [ ] 8.6 Test scenario formatting examples work correctly
+- [ ] 8.7 Verify troubleshooting steps resolve common errors
\ No newline at end of file