@fission-ai/openspec 0.2.0 → 0.3.0

package/README.md

@@ -27,129 +27,181 @@
 
 # OpenSpec
 
-**Supported AI Tools:** ✅ Claude Code | 🔜 Cursor (coming soon) | ✅ AGENTS.md instructions
-
-Create **alignment** between humans and AI coding assistants through spec-driven development. **No API keys required.**
-
-OpenSpec ensures you and your AI assistant agree on what to build before any code is written. By discussing and refining specifications first, you bring determinism to AI code generation, getting exactly what you want, not what the AI thinks you might want.
+OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
 
 ## Why OpenSpec?
 
-**The Problem:** AI coding assistants are powerful but unpredictable. Without clear specifications, they generate code based on assumptions, often missing requirements or adding unwanted features. Teams waste time in review cycles because humans and AI aren't aligned on what to build.
+AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
 
-**The Solution:** OpenSpec creates alignment BEFORE code is written:
-- **Human-AI Alignment** - You and your AI agree on specifications before implementation
-- **Deterministic, Predictable Output** - Clear specs lead to reliable, repeatable code generation
-- **Team Alignment via Spec Reviews** - Everyone reviews intentions, not code surprises
-- **Clear Feature Scope** - Know exactly what you're building—and what you're not
-- **Progress Tracking** - See what's proposed, in progress, or completed at a glance
-- **Living Documentation** - Specs evolve with your code as a natural byproduct
-- **Universal Tool Support** - Works with any AI assistant (Claude Code, Cursor, and more)
-- **No API Keys Required** - Integrates through context rules, not external services
+Key outcomes:
+- Human and AI stakeholders agree on specs before work begins.
+- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
+- Shared visibility into what's proposed, active, or archived.
+- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
 
 ## How It Works
 
 ```
-┌─────────────┐       ┌─────────────┐       ┌──────────────┐
-│    SPECS    │       │   CHANGES   │       │   ARCHIVE    │
-│   (Truth)   │◀──────│ (Proposals) │──────▶│ (Completed)  │
-└─────────────┘       └─────────────┘       └──────────────┘
-      ▲                      │                      │
-      │                      ▼                      │
-      │               ┌─────────────┐               │
-      └───────────────│    CODE     │◀──────────────┘
-                      └─────────────┘
-
-1. SPECS define current capabilities (what IS built)
-2. CHANGES propose modifications using deltas (what SHOULD change)  
-3. CODE implements the changes following tasks
-4. ARCHIVE preserves completed changes after deployment
+┌────────────────────┐
+│ Draft Change       │
+│ Proposal           │
+└────────┬───────────┘
+         │ share intent with your AI
+         ▼
+┌────────────────────┐
+│ Review & Align     │
+│ (edit specs/tasks) │◀──── feedback loop ──────┐
+└────────┬───────────┘                          │
+         │ approved plan                        │
+         ▼                                      │
+┌────────────────────┐                          │
+│ Implement Tasks    │──────────────────────────┘
+│ (AI writes code)   │
+└────────┬───────────┘
+         │ ship the change
+         ▼
+┌────────────────────┐
+│ Archive & Update   │
+│ Specs (source)     │
+└────────────────────┘
+
+1. Draft a change proposal that captures the spec updates you want.
+2. Review the proposal with your AI assistant until everyone agrees.
+3. Implement tasks that reference the agreed specs.
+4. Archive the change to merge the approved updates back into the source-of-truth specs.
 ```
 
-## Installation
+## Getting Started
+
+### Supported AI Tools
+
+#### Native Slash Commands
+These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
 
-### Prerequisites
+| Tool | Commands |
+|------|----------|
+| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
+| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 
-- Node.js >= 20.19.0
+#### AGENTS.md Compatible
+These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
 
-### Install OpenSpec
+| Tools |
+|-------|
+| Codex • Amp • Jules • OpenCode • Gemini CLI • GitHub Copilot • Others |
 
-Install globally:
+### Install & Initialize
+
+#### Prerequisites
+- **Node.js >= 20.19.0** - Check your version with `node --version`
+
+#### Step 1: Install the CLI globally
 
 ```bash
-npm install -g @fission-ai/openspec
+npm install -g @fission-ai/openspec@latest
 ```
 
-## Getting Started
+Verify installation:
+```bash
+openspec --version
+```
 
-### 1. Initialize OpenSpec in Your Project
+#### Step 2: Initialize OpenSpec in your project
 
+Navigate to your project directory:
 ```bash
-# Navigate to your project
 cd my-project
+```
 
-# Initialize OpenSpec
+Run the initialization:
+```bash
 openspec init
+```
 
-# Select your AI tool (more coming soon!):
-# "Which AI tool do you use?"
-#   > Claude Code
-#     Cursor (coming soon)
+**What happens during initialization:**
+- You'll be prompted to select your AI tool (Claude Code, Cursor, etc.)
+- OpenSpec automatically configures slash commands or `AGENTS.md` based on your selection
+- A new `openspec/` directory structure is created in your project
 
-# This creates:
-# openspec/
-#   ├── specs/       # Current specifications (truth)
-#   ├── changes/     # Proposed changes
-#   └── AGENTS.md    # AI instructions for your tool
-```
+**After setup:**
+- Primary AI tools can trigger `/openspec` workflows without additional configuration
+- Run `openspec list` to verify the setup and view any active changes
 
-### 2. Create Your First Change
+### Create Your First Change
 
-Jump straight into creating a change proposal with your AI assistant (works with Claude Code, Cursor, or any AI tool):
+Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
 
-```markdown
-// 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*
+#### 1. Draft the Proposal
+Start by asking your AI to create a change proposal:
+
+```text
+You: Create an OpenSpec change proposal for adding profile search filters by role and team
+     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
+
+AI:  I'll create an OpenSpec change proposal for profile filters.
+     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
 ```
 
-### 3. Track Your Work
+#### 2. Verify & Review
+Check that the change was created correctly and review the proposal:
 
 ```bash
-# View active changes (what's being worked on)
-openspec list
+$ openspec list                             # Confirm the change folder exists
+$ openspec validate add-profile-filters     # Validate spec formatting
+$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta
+```
+
+#### 3. Refine the Specs
+Iterate on the specifications until they match your needs:
 
-# Validate your changes are properly formatted
-openspec validate add-2fa --strict
+```text
+You: Can you add acceptance criteria for the role and team filters?
 
-# After deployment, archive the completed change
-openspec archive add-2fa
-# This moves the change to archive/ and updates specs/
+AI:  I'll update the spec delta with scenarios for role and team filters.
+     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
 ```
 
-## Common Commands
+#### 4. Implement the Change
+Once specs look good, start implementation:
 
+```text
+You: The specs look good. Let's implement this change.
+     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
+
+AI:  I'll work through the tasks in the add-profile-filters change.
+     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
+     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
+```
+
+#### 5. Archive the Completed Change
+After implementation is complete, archive the change:
+
+```text
+AI:  All tasks are complete. The implementation is ready.
+
+You: Please archive the change
+     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
+
+AI:  I'll archive the add-profile-filters change.
+     *Runs: openspec archive add-profile-filters*
+     ✓ Change archived successfully. Specs updated. Ready for the next feature!
+```
+
+Or run the command yourself in terminal:
 ```bash
-# Most used:
-openspec list              # See what changes you're working on
-openspec archive <change>  # Mark a change as complete after deployment
+$ openspec archive add-profile-filters  # Archive the completed change
+```
 
-# Also useful:
-openspec validate <change> # Check formatting before committing
-openspec show <change>     # View change details
+**Note:** Tools with native slash commands (Claude Code, Cursor) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
+
+## Command Reference
+
+```bash
+openspec list               # View active change folders
+openspec view               # Interactive dashboard of specs and changes
+openspec show <change>      # Display change details (proposal, tasks, spec updates)
+openspec validate <change>  # Check spec formatting and structure
+openspec archive <change>   # Move a completed change into archive/
 ```
 
 ## Example: How AI Creates OpenSpec Files
@@ -236,46 +288,38 @@ Deltas are "patches" that show how specs change:
 - Every requirement needs at least one `#### Scenario:` block
 - Use SHALL/MUST in requirement text
 
-
-## Why OpenSpec Works
-
-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
-
-**True Interoperability:** OpenSpec is designed to be universal. No API keys, no vendor lock-in. It works by adding context rules to ANY AI coding tool - whether you use Claude Code today, switch to Cursor tomorrow, or adopt the next breakthrough AI assistant. Your specs remain portable and your workflow stays consistent.
-
-
 ## How OpenSpec Compares
 
 ### 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.
+OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
 
 ### 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.
+Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
 
 ## Team Adoption
 
-### Getting Started with Your Team
+1. **Initialize OpenSpec** – Run `openspec init` in your repo.
+2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
+3. **Grow incrementally** – Each change archives into living specs that document your system.
+4. **Stay flexible** – Different teammates can use Claude Code, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
 
-1. **Initialize OpenSpec** - Run `openspec init` in your project
-2. **Start with new features** - Use OpenSpec for your next change proposal
-3. **Build incrementally** - Each new feature adds to your spec library
-4. **Future capability** - We're working on tools to generate specs from existing code
+Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
 
-**Tool Freedom:** Your team can use different AI assistants. One developer might use Claude Code while another uses Cursor - OpenSpec keeps everyone aligned through shared specifications. Run `openspec update` to configure for any supported tool without affecting others.
+## Updating OpenSpec
 
+1. **Upgrade the package**
+   ```bash
+   npm install -g @fission-ai/openspec@latest
+   ```
+2. **Refresh agent instructions**
+   - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
 
 ## Contributing
 
-- Install dependencies: `npm install`
-- Build: `npm run build`
-- Test: `npm test`
-- Develop CLI locally: `npm run dev` or `npm run dev:cli`
+- Install dependencies: `pnpm install`
+- Build: `pnpm run build`
+- Test: `pnpm test`
+- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
 - Conventional commits (one-line): `type(scope): subject`
 
 ## License

package/dist/core/config.d.ts

@@ -1,14 +1,16 @@
 export declare const OPENSPEC_DIR_NAME = "openspec";
-export interface OpenSpecConfig {
-    aiTools: string[];
-}
 export declare const OPENSPEC_MARKERS: {
     start: string;
     end: string;
 };
-export declare const AI_TOOLS: {
+export interface OpenSpecConfig {
+    aiTools: string[];
+}
+export interface AIToolOption {
     name: string;
     value: string;
     available: boolean;
-}[];
+    successLabel?: string;
+}
+export declare const AI_TOOLS: AIToolOption[];
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -4,9 +4,8 @@ export const OPENSPEC_MARKERS = {
     end: '<!-- OPENSPEC:END -->'
 };
 export const AI_TOOLS = [
-    { name: 'Claude Code', value: 'claude', available: true },
-    { name: 'Cursor', value: 'cursor', available: true },
-    { name: 'Aider', value: 'aider', available: false },
-    { name: 'Continue', value: 'continue', available: false }
+    { name: 'Claude Code (✅ OpenSpec custom slash commands available)', value: 'claude', available: true, successLabel: 'Claude Code' },
+    { name: 'Cursor (✅ OpenSpec custom slash commands available)', value: 'cursor', available: true, successLabel: 'Cursor' },
+    { name: 'AGENTS.md (works with Codex, Amp, Copilot, …)', value: 'agents', available: true, successLabel: 'your AGENTS.md-compatible assistant' }
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/configurators/agents.d.ts

@@ -0,0 +1,8 @@
+import { ToolConfigurator } from './base.js';
+export declare class AgentsStandardConfigurator implements ToolConfigurator {
+    name: string;
+    configFileName: string;
+    isAvailable: boolean;
+    configure(projectPath: string, _openspecDir: string): Promise<void>;
+}
+//# sourceMappingURL=agents.d.ts.map

package/dist/core/configurators/agents.js

@@ -0,0 +1,15 @@
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { TemplateManager } from '../templates/index.js';
+import { OPENSPEC_MARKERS } from '../config.js';
+export class AgentsStandardConfigurator {
+    name = 'AGENTS.md standard';
+    configFileName = 'AGENTS.md';
+    isAvailable = true;
+    async configure(projectPath, _openspecDir) {
+        const filePath = path.join(projectPath, this.configFileName);
+        const content = TemplateManager.getAgentsStandardTemplate();
+        await FileSystemUtils.updateFileWithMarkers(filePath, content, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/core/configurators/registry.js

@@ -1,10 +1,13 @@
 import { ClaudeConfigurator } from './claude.js';
+import { AgentsStandardConfigurator } from './agents.js';
 export class ToolRegistry {
     static tools = new Map();
     static {
         const claudeConfigurator = new ClaudeConfigurator();
+        const agentsConfigurator = new AgentsStandardConfigurator();
         // Register with the ID that matches the checkbox value
         this.tools.set('claude', claudeConfigurator);
+        this.tools.set('agents', agentsConfigurator);
     }
     static register(tool) {
         this.tools.set(tool.name.toLowerCase().replace(/\s+/g, '-'), tool);

package/dist/core/init.d.ts

@@ -1,10 +1,38 @@
+type ToolLabel = {
+    primary: string;
+    annotation?: string;
+};
+type ToolWizardChoice = {
+    value: string;
+    label: ToolLabel;
+    configured: boolean;
+};
+type ToolWizardConfig = {
+    extendMode: boolean;
+    baseMessage: string;
+    choices: ToolWizardChoice[];
+    initialSelected?: string[];
+};
+type ToolSelectionPrompt = (config: ToolWizardConfig) => Promise<string[]>;
+type InitCommandOptions = {
+    prompt?: ToolSelectionPrompt;
+};
 export declare class InitCommand {
+    private readonly prompt;
+    constructor(options?: InitCommandOptions);
     execute(targetPath: string): Promise<void>;
     private validate;
     private getConfiguration;
+    private promptForAITools;
+    private getExistingToolStates;
+    private isToolConfigured;
     private createDirectoryStructure;
     private generateFiles;
     private configureAITools;
     private displaySuccessMessage;
+    private formatToolNames;
+    private renderBanner;
+    private startSpinner;
 }
+export {};
 //# sourceMappingURL=init.d.ts.map

package/dist/core/init.js

@@ -1,58 +1,335 @@
 import path from 'path';
-import { select } from '@inquirer/prompts';
+import { createPrompt, isBackspaceKey, isDownKey, isEnterKey, isSpaceKey, isUpKey, useKeypress, usePagination, useState } from '@inquirer/core';
+import chalk from 'chalk';
 import ora from 'ora';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
+const PROGRESS_SPINNER = {
+    interval: 80,
+    frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓']
+};
+const PALETTE = {
+    white: chalk.hex('#f4f4f4'),
+    lightGray: chalk.hex('#c8c8c8'),
+    midGray: chalk.hex('#8a8a8a'),
+    darkGray: chalk.hex('#4a4a4a')
+};
+const LETTER_MAP = {
+    O: [
+        ' ████ ',
+        '██  ██',
+        '██  ██',
+        '██  ██',
+        ' ████ '
+    ],
+    P: [
+        '█████ ',
+        '██  ██',
+        '█████ ',
+        '██    ',
+        '██    '
+    ],
+    E: [
+        '██████',
+        '██    ',
+        '█████ ',
+        '██    ',
+        '██████'
+    ],
+    N: [
+        '██  ██',
+        '███ ██',
+        '██ ███',
+        '██  ██',
+        '██  ██'
+    ],
+    S: [
+        ' █████',
+        '██    ',
+        ' ████ ',
+        '    ██',
+        '█████ '
+    ],
+    C: [
+        ' █████',
+        '██    ',
+        '██    ',
+        '██    ',
+        ' █████'
+    ],
+    ' ': [
+        '  ',
+        '  ',
+        '  ',
+        '  ',
+        '  '
+    ]
+};
+const sanitizeToolLabel = (raw) => raw.replace(/✅/gu, '✔').trim();
+const parseToolLabel = (raw) => {
+    const sanitized = sanitizeToolLabel(raw);
+    const match = sanitized.match(/^(.*?)\s*\((.+)\)$/u);
+    if (!match) {
+        return { primary: sanitized };
+    }
+    return {
+        primary: match[1].trim(),
+        annotation: match[2].trim()
+    };
+};
+const toolSelectionWizard = createPrompt((config, done) => {
+    const totalSteps = 3;
+    const [step, setStep] = useState('intro');
+    const [cursor, setCursor] = useState(0);
+    const [selected, setSelected] = useState(() => config.initialSelected ?? []);
+    const [error, setError] = useState(null);
+    const selectedSet = new Set(selected);
+    const pageSize = Math.max(Math.min(config.choices.length, 7), 1);
+    const updateSelected = (next) => {
+        const ordered = config.choices
+            .map((choice) => choice.value)
+            .filter((value) => next.has(value));
+        setSelected(ordered);
+    };
+    const page = usePagination({
+        items: config.choices,
+        active: cursor,
+        pageSize,
+        loop: config.choices.length > 1,
+        renderItem: ({ item, isActive }) => {
+            const isSelected = selectedSet.has(item.value);
+            const cursorSymbol = isActive ? PALETTE.white('›') : PALETTE.midGray(' ');
+            const indicator = isSelected ? PALETTE.white('◉') : PALETTE.midGray('○');
+            const nameColor = isActive ? PALETTE.white : PALETTE.midGray;
+            const label = `${nameColor(item.label.primary)}${item.configured ? PALETTE.midGray(' (already configured)') : ''}`;
+            return `${cursorSymbol} ${indicator} ${label}`;
+        }
+    });
+    useKeypress((key) => {
+        if (step === 'intro') {
+            if (isEnterKey(key)) {
+                setStep('select');
+            }
+            return;
+        }
+        if (step === 'select') {
+            if (isUpKey(key)) {
+                const previousIndex = cursor <= 0 ? config.choices.length - 1 : cursor - 1;
+                setCursor(previousIndex);
+                setError(null);
+                return;
+            }
+            if (isDownKey(key)) {
+                const nextIndex = cursor >= config.choices.length - 1 ? 0 : cursor + 1;
+                setCursor(nextIndex);
+                setError(null);
+                return;
+            }
+            if (isSpaceKey(key)) {
+                const current = config.choices[cursor];
+                if (!current)
+                    return;
+                const next = new Set(selected);
+                if (next.has(current.value)) {
+                    next.delete(current.value);
+                }
+                else {
+                    next.add(current.value);
+                }
+                updateSelected(next);
+                setError(null);
+                return;
+            }
+            if (isEnterKey(key)) {
+                if (selected.length === 0) {
+                    setError('Select at least one AI tool to continue.');
+                    return;
+                }
+                setStep('review');
+                setError(null);
+                return;
+            }
+            if (key.name === 'escape') {
+                setSelected([]);
+                setError(null);
+            }
+            return;
+        }
+        if (step === 'review') {
+            if (isEnterKey(key)) {
+                const finalSelection = config.choices
+                    .map((choice) => choice.value)
+                    .filter((value) => selectedSet.has(value));
+                done(finalSelection);
+                return;
+            }
+            if (isBackspaceKey(key) || key.name === 'escape') {
+                setStep('select');
+                setError(null);
+            }
+        }
+    });
+    const selectedNames = config.choices
+        .filter((choice) => selectedSet.has(choice.value))
+        .map((choice) => choice.label.primary);
+    const stepIndex = step === 'intro' ? 1 : step === 'select' ? 2 : 3;
+    const lines = [];
+    lines.push(PALETTE.midGray(`Step ${stepIndex}/${totalSteps}`));
+    lines.push('');
+    if (step === 'intro') {
+        const introHeadline = config.extendMode
+            ? 'Extend your OpenSpec tooling'
+            : 'Configure your OpenSpec tooling';
+        const introBody = config.extendMode
+            ? 'We detected an existing setup. We will help you refresh or add integrations.'
+            : "Let's get your AI assistants connected so they understand OpenSpec.";
+        lines.push(PALETTE.white(introHeadline));
+        lines.push(PALETTE.midGray(introBody));
+        lines.push('');
+        lines.push(PALETTE.midGray('Press Enter to continue.'));
+    }
+    else if (step === 'select') {
+        lines.push(PALETTE.white(config.baseMessage));
+        lines.push(PALETTE.midGray('Use ↑/↓ to move · Space to toggle · Enter to review selections.'));
+        lines.push('');
+        lines.push(page);
+        lines.push('');
+        if (selectedNames.length === 0) {
+            lines.push(`${PALETTE.midGray('Selected')}: ${PALETTE.midGray('None selected yet')}`);
+        }
+        else {
+            lines.push(PALETTE.midGray('Selected:'));
+            selectedNames.forEach((name) => {
+                lines.push(`  ${PALETTE.white('-')} ${PALETTE.white(name)}`);
+            });
+        }
+    }
+    else {
+        lines.push(PALETTE.white('Review selections'));
+        lines.push(PALETTE.midGray('Press Enter to confirm or Backspace to adjust.'));
+        lines.push('');
+        if (selectedNames.length === 0) {
+            lines.push(PALETTE.midGray('No tools selected. Press Backspace to return.'));
+        }
+        else {
+            selectedNames.forEach((name) => {
+                lines.push(`${PALETTE.white('▌')} ${PALETTE.white(name)}`);
+            });
+        }
+    }
+    if (error) {
+        return [lines.join('\n'), chalk.red(error)];
+    }
+    return lines.join('\n');
+});
 export class InitCommand {
+    prompt;
+    constructor(options = {}) {
+        this.prompt = options.prompt ?? ((config) => toolSelectionWizard(config));
+    }
     async execute(targetPath) {
         const projectPath = path.resolve(targetPath);
         const openspecDir = OPENSPEC_DIR_NAME;
         const openspecPath = path.join(projectPath, openspecDir);
         // Validation happens silently in the background
-        await this.validate(projectPath, openspecPath);
+        const extendMode = await this.validate(projectPath, openspecPath);
+        const existingToolStates = await this.getExistingToolStates(projectPath);
+        this.renderBanner(extendMode);
         // Get configuration (after validation to avoid prompts if validation fails)
-        const config = await this.getConfiguration();
+        const config = await this.getConfiguration(existingToolStates, extendMode);
+        if (config.aiTools.length === 0) {
+            if (extendMode) {
+                throw new Error(`OpenSpec seems to already be initialized at ${openspecPath}.\n` +
+                    `Use 'openspec update' to update the structure.`);
+            }
+            throw new Error('You must select at least one AI tool to configure.');
+        }
+        const availableTools = AI_TOOLS.filter(tool => tool.available);
+        const selectedIds = new Set(config.aiTools);
+        const selectedTools = availableTools.filter(tool => selectedIds.has(tool.value));
+        const created = selectedTools.filter(tool => !existingToolStates[tool.value]);
+        const refreshed = selectedTools.filter(tool => existingToolStates[tool.value]);
+        const skippedExisting = availableTools.filter(tool => !selectedIds.has(tool.value) && existingToolStates[tool.value]);
+        const skipped = availableTools.filter(tool => !selectedIds.has(tool.value) && !existingToolStates[tool.value]);
         // Step 1: Create directory structure
-        const structureSpinner = ora({ text: 'Creating OpenSpec structure...', stream: process.stdout }).start();
-        await this.createDirectoryStructure(openspecPath);
-        await this.generateFiles(openspecPath, config);
-        structureSpinner.succeed('OpenSpec structure created');
+        if (!extendMode) {
+            const structureSpinner = this.startSpinner('Creating OpenSpec structure...');
+            await this.createDirectoryStructure(openspecPath);
+            await this.generateFiles(openspecPath, config);
+            structureSpinner.stopAndPersist({
+                symbol: PALETTE.white('▌'),
+                text: PALETTE.white('OpenSpec structure created')
+            });
+        }
+        else {
+            ora({ stream: process.stdout }).info(PALETTE.midGray('ℹ OpenSpec already initialized. Skipping base scaffolding.'));
+        }
         // Step 2: Configure AI tools
-        const toolSpinner = ora({ text: 'Configuring AI tools...', stream: process.stdout }).start();
+        const toolSpinner = this.startSpinner('Configuring AI tools...');
         await this.configureAITools(projectPath, openspecDir, config.aiTools);
-        toolSpinner.succeed('AI tools configured');
+        toolSpinner.stopAndPersist({
+            symbol: PALETTE.white('▌'),
+            text: PALETTE.white('AI tools configured')
+        });
         // Success message
-        this.displaySuccessMessage(openspecDir, config);
+        this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode);
     }
-    async validate(projectPath, openspecPath) {
-        // Check if OpenSpec already exists
-        if (await FileSystemUtils.directoryExists(openspecPath)) {
-            throw new Error(`OpenSpec seems to already be initialized at ${openspecPath}.\n` +
-                `Use 'openspec update' to update the structure.`);
-        }
+    async validate(projectPath, _openspecPath) {
+        const extendMode = await FileSystemUtils.directoryExists(_openspecPath);
         // Check write permissions
         if (!await FileSystemUtils.ensureWritePermissions(projectPath)) {
             throw new Error(`Insufficient permissions to write to ${projectPath}`);
         }
+        return extendMode;
     }
-    async getConfiguration() {
-        const config = {
-            aiTools: []
-        };
-        // Single-select for better UX
-        const selectedTool = await select({
-            message: 'Which AI tool do you use?',
-            choices: AI_TOOLS.map(tool => ({
-                name: tool.available ? tool.name : `${tool.name} (coming soon)`,
+    async getConfiguration(existingTools, extendMode) {
+        const selectedTools = await this.promptForAITools(existingTools, extendMode);
+        return { aiTools: selectedTools };
+    }
+    async promptForAITools(existingTools, extendMode) {
+        const availableTools = AI_TOOLS.filter(tool => tool.available);
+        if (availableTools.length === 0) {
+            return [];
+        }
+        const baseMessage = extendMode
+            ? 'Which AI tools would you like to add or refresh?'
+            : 'Which AI tools do you use?';
+        const initialSelected = extendMode
+            ? availableTools.filter(tool => existingTools[tool.value]).map(tool => tool.value)
+            : [];
+        return this.prompt({
+            extendMode,
+            baseMessage,
+            choices: availableTools.map((tool) => ({
                 value: tool.value,
-                disabled: !tool.available
-            }))
+                label: parseToolLabel(tool.name),
+                configured: Boolean(existingTools[tool.value])
+            })),
+            initialSelected
         });
-        config.aiTools = [selectedTool];
-        return config;
+    }
+    async getExistingToolStates(projectPath) {
+        const states = {};
+        for (const tool of AI_TOOLS) {
+            states[tool.value] = await this.isToolConfigured(projectPath, tool.value);
+        }
+        return states;
+    }
+    async isToolConfigured(projectPath, toolId) {
+        const configFile = ToolRegistry.get(toolId)?.configFileName;
+        if (configFile && await FileSystemUtils.fileExists(path.join(projectPath, configFile)))
+            return true;
+        const slashConfigurator = SlashCommandRegistry.get(toolId);
+        if (!slashConfigurator)
+            return false;
+        for (const target of slashConfigurator.getTargets()) {
+            if (await FileSystemUtils.fileExists(path.join(projectPath, target.path)))
+                return true;
+        }
+        return false;
     }
     async createDirectoryStructure(openspecPath) {
         const directories = [
@@ -90,25 +367,83 @@ export class InitCommand {
             }
         }
     }
-    displaySuccessMessage(openspecDir, config) {
+    displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode) {
         console.log(); // Empty line for spacing
-        ora().succeed('OpenSpec initialized successfully!');
-        // Get the selected tool name for display
-        const selectedToolId = config.aiTools[0];
-        const selectedTool = AI_TOOLS.find(t => t.value === selectedToolId);
-        const toolName = selectedTool ? selectedTool.name : 'your AI assistant';
-        console.log(`\nNext steps - Copy these prompts to ${toolName}:\n`);
-        console.log('────────────────────────────────────────────────────────────');
-        console.log('1. Populate your project context:');
-        console.log('   "Please read openspec/project.md and help me fill it out');
-        console.log('    with details about my project, tech stack, and conventions"\n');
-        console.log('2. Create your first change proposal:');
-        console.log('   "I want to add [YOUR FEATURE HERE]. Please create an');
-        console.log('    OpenSpec change proposal for this feature"\n');
-        console.log('3. Learn the OpenSpec workflow:');
-        console.log('   "Please explain the OpenSpec workflow from openspec/AGENTS.md');
-        console.log('    and how I should work with you on this project"');
-        console.log('────────────────────────────────────────────────────────────\n');
+        const successHeadline = extendMode
+            ? 'OpenSpec tool configuration updated!'
+            : 'OpenSpec initialized successfully!';
+        ora().succeed(PALETTE.white(successHeadline));
+        console.log();
+        console.log(PALETTE.lightGray('Tool summary:'));
+        const summaryLines = [
+            created.length ? `${PALETTE.white('▌')} ${PALETTE.white('Created:')} ${this.formatToolNames(created)}` : null,
+            refreshed.length ? `${PALETTE.lightGray('▌')} ${PALETTE.lightGray('Refreshed:')} ${this.formatToolNames(refreshed)}` : null,
+            skippedExisting.length ? `${PALETTE.midGray('▌')} ${PALETTE.midGray('Skipped (already configured):')} ${this.formatToolNames(skippedExisting)}` : null,
+            skipped.length ? `${PALETTE.darkGray('▌')} ${PALETTE.darkGray('Skipped:')} ${this.formatToolNames(skipped)}` : null
+        ].filter((line) => Boolean(line));
+        for (const line of summaryLines) {
+            console.log(line);
+        }
+        console.log();
+        console.log(PALETTE.midGray('Use `openspec update` to refresh shared OpenSpec instructions in the future.'));
+        // Get the selected tool name(s) for display
+        const toolName = this.formatToolNames(selectedTools);
+        console.log();
+        console.log(`Next steps - Copy these prompts to ${toolName}:`);
+        console.log(chalk.gray('────────────────────────────────────────────────────────────'));
+        console.log(PALETTE.white('1. Populate your project context:'));
+        console.log(PALETTE.lightGray('   "Please read openspec/project.md and help me fill it out'));
+        console.log(PALETTE.lightGray('    with details about my project, tech stack, and conventions"\n'));
+        console.log(PALETTE.white('2. Create your first change proposal:'));
+        console.log(PALETTE.lightGray('   "I want to add [YOUR FEATURE HERE]. Please create an'));
+        console.log(PALETTE.lightGray('    OpenSpec change proposal for this feature"\n'));
+        console.log(PALETTE.white('3. Learn the OpenSpec workflow:'));
+        console.log(PALETTE.lightGray('   "Please explain the OpenSpec workflow from openspec/AGENTS.md'));
+        console.log(PALETTE.lightGray('    and how I should work with you on this project"'));
+        console.log(PALETTE.darkGray('────────────────────────────────────────────────────────────\n'));
+    }
+    formatToolNames(tools) {
+        const names = tools
+            .map((tool) => tool.successLabel ?? tool.name)
+            .filter((name) => Boolean(name));
+        if (names.length === 0)
+            return PALETTE.lightGray('your AI assistant');
+        if (names.length === 1)
+            return PALETTE.white(names[0]);
+        const base = names.slice(0, -1).map((name) => PALETTE.white(name));
+        const last = PALETTE.white(names[names.length - 1]);
+        return `${base.join(PALETTE.midGray(', '))}${base.length ? PALETTE.midGray(', and ') : ''}${last}`;
+    }
+    renderBanner(_extendMode) {
+        const rows = ['', '', '', '', ''];
+        for (const char of 'OPENSPEC') {
+            const glyph = LETTER_MAP[char] ?? LETTER_MAP[' '];
+            for (let i = 0; i < rows.length; i += 1) {
+                rows[i] += `${glyph[i]}  `;
+            }
+        }
+        const rowStyles = [
+            PALETTE.white,
+            PALETTE.lightGray,
+            PALETTE.midGray,
+            PALETTE.lightGray,
+            PALETTE.white
+        ];
+        console.log();
+        rows.forEach((row, index) => {
+            console.log(rowStyles[index](row.replace(/\s+$/u, '')));
+        });
+        console.log();
+        console.log(PALETTE.white('Welcome to OpenSpec!'));
+        console.log();
+    }
+    startSpinner(text) {
+        return ora({
+            text,
+            stream: process.stdout,
+            color: 'gray',
+            spinner: PROGRESS_SPINNER
+        }).start();
     }
 }
 //# sourceMappingURL=init.js.map

package/dist/core/templates/claude-template.d.ts

@@ -1,2 +1,2 @@
-export declare const claudeTemplate = "# OpenSpec Project\n\nThis project uses OpenSpec for spec-driven development. Specifications are the source of truth.\n\nSee @openspec/AGENTS.md for detailed conventions and guidelines.\n\n## Three-Stage Workflow\n\n### Stage 1: Creating Changes\nCreate proposal for: features, breaking changes, architecture changes\nSkip proposal for: bug fixes, typos, non-breaking updates\n\n### Stage 2: Implementing Changes\n1. Read proposal.md to understand the change\n2. Read design.md if it exists for technical context\n3. Read tasks.md for implementation checklist\n4. Complete tasks one by one\n5. Mark each task complete immediately: `- [x]`\n6. Validate strictly: `openspec validate [change] --strict`\n7. Approval gate: Do not start implementation until the proposal is approved\n\n### Stage 3: Archiving\nAfter deployment, use `openspec archive [change]` (add `--skip-specs` for tooling-only changes)\n\n## Before Any Task\n\n**Always:**\n- Check existing specs: `openspec list --specs`\n- Check active changes: `openspec list`\n- Read relevant specs before creating new ones\n- Prefer modifying existing specs over creating duplicates\n\n## CLI Quick Reference\n\n```bash\n# Essential\nopenspec list              # Active changes\nopenspec list --specs      # Existing specifications\nopenspec show [item]       # View details\nopenspec validate --strict # Validate thoroughly\nopenspec archive [change]  # Archive after deployment\n\n# Interactive\nopenspec show              # Prompts for selection\nopenspec validate          # Bulk validation\n\n# Debugging\nopenspec show [change] --json --deltas-only\n```\n\n## Creating Changes\n\n1. **Directory:** `changes/[change-id]/`\n   - Change ID naming: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`), unique (append `-2`, `-3` if needed)\n2. **Files:**\n   - `proposal.md` - Why, what, impact\n   - `tasks.md` - Implementation checklist\n   - `design.md` - Only if needed (cross-cutting, new deps/data model, security/perf/migration complexity, or high ambiguity)\n   - `specs/[capability]/spec.md` - Delta changes (ADDED/MODIFIED/REMOVED). For multiple capabilities, include multiple files.\n3. **If ambiguous:** ask 1\u20132 clarifying questions before scaffolding\n\n## Search Guidance\n- Enumerate specs: `openspec spec list --long` (or `--json`)\n- Enumerate changes: `openspec list`\n- Show details: `openspec show <spec-id> --type spec`, `openspec show <change-id> --json --deltas-only`\n- Full-text search (use ripgrep): `rg -n \"Requirement:|Scenario:\" openspec/specs`\n\n## Critical: Scenario Format\n\n**CORRECT:**\n```markdown\n#### Scenario: User login\n- **WHEN** valid credentials\n- **THEN** return token\n```\n\n**WRONG:** Using bullets (- **Scenario**), bold (**Scenario:**), or ### headers\n\nEvery requirement MUST have scenarios using `#### Scenario:` format.\n\n## Complexity Management\n\n**Default to minimal:**\n- <100 lines of new code\n- Single-file implementations\n- No frameworks without justification\n- Boring, proven patterns\n\n**Only add complexity with:**\n- Performance data showing need\n- Concrete scale requirements (>1000 users)\n- Multiple proven use cases\n\n## Troubleshooting\n\n**\"Change must have at least one delta\"**\n- Check `changes/[name]/specs/` exists\n- Verify operation prefixes (## ADDED Requirements)\n\n**\"Requirement must have at least one scenario\"**\n- Use `#### Scenario:` format (4 hashtags)\n- Don't use bullets or bold\n\n**Debug:** `openspec show [change] --json --deltas-only`\n";
+export { agentsTemplate as claudeTemplate } from './agents-template.js';
 //# sourceMappingURL=claude-template.d.ts.map

package/dist/core/templates/claude-template.js

@@ -1,106 +1,2 @@
-export const claudeTemplate = `# OpenSpec Project
-
-This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
-
-See @openspec/AGENTS.md for detailed conventions and guidelines.
-
-## Three-Stage Workflow
-
-### Stage 1: Creating Changes
-Create proposal for: features, breaking changes, architecture changes
-Skip proposal for: bug fixes, typos, non-breaking updates
-
-### Stage 2: Implementing Changes
-1. Read proposal.md to understand the change
-2. Read design.md if it exists for technical context
-3. Read tasks.md for implementation checklist
-4. Complete tasks one by one
-5. Mark each task complete immediately: \`- [x]\`
-6. Validate strictly: \`openspec validate [change] --strict\`
-7. Approval gate: Do not start implementation until the proposal is approved
-
-### Stage 3: Archiving
-After deployment, use \`openspec archive [change]\` (add \`--skip-specs\` for tooling-only changes)
-
-## Before Any Task
-
-**Always:**
-- Check existing specs: \`openspec list --specs\`
-- Check active changes: \`openspec list\`
-- Read relevant specs before creating new ones
-- Prefer modifying existing specs over creating duplicates
-
-## CLI Quick Reference
-
-\`\`\`bash
-# Essential
-openspec list              # Active changes
-openspec list --specs      # Existing specifications
-openspec show [item]       # View details
-openspec validate --strict # Validate thoroughly
-openspec archive [change]  # Archive after deployment
-
-# Interactive
-openspec show              # Prompts for selection
-openspec validate          # Bulk validation
-
-# Debugging
-openspec show [change] --json --deltas-only
-\`\`\`
-
-## Creating Changes
-
-1. **Directory:** \`changes/[change-id]/\`
-   - Change ID naming: kebab-case, verb-led (\`add-\`, \`update-\`, \`remove-\`, \`refactor-\`), unique (append \`-2\`, \`-3\` if needed)
-2. **Files:**
-   - \`proposal.md\` - Why, what, impact
-   - \`tasks.md\` - Implementation checklist
-   - \`design.md\` - Only if needed (cross-cutting, new deps/data model, security/perf/migration complexity, or high ambiguity)
-   - \`specs/[capability]/spec.md\` - Delta changes (ADDED/MODIFIED/REMOVED). For multiple capabilities, include multiple files.
-3. **If ambiguous:** ask 1–2 clarifying questions before scaffolding
-
-## Search Guidance
-- Enumerate specs: \`openspec spec list --long\` (or \`--json\`)
-- Enumerate changes: \`openspec list\`
-- Show details: \`openspec show <spec-id> --type spec\`, \`openspec show <change-id> --json --deltas-only\`
-- Full-text search (use ripgrep): \`rg -n "Requirement:|Scenario:" openspec/specs\`
-
-## Critical: Scenario Format
-
-**CORRECT:**
-\`\`\`markdown
-#### Scenario: User login
-- **WHEN** valid credentials
-- **THEN** return token
-\`\`\`
-
-**WRONG:** Using bullets (- **Scenario**), bold (**Scenario:**), or ### headers
-
-Every requirement MUST have scenarios using \`#### Scenario:\` format.
-
-## Complexity Management
-
-**Default to minimal:**
-- <100 lines of new code
-- Single-file implementations
-- No frameworks without justification
-- Boring, proven patterns
-
-**Only add complexity with:**
-- Performance data showing need
-- Concrete scale requirements (>1000 users)
-- Multiple proven use cases
-
-## Troubleshooting
-
-**"Change must have at least one delta"**
-- Check \`changes/[name]/specs/\` exists
-- Verify operation prefixes (## ADDED Requirements)
-
-**"Requirement must have at least one scenario"**
-- Use \`#### Scenario:\` format (4 hashtags)
-- Don't use bullets or bold
-
-**Debug:** \`openspec show [change] --json --deltas-only\`
-`;
+export { agentsTemplate as claudeTemplate } from './agents-template.js';
 //# sourceMappingURL=claude-template.js.map

package/dist/core/templates/index.d.ts

@@ -7,6 +7,7 @@ export interface Template {
 export declare class TemplateManager {
     static getTemplates(context?: ProjectContext): Template[];
     static getClaudeTemplate(): string;
+    static getAgentsStandardTemplate(): string;
     static getSlashCommandBody(id: SlashCommandId): string;
 }
 export { ProjectContext } from './project-template.js';

package/dist/core/templates/index.js

@@ -18,6 +18,9 @@ export class TemplateManager {
     static getClaudeTemplate() {
         return claudeTemplate;
     }
+    static getAgentsStandardTemplate() {
+        return agentsTemplate;
+    }
     static getSlashCommandBody(id) {
         return getSlashCommandBody(id);
     }

package/dist/core/update.js

@@ -1,7 +1,8 @@
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { OPENSPEC_DIR_NAME } from './config.js';
+import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
 import { agentsTemplate } from './templates/agents-template.js';
+import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 export class UpdateCommand {
@@ -15,7 +16,11 @@ export class UpdateCommand {
         }
         // 2. Update AGENTS.md (full replacement)
         const agentsPath = path.join(openspecPath, 'AGENTS.md');
+        const rootAgentsPath = path.join(resolvedProjectPath, 'AGENTS.md');
+        const rootAgentsExisted = await FileSystemUtils.fileExists(rootAgentsPath);
         await FileSystemUtils.writeFile(agentsPath, agentsTemplate);
+        const agentsStandardContent = TemplateManager.getAgentsStandardTemplate();
+        await FileSystemUtils.updateFileWithMarkers(rootAgentsPath, agentsStandardContent, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
         // 3. Update existing AI tool configuration files only
         const configurators = ToolRegistry.getAll();
         const slashConfigurators = SlashCommandRegistry.getAll();
@@ -54,7 +59,9 @@ export class UpdateCommand {
             }
         }
         // 4. Success message (ASCII-safe)
-        const messages = ['Updated OpenSpec instructions (AGENTS.md)'];
+        const instructionUpdates = ['openspec/AGENTS.md'];
+        instructionUpdates.push(`AGENTS.md${rootAgentsExisted ? '' : ' (created)'}`);
+        const messages = [`Updated OpenSpec instructions (${instructionUpdates.join(', ')})`];
         if (updatedFiles.length > 0) {
             messages.push(`Updated AI tool files: ${updatedFiles.join(', ')}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -48,6 +48,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
+    "@inquirer/core": "^10.2.2",
     "@inquirer/prompts": "^7.8.0",
     "chalk": "^5.5.0",
     "commander": "^14.0.0",