docs(readme): restructure for clarity - focus on AI alignment benefits and quick wins

Author: TabishB

README.md

@@ -21,6 +21,15 @@ OpenSpec turns specifications into living documentation that drives development.
 - **Clear Workflow** - Know what's proposed, what's built, and what's archived
 - **Team Alignment** - Everyone sees the same requirements and changes
 
+## What You Get
+
+- **Better AI Code Generation** - Create specs first, get the code you actually want
+- **Alignment with AI** - Your AI assistant understands exactly what to build through clear specifications
+- **Plan Before You Build** - Clarify features and requirements before implementation
+- **Team Clarity** - Everyone reviews specs, not code changes
+- **No API Keys** - Works with your existing AI tools (Claude Code, Cursor) by adding context rules
+- **Track Progress** - See what changes are proposed, in progress, or completed
+
 ## How It Works
 
 ```
@@ -40,12 +49,6 @@ OpenSpec turns specifications into living documentation that drives development.
 4. ARCHIVE preserves completed changes after deployment
 ```
 
-## Overview
-
-- Specs are the current truth stored in `openspec/specs/<capability>/spec.md`.
-- Changes are proposals stored in `openspec/changes/<name>/` with delta-formatted spec updates.
-- The CLI favors verb-first commands: `list`, `show`, `validate`, `diff`, `archive`.
-
 ## Installation
 
 ### Prerequisites
@@ -83,57 +86,30 @@ openspec init
 #   └── README.md    # AI instructions
 ```
 
-### 2. Create Your First Change Proposal
-
-After initialization, tell your AI assistant (Claude Code, Cursor, etc.):
+### 2. Create Your First Change
 
-```markdown
-// Step 1: Create the change proposal
-"I want to add user authentication with JWT tokens.
-Please create an OpenSpec change proposal for this feature"
-
-// Your AI will:
-// 1. Create openspec/changes/add-user-auth/
-// 2. Write proposal.md explaining why and what  
-// 3. Create design.md with technical decisions (optional)
-// 4. Generate spec deltas showing what's being added
-// 5. Create tasks.md with implementation checklist
-
-// Step 2: Review the proposal
-// Look at the generated files and ensure they match your vision
-// Make any adjustments needed to the proposal or specs
-
-// Step 3: When ready, implement the change
-"The proposal looks good. Let's implement the user authentication 
-change following the tasks in openspec/changes/add-user-auth/tasks.md"
-
-// AI will then work through each task systematically,
-// marking them complete as it implements the feature
-```
-
-### 3. AI-Driven Development Workflow
+Jump straight into creating a change proposal with your AI assistant:
 
 ```markdown
-// When starting a new feature:
-You: "I need to add two-factor authentication to our auth system"
-
-AI: "I'll create an OpenSpec change proposal for 2FA. Let me first
-     check the current auth specs..."
-     *reads openspec/specs/user-auth/spec.md*
-     *creates openspec/changes/add-2fa/ with:*
-       - proposal.md (why and impact)
-       - tasks.md (implementation checklist)
-       - design.md (technical decisions)
-       - specs/user-auth/spec.md (ADDED requirements)
-
-You: "Great, let's implement it"
-
-AI: "Following the tasks in openspec/changes/add-2fa/tasks.md:
-     Task 1.1: Create OTP model..."
-     *implements each task, marking complete*
+// Quick win - Add a simple new feature:
+You: "I want to add a user profile API endpoint.
+      Please create an OpenSpec change proposal for this."
+
+AI: "I'll create an OpenSpec change proposal for the user profile API..."
+    *Creates openspec/changes/add-user-profile-api/ with:*
+    - proposal.md (why this feature is needed)
+    - tasks.md (implementation checklist)
+    - design.md (API design decisions)
+    - specs/user-profile/spec.md (new requirements)
+
+You: "The proposal looks good. Let's implement it."
+
+AI: "Following the tasks in openspec/changes/add-user-profile-api/tasks.md:
+     Task 1.1: Create user profile model..."
+    *Implements each task systematically*
 ```
 
-### 4. Track and Complete Changes
+### 3. Track Your Work
 
 ```bash
 # View active changes (what's being worked on)
@@ -150,12 +126,18 @@ openspec archive add-2fa
 # This moves the change to archive/ and updates specs/
 ```
 
-### Key Points
+## Common Commands
 
-- **You don't write spec files manually** - Your AI assistant creates them
-- **Specs are living documentation** - They evolve with your code
-- **Changes are proposals** - They show what will be modified before implementation
-- **AI follows the specs** - Ensuring consistent, documented development
+```bash
+# Most used:
+openspec list              # See what changes you're working on
+openspec archive <change>  # Mark a change as complete after deployment
+
+# Also useful:
+openspec diff <change>     # See what specs will change
+openspec validate <change> # Check formatting before committing
+openspec show <change>     # View change details
+```
 
 ## Example: How AI Creates OpenSpec Files
 
@@ -226,77 +208,42 @@ The system MUST require a second factor during login.
 
 **Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
 
-### Understanding Delta Format
+## Understanding OpenSpec Files
 
-Deltas describe how specifications change using operation headers:
+### Delta Format
 
-- **`## ADDED Requirements`** - New capabilities being introduced
-- **`## MODIFIED Requirements`** - Changes to existing behavior (include the complete modified text)
-- **`## REMOVED Requirements`** - Features being deprecated (include reason and migration path)
-- **`## RENAMED Requirements`** - Simple name changes
+Deltas are "patches" that show how specs change:
 
-Each delta operation contains complete requirement blocks that will be merged into the main spec. Think of deltas as "patches" that transform your current specifications into the desired state.
+- **`## ADDED Requirements`** - New capabilities
+- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
+- **`## REMOVED Requirements`** - Deprecated features
 
-**Critical formatting rules:**
-- Use `### Requirement: <name>` for requirement headers
-- Every requirement MUST include at least one `#### Scenario:` block
-- Use SHALL/MUST in ADDED/MODIFIED requirement text
-- MODIFIED sections must contain the complete updated requirement, not just the changes
+**Format requirements:**
+- Use `### Requirement: <name>` for headers
+- Every requirement needs at least one `#### Scenario:` block
+- Use SHALL/MUST in requirement text
 
 
-## AI Integration
+## Why OpenSpec Works
 
-OpenSpec is built for AI-driven development. Your AI assistant creates and manages all specs and changes.
-
-### The AI Workflow
-
-1. **You describe what you want** - "Add user authentication" or "Improve performance"
-2. **AI creates the change proposal** - Generates proposal.md, tasks.md, and spec deltas
-3. **AI implements following specs** - Works through tasks.md systematically
-4. **You deploy and archive** - Once deployed, archive the change to update specs
-
-### How Your AI Assistant Works with OpenSpec
-
-```markdown
-// Starting a new feature:
-You: "Add password reset functionality"
-
-AI: "I'll create an OpenSpec change proposal. Let me check the current auth specs first..."
-    *Runs: openspec list --specs*
-    *Reads: openspec/specs/auth/spec.md*
-    *Creates: openspec/changes/add-password-reset/*
-    
-// AI automatically:
-- Checks existing specs to understand current state
-- Creates properly structured change proposals
-- Generates spec deltas showing what's being added/modified
-- Implements code following the tasks checklist
-- Validates changes with openspec validate
-```
-
-### Setting Up Your AI Assistant
-
-```bash
-# After running 'openspec init', your AI is configured
-# The init command:
-# 1. Asks which AI tool you use (Claude Code, Cursor, etc.)
-# 2. Creates the appropriate configuration files
-# 3. Sets up AI-specific instructions
-
-# To update AI configurations later:
-openspec update
-```
+OpenSpec creates **alignment** between you and your AI coding assistant:
 
+1. **You describe** what you want to build
+2. **AI creates specs** before writing any code
+3. **You review and adjust** the specifications
+4. **AI implements** exactly what was specified
+5. **Everyone understands** what's being built through clear specs
 
-## Comparison with Kiro.dev
+No API keys needed - OpenSpec works by adding context rules to your existing AI tools (Claude Code, Cursor, etc.).
 
-The key difference between OpenSpec and Kiro is **change management**:
 
-- **OpenSpec**: Groups all changes for a feature in one place (`openspec/changes/feature-name/`). You can see exactly what specs, tasks, and code need to be modified for a single feature.
+## How OpenSpec Compares
 
-- **Kiro**: Changes affect multiple specs and create tasks across different folders. When implementing a feature that touches multiple capabilities, it's harder to track what needs to be done to complete that specific feature.
+### vs. Kiro.dev
+OpenSpec groups all changes for a feature in one place (`openspec/changes/feature-name/`), making it easy to track what needs to be done. Kiro spreads changes across multiple spec folders, making feature tracking harder.
 
-This makes OpenSpec better for tracking feature completion and understanding the full scope of changes.
+### vs. No Specs
+Without specs, AI coding assistants generate code based on vague prompts, often missing requirements or adding unwanted features. OpenSpec ensures alignment before any code is written.
 
 ## Team Adoption