docs(changes): use proposal/apply/archive names and per-tool slash naming; add format examples and test guidance

openspec/README.md

@@ -87,6 +87,7 @@ After deployment, create separate PR to:
 openspec list                  # List active changes
 openspec list --specs          # List specifications
 openspec show [item]           # Display change or spec
+openspec diff [change]         # Show spec differences
 openspec validate [item]       # Validate changes or specs
 openspec archive [change]      # Archive after deployment
 
@@ -255,6 +256,19 @@ Every requirement MUST have at least one scenario.
 
 Headers matched with `trim(header)` - whitespace ignored.
 
+#### When to use ADDED vs MODIFIED
+- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
+- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
+- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
+
+Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
+
+Authoring a MODIFIED requirement correctly:
+1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
+2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
+3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
+4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
+
 Example for RENAMED:
 ```markdown
 ## RENAMED Requirements
@@ -425,6 +439,7 @@ Only add complexity with:
 ```bash
 openspec list              # What's in progress?
 openspec show [item]       # View details
+openspec diff [change]     # What's changing?
 openspec validate --strict # Is it correct?
 openspec archive [change]  # Mark complete
 ```

openspec/changes/add-slash-command-support/proposal.md

@@ -0,0 +1,119 @@
+# Add Slash Command Support for Coding Agents
+
+## Summary
+- Enable OpenSpec to generate and update custom slash commands for supported coding agents (Claude Code and Cursor).
+- Provide three slash commands aligned with OpenSpec's workflow: proposal (start a change proposal), apply (implement), and archive.
+- Share slash command templating between agents to make future extensions simple.
+
+## Motivation
+Developers use different coding agents and editors. Having consistent slash commands across tools for the OpenSpec workflow reduces friction and ensures a standard way to trigger the workflow. Supporting both Claude Code and Cursor now lays a foundation for future agents that introduce slash command features.
+
+## Proposal
+1. During `openspec init`, when a user selects a supported tool, generate slash command configuration for three OpenSpec workflow stages:
+   - Claude (namespaced): `/openspec/proposal`, `/openspec/apply`, `/openspec/archive`.
+   - Cursor (flat, prefixed): `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`.
+   - Semantics:
+     - Create – scaffold a change (ID, `proposal.md`, `tasks.md`, delta specs); validate strictly.
+     - Apply – implement an approved change; complete tasks; validate strictly.
+     - Archive – archive after deployment; update specs if needed.
+   - Each command file MUST embed concise, step-by-step instructions sourced from `openspec/README.md` (see Template Content section).
+2. Store slash command files per tool:
+   - Claude Code: `.claude/commands/openspec/{proposal,apply,archive}.md`
+   - Cursor: `.cursor/commands/{openspec-proposal,openspec-apply,openspec-archive}.md`
+   - Ensure nested directories are created.
+3. Command file format and metadata:
+   - Use Markdown with optional YAML frontmatter for tool metadata (name/title, description, category/tags) when supported by the tool.
+   - Place OpenSpec markers around the body only, never inside frontmatter.
+   - Keep the visible slash name, file name, and any frontmatter `name`/`id` consistently aligned (e.g., `proposal`, `openspec-proposal`).
+   - Namespacing: categorize these under “OpenSpec” and prefer unique IDs (e.g., `openspec-proposal`) to avoid collisions.
+4. Centralize templates: define command bodies once and reuse across tools; apply minimal per-tool wrappers (frontmatter, categories, filenames).
+5. During `openspec update`, refresh only existing slash command files (per-file basis) within markers; do not create missing files or new tools.
+
+## Design Ideas
+- Introduce `SlashCommandConfigurator` to manage multiple files per tool.
+  - Expose targets rather than a single `configFileName` (e.g., `getTargets(): Array<{ path: string; kind: 'slash'; id: string }>`).
+  - Provide `generateAll(projectPath, openspecDir)` for init and `updateExisting(projectPath, openspecDir)` for update.
+- Per-tool adapters add only frontmatter and pathing; bodies come from shared templates.
+- Templates live in `TemplateManager` with helpers that extract concise, authoritative snippets from `openspec/README.md`.
+- Update flow logs per-file results so users see exactly which slash files were refreshed.
+
+### Marker Placement
+- Markers MUST wrap only the Markdown body contents:
+  - Frontmatter (if present) goes first.
+  - Then `<!-- OPENSPEC:START -->` … body … `<!-- OPENSPEC:END -->`.
+  - Avoid inserting markers into the YAML block to prevent parse errors.
+
+### Idempotency and Creation Rules
+- `init`: create all three files for the chosen tool(s) once; subsequent `init` runs are no-ops for existing files.
+- `update`: refresh only files that exist; skip missing ones without creating new files.
+- Directory creation for `.claude/commands/openspec/` and `.cursor/commands/` is the configurator’s responsibility.
+
+### Command Naming & UX
+- Claude Code: use namespacing in the slash itself for readability and grouping: `/openspec/proposal`, `/openspec/apply`, `/openspec/archive`.
+- Cursor: use flat names with an `openspec-` prefix: `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`. Group via `category: OpenSpec` when supported.
+- Consistency: align file names, visible slash names, and any frontmatter `id` (e.g., `id: openspec-apply`).
+- Migration: do not rename existing commands during `update`; apply new naming only on `init` (or via an explicit migrate step).
+
+## Open Questions
+- Validate exact metadata/frontmatter supported by each tool version; if unsupported, omit frontmatter and ship Markdown body only.
+- Confirm the final Cursor command file location for the targeted versions; fall back to Markdown-only if Cursor does not parse frontmatter.
+- Evaluate additional commands beyond the initial three (e.g., `/show-change`, `/validate-all`) based on user demand.
+
+## Alternatives
+- Hard-code slash command text per tool (rejected: duplicates content; increases maintenance).
+- Delay Cursor support until its config stabilizes (partial accept): gate Cursor behind a feature flag until verified in real environments.
+
+## Risks
+- Tool configuration formats may change, requiring updates to wrappers/frontmatter.
+- Incorrect paths or categories can hide commands; add path existence checks and clear logging.
+- Marker misuse (inside frontmatter) can break parsing; enforce placement rules in tests.
+
+## Future Work
+- Support additional editors/agents that expose slash command APIs.
+- Allow users to customize command names and categories during `openspec init`.
+- Provide a dedicated command to regenerate slash commands without running full `update`.
+
+## File Format Examples
+The following examples illustrate expected structure. If a tool does not support frontmatter, omit the YAML block and keep only the markers + body.
+
+### Claude Code: `.claude/commands/openspec/proposal.md`
+```markdown
+---
+name: OpenSpec: Proposal
+description: Scaffold a new OpenSpec change and validate strictly.
+category: OpenSpec
+tags: [openspec, change]
+---
+<!-- OPENSPEC:START -->
+...command body from shared template...
+<!-- OPENSPEC:END -->
+```
+
+Slash invocation: `/openspec/proposal` (namespaced)
+
+### Cursor: `.cursor/commands/openspec-proposal.md`
+```markdown
+---
+name: /openspec-proposal
+id: openspec-proposal
+category: OpenSpec
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+...command body from shared template...
+<!-- OPENSPEC:END -->
+```
+
+Slash invocation: `/openspec-proposal` (flat, prefixed)
+
+## Template Content
+Templates should be brief, actionable, and sourced from `openspec/README.md` to avoid duplication. Each command body includes:
+- Guardrails: ask 1–2 clarifying questions if needed; follow minimal-complexity rules; use `pnpm` for Node projects.
+- Step list tailored to the workflow stage (proposal, apply, archive), including strict validation commands.
+- Pointers to `openspec show`, `openspec list`, and troubleshooting tips when validation fails.
+
+## Testing Strategy
+- Golden snapshots for generated files per tool (frontmatter + markers + body).
+- Partial presence tests: if 1–2 files exist, `update` only refreshes those and does not create missing ones.
+- Marker placement tests: ensure markers never appear inside frontmatter; cover missing/duplicated marker recovery behavior.
+- Logging tests: `update` reports per-file updates for slash commands.

openspec/changes/add-slash-command-support/specs/cli-init/spec.md

@@ -0,0 +1,15 @@
+## ADDED Requirements
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage

openspec/changes/add-slash-command-support/specs/cli-update/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update

openspec/changes/add-slash-command-support/tasks.md

@@ -0,0 +1,16 @@
+# Implementation Tasks
+
+## 1. Templates and Configurators
+- [ ] 1.1 Create shared templates for the Proposal, Apply, and Archive commands with instructions for each workflow stage from `openspec/README.md`.
+- [ ] 1.2 Implement a `SlashCommandConfigurator` base and tool-specific configurators for Claude Code and Cursor.
+
+## 2. Claude Code Integration
+- [ ] 2.1 Generate `.claude/commands/openspec/{proposal,apply,archive}.md` during `openspec init` using shared templates.
+- [ ] 2.2 Update existing `.claude/commands/openspec/*` files during `openspec update`.
+
+## 3. Cursor Integration
+- [ ] 3.1 Generate `.cursor/commands/{openspec-proposal,openspec-apply,openspec-archive}.md` during `openspec init` using shared templates.
+- [ ] 3.2 Update existing `.cursor/commands/*` files during `openspec update`.
+
+## 4. Verification
+- [ ] 4.1 Add tests verifying slash command files are created and updated correctly.

openspec/changes/archive/2025-09-12-add-view-dashboard-command/proposal.md

@@ -1,38 +0,0 @@
-# Change: Add View Dashboard Command
-
-## Why
-
-Users need a quick, at-a-glance overview of their OpenSpec project status without running multiple commands. Currently, users must run `openspec list --changes` and `openspec list --specs` separately to understand the project state. A unified dashboard view would improve developer experience and provide immediate insight into project progress.
-
-## What Changes
-
-### Added `openspec view` Command
-
-The new command provides an interactive dashboard displaying:
-- Summary metrics (total specs, requirements, changes, task progress)
-- Active changes with visual progress bars
-- Completed changes
-- Specifications with requirement counts
-
-### Specifications Affected
-
-- **cli-view** (NEW): Complete specification for the view dashboard command
-
-## Implementation Details
-
-### File Structure
-- Created `/src/core/view.ts` implementing the `ViewCommand` class
-- Registered command in `/src/cli/index.ts`
-- Reuses existing utilities from `task-progress.ts` and `MarkdownParser`
-
-### Visual Design
-- Uses Unicode box drawing characters for borders
-- Color coding: cyan for specs, yellow for active, green for completed
-- Progress bars using filled (█) and empty (░) blocks
-- Clean alignment with proper padding
-
-### Technical Approach
-- Async data fetching from changes and specs directories
-- Parallel processing of specs and changes
-- Error handling for missing or invalid data
-- Maintains consistency with existing list command output

openspec/changes/archive/2025-09-12-add-view-dashboard-command/specs/cli-view/spec.md

@@ -1,109 +0,0 @@
-# CLI View Command - Changes
-
-## ADDED Requirements
-
-### Requirement: Dashboard Display
-
-The system SHALL provide a `view` command that displays a dashboard overview of specs and changes.
-
-#### Scenario: Basic dashboard display
-
-- **WHEN** user runs `openspec view`
-- **THEN** system displays a formatted dashboard with sections for summary, active changes, completed changes, and specifications
-
-#### Scenario: No OpenSpec directory
-
-- **WHEN** user runs `openspec view` in a directory without OpenSpec
-- **THEN** system displays error message "✗ No openspec directory found"
-
-### Requirement: Summary Section
-
-The dashboard SHALL display a summary section with key project metrics.
-
-#### Scenario: Complete summary display
-
-- **WHEN** dashboard is rendered with specs and changes
-- **THEN** system shows total number of specifications and requirements
-- **AND** shows number of active changes in progress
-- **AND** shows number of completed changes
-- **AND** shows overall task progress percentage
-
-#### Scenario: Empty project summary
-
-- **WHEN** no specs or changes exist
-- **THEN** summary shows zero counts for all metrics
-
-### Requirement: Active Changes Display
-
-The dashboard SHALL show active changes with visual progress indicators.
-
-#### Scenario: Active changes with progress bars
-
-- **WHEN** there are in-progress changes with tasks
-- **THEN** system displays each change with change name left-aligned
-- **AND** visual progress bar using Unicode characters
-- **AND** percentage completion on the right
-
-#### Scenario: No active changes
-
-- **WHEN** all changes are completed or no changes exist
-- **THEN** active changes section is omitted from display
-
-### Requirement: Completed Changes Display
-
-The dashboard SHALL list completed changes in a separate section.
-
-#### Scenario: Completed changes listing
-
-- **WHEN** there are completed changes (all tasks done)
-- **THEN** system shows them with checkmark indicators in a dedicated section
-
-#### Scenario: Mixed completion states
-
-- **WHEN** some changes are complete and others active
-- **THEN** system separates them into appropriate sections
-
-### Requirement: Specifications Display
-
-The dashboard SHALL display specifications sorted by requirement count.
-
-#### Scenario: Specs listing with counts
-
-- **WHEN** specifications exist in the project
-- **THEN** system shows specs sorted by requirement count (descending) with count labels
-
-#### Scenario: Specs with parsing errors
-
-- **WHEN** a spec file cannot be parsed
-- **THEN** system includes it with 0 requirement count
-
-### Requirement: Visual Formatting
-
-The dashboard SHALL use consistent visual formatting with colors and symbols.
-
-#### Scenario: Color coding
-
-- **WHEN** dashboard elements are displayed
-- **THEN** system uses cyan for specification items
-- **AND** yellow for active changes
-- **AND** green for completed items
-- **AND** dim gray for supplementary text
-
-#### Scenario: Progress bar rendering
-
-- **WHEN** displaying progress bars
-- **THEN** system uses filled blocks (█) for completed portions and light blocks (░) for remaining
-
-### Requirement: Error Handling
-
-The view command SHALL handle errors gracefully.
-
-#### Scenario: File system errors
-
-- **WHEN** file system operations fail
-- **THEN** system continues with available data and omits inaccessible items
-
-#### Scenario: Invalid data structures
-
-- **WHEN** specs or changes have invalid format
-- **THEN** system skips invalid items and continues rendering

openspec/changes/archive/2025-09-12-add-view-dashboard-command/tasks.md

@@ -1,47 +0,0 @@
-# Implementation Tasks
-
-## Design Phase
-- [x] Research existing list command implementation
-- [x] Design dashboard layout and information architecture
-- [x] Choose appropriate command verb (`view`)
-- [x] Define visual elements (progress bars, colors, layout)
-
-## Core Implementation
-- [x] Create ViewCommand class in `/src/core/view.ts`
-- [x] Implement getChangesData method for fetching change information
-- [x] Implement getSpecsData method for fetching spec information
-- [x] Implement displaySummary method for summary metrics
-- [x] Add progress bar visualization with Unicode characters
-- [x] Implement color coding using chalk
-
-## Integration
-- [x] Import ViewCommand in CLI index
-- [x] Register `openspec view` command with commander
-- [x] Add proper error handling and ora spinner integration
-- [x] Ensure command appears in help documentation
-
-## Data Processing
-- [x] Reuse TaskProgress utilities for change progress
-- [x] Integrate MarkdownParser for spec requirement counting
-- [x] Handle async operations for file system access
-- [x] Sort specifications by requirement count
-
-## Testing and Validation
-- [x] Build project successfully with new command
-- [x] Test command with sample data
-- [x] Verify correct requirement counts match list --specs
-- [x] Test progress bar display for various completion states
-- [x] Run existing test suite to ensure no regressions
-- [x] Verify TypeScript compilation with no errors
-
-## Documentation
-- [x] Add command description in CLI help
-- [x] Create change proposal documentation
-- [x] Update README with view command example (if needed)
-- [x] Add view command to user documentation (if exists)
-
-## Polish
-- [x] Ensure consistent formatting and alignment
-- [x] Add helpful footer text referencing list commands
-- [x] Optimize for terminal width considerations
-- [x] Review and refine color choices for accessibility

openspec/changes/make-validation-scope-aware/proposal.md

@@ -0,0 +1,12 @@
+## Why
+Validation currently errors on changes without spec deltas, even when the change is intentionally proposal-only or tooling-only. This creates false negatives and noisy CI.
+
+## What Changes
+- Make change validation scope-aware: validate only artifacts that exist.
+- Only error on "No deltas found" if spec delta files exist but parse to zero deltas.
+- Keep archive stricter: if specs exist but parse to zero deltas, fail; allow `--skip-specs` for tooling-only changes.
+
+## Impact
+- Affected specs: cli-validate
+- Affected code: `src/commands/validate.ts`, `src/core/validation/validator.ts`
+

openspec/changes/make-validation-scope-aware/specs/cli-validate/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+### Requirement: Scope-Aware Change Validation
+The validator SHALL validate only artifacts that exist for a change, avoiding errors for proposal-only or tooling-only changes.
+
+#### Scenario: Proposal-only change
+- **WHEN** a change contains `proposal.md` but has no `specs/` directory or contains no `*/spec.md` files
+- **THEN** validate the proposal (Why/What sections)
+- **AND** do not require or validate spec deltas
+
+#### Scenario: Delta validation when specs exist
+- **WHEN** a change contains one or more `specs/<capability>/spec.md` files
+- **THEN** validate delta-formatted specs with existing rules (SHALL/MUST, scenarios, duplicates, conflicts)
+
+## MODIFIED Requirements
+### Requirement: Validation SHALL provide actionable remediation steps
+Validation output SHALL include specific guidance to fix each error, including expected structure, example headers, and suggested commands to verify fixes.
+
+#### Scenario: No deltas found in change
+- **WHEN** validating a change that contains `specs/` with one or more `*/spec.md` files but the parser finds zero deltas
+- **THEN** show error "No deltas found" with guidance:
+  - Ensure `openspec/changes/{id}/specs/` has `.md` files that include delta headers
+  - Use delta headers: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements`
+  - Each requirement must include at least one `#### Scenario:` block
+  - Try: `openspec change show {id} --json --deltas-only` to inspect parsed deltas
+

openspec/changes/make-validation-scope-aware/tasks.md

@@ -0,0 +1,16 @@
+## 1. Validator changes
+- [ ] 1.1 Change `validateChangeDeltaSpecs` to only emit "Change must have at least one delta" when `specs/` exists and contains at least one `*/spec.md` but parsed total deltas is 0
+- [ ] 1.2 Return valid (no error) when `specs/` directory is missing or has no `spec.md` files
+
+## 2. CLI changes
+- [ ] 2.1 In bulk validation, keep current behavior (call delta validator). Behavior remains correct after 1.1
+- [ ] 2.2 Add a short INFO log in human-readable mode when a change has no `specs/` (optional)
+
+## 3. Documentation
+- [ ] 3.1 Update README and template: "Validation checks only existing artifacts. Proposal-only changes are valid without spec deltas."
+
+## 4. Tests
+- [ ] 4.1 Add test: proposal-only change passes validation without deltas
+- [ ] 4.2 Add test: specs present but zero parsed deltas → ERROR
+- [ ] 4.3 Add test: specs present with proper deltas → valid
+

openspec/specs/cli-view/spec.md

@@ -1,112 +0,0 @@
-# cli-view Specification
-
-## Purpose
-
-The `openspec view` command provides a comprehensive dashboard view of the OpenSpec project state, displaying specifications, changes, and progress metrics in a unified, visually appealing format to help developers quickly understand project status.
-## Requirements
-### Requirement: Dashboard Display
-
-The system SHALL provide a `view` command that displays a dashboard overview of specs and changes.
-
-#### Scenario: Basic dashboard display
-
-- **WHEN** user runs `openspec view`
-- **THEN** system displays a formatted dashboard with sections for summary, active changes, completed changes, and specifications
-
-#### Scenario: No OpenSpec directory
-
-- **WHEN** user runs `openspec view` in a directory without OpenSpec
-- **THEN** system displays error message "✗ No openspec directory found"
-
-### Requirement: Summary Section
-
-The dashboard SHALL display a summary section with key project metrics.
-
-#### Scenario: Complete summary display
-
-- **WHEN** dashboard is rendered with specs and changes
-- **THEN** system shows total number of specifications and requirements
-- **AND** shows number of active changes in progress
-- **AND** shows number of completed changes
-- **AND** shows overall task progress percentage
-
-#### Scenario: Empty project summary
-
-- **WHEN** no specs or changes exist
-- **THEN** summary shows zero counts for all metrics
-
-### Requirement: Active Changes Display
-
-The dashboard SHALL show active changes with visual progress indicators.
-
-#### Scenario: Active changes with progress bars
-
-- **WHEN** there are in-progress changes with tasks
-- **THEN** system displays each change with change name left-aligned
-- **AND** visual progress bar using Unicode characters
-- **AND** percentage completion on the right
-
-#### Scenario: No active changes
-
-- **WHEN** all changes are completed or no changes exist
-- **THEN** active changes section is omitted from display
-
-### Requirement: Completed Changes Display
-
-The dashboard SHALL list completed changes in a separate section.
-
-#### Scenario: Completed changes listing
-
-- **WHEN** there are completed changes (all tasks done)
-- **THEN** system shows them with checkmark indicators in a dedicated section
-
-#### Scenario: Mixed completion states
-
-- **WHEN** some changes are complete and others active
-- **THEN** system separates them into appropriate sections
-
-### Requirement: Specifications Display
-
-The dashboard SHALL display specifications sorted by requirement count.
-
-#### Scenario: Specs listing with counts
-
-- **WHEN** specifications exist in the project
-- **THEN** system shows specs sorted by requirement count (descending) with count labels
-
-#### Scenario: Specs with parsing errors
-
-- **WHEN** a spec file cannot be parsed
-- **THEN** system includes it with 0 requirement count
-
-### Requirement: Visual Formatting
-
-The dashboard SHALL use consistent visual formatting with colors and symbols.
-
-#### Scenario: Color coding
-
-- **WHEN** dashboard elements are displayed
-- **THEN** system uses cyan for specification items
-- **AND** yellow for active changes
-- **AND** green for completed items
-- **AND** dim gray for supplementary text
-
-#### Scenario: Progress bar rendering
-
-- **WHEN** displaying progress bars
-- **THEN** system uses filled blocks (█) for completed portions and light blocks (░) for remaining
-
-### Requirement: Error Handling
-
-The view command SHALL handle errors gracefully.
-
-#### Scenario: File system errors
-
-- **WHEN** file system operations fail
-- **THEN** system continues with available data and omits inaccessible items
-
-#### Scenario: Invalid data structures
-
-- **WHEN** specs or changes have invalid format
-- **THEN** system skips invalid items and continues rendering
-

src/cli/index.ts

@@ -7,7 +7,6 @@ import { InitCommand } from '../core/init.js';
 import { UpdateCommand } from '../core/update.js';
 import { ListCommand } from '../core/list.js';
 import { ArchiveCommand } from '../core/archive.js';
-import { ViewCommand } from '../core/view.js';
 import { registerSpecCommand } from '../commands/spec.js';
 import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
@@ -98,20 +97,6 @@ program
     }
   });
 
-program
-  .command('view')
-  .description('Display an interactive dashboard of specs and changes')
-  .action(async () => {
-    try {
-      const viewCommand = new ViewCommand();
-      await viewCommand.execute('.');
-    } catch (error) {
-      console.log(); // Empty line for spacing
-      ora().fail(`Error: ${(error as Error).message}`);
-      process.exit(1);
-    }
-  });
-
 // Change command with subcommands
 const changeCmd = program
   .command('change')

src/core/templates/readme-template.ts

@@ -256,6 +256,19 @@ Every requirement MUST have at least one scenario.
 
 Headers matched with \`trim(header)\` - whitespace ignored.
 
+#### When to use ADDED vs MODIFIED
+- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
+- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
+- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
+
+Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
+
+Authoring a MODIFIED requirement correctly:
+1) Locate the existing requirement in \`openspec/specs/<capability>/spec.md\`.
+2) Copy the entire requirement block (from \`### Requirement: ...\` through its scenarios).
+3) Paste it under \`## MODIFIED Requirements\` and edit to reflect the new behavior.
+4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one \`#### Scenario:\`.
+
 Example for RENAMED:
 \`\`\`markdown
 ## RENAMED Requirements

src/core/view.ts

@@ -1,182 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import chalk from 'chalk';
-import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
-import { MarkdownParser } from './parsers/markdown-parser.js';
-
-export class ViewCommand {
-  async execute(targetPath: string = '.'): Promise<void> {
-    const openspecDir = path.join(targetPath, 'openspec');
-    
-    if (!fs.existsSync(openspecDir)) {
-      console.error(chalk.red('No openspec directory found'));
-      process.exit(1);
-    }
-
-    console.log(chalk.bold('\nOpenSpec Dashboard\n'));
-    console.log('═'.repeat(60));
-
-    // Get changes and specs data
-    const changesData = await this.getChangesData(openspecDir);
-    const specsData = await this.getSpecsData(openspecDir);
-
-    // Display summary metrics
-    this.displaySummary(changesData, specsData);
-
-    // Display active changes
-    if (changesData.active.length > 0) {
-      console.log(chalk.bold.cyan('\nActive Changes'));
-      console.log('─'.repeat(60));
-      changesData.active.forEach(change => {
-        const progressBar = this.createProgressBar(change.progress.completed, change.progress.total);
-        const percentage = change.progress.total > 0 
-          ? Math.round((change.progress.completed / change.progress.total) * 100)
-          : 0;
-        
-        console.log(
-          `  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(30))} ${progressBar} ${chalk.dim(`${percentage}%`)}`
-        );
-      });
-    }
-
-    // Display completed changes
-    if (changesData.completed.length > 0) {
-      console.log(chalk.bold.green('\nCompleted Changes'));
-      console.log('─'.repeat(60));
-      changesData.completed.forEach(change => {
-        console.log(`  ${chalk.green('✓')} ${change.name}`);
-      });
-    }
-
-    // Display specifications
-    if (specsData.length > 0) {
-      console.log(chalk.bold.blue('\nSpecifications'));
-      console.log('─'.repeat(60));
-      
-      // Sort specs by requirement count (descending)
-      specsData.sort((a, b) => b.requirementCount - a.requirementCount);
-      
-      specsData.forEach(spec => {
-        const reqLabel = spec.requirementCount === 1 ? 'requirement' : 'requirements';
-        console.log(
-          `  ${chalk.blue('▪')} ${chalk.bold(spec.name.padEnd(30))} ${chalk.dim(`${spec.requirementCount} ${reqLabel}`)}`
-        );
-      });
-    }
-
-    console.log('\n' + '═'.repeat(60));
-    console.log(chalk.dim(`\nUse ${chalk.white('openspec list --changes')} or ${chalk.white('openspec list --specs')} for detailed views`));
-  }
-
-  private async getChangesData(openspecDir: string): Promise<{
-    active: Array<{ name: string; progress: { total: number; completed: number } }>;
-    completed: Array<{ name: string }>;
-  }> {
-    const changesDir = path.join(openspecDir, 'changes');
-    
-    if (!fs.existsSync(changesDir)) {
-      return { active: [], completed: [] };
-    }
-
-    const active: Array<{ name: string; progress: { total: number; completed: number } }> = [];
-    const completed: Array<{ name: string }> = [];
-
-    const entries = fs.readdirSync(changesDir, { withFileTypes: true });
-    
-    for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== 'archive') {
-        const progress = await getTaskProgressForChange(changesDir, entry.name);
-        
-        if (progress.total === 0 || progress.completed === progress.total) {
-          completed.push({ name: entry.name });
-        } else {
-          active.push({ name: entry.name, progress });
-        }
-      }
-    }
-
-    // Sort alphabetically
-    active.sort((a, b) => a.name.localeCompare(b.name));
-    completed.sort((a, b) => a.name.localeCompare(b.name));
-
-    return { active, completed };
-  }
-
-  private async getSpecsData(openspecDir: string): Promise<Array<{ name: string; requirementCount: number }>> {
-    const specsDir = path.join(openspecDir, 'specs');
-    
-    if (!fs.existsSync(specsDir)) {
-      return [];
-    }
-
-    const specs: Array<{ name: string; requirementCount: number }> = [];
-    const entries = fs.readdirSync(specsDir, { withFileTypes: true });
-    
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        const specFile = path.join(specsDir, entry.name, 'spec.md');
-        
-        if (fs.existsSync(specFile)) {
-          try {
-            const content = fs.readFileSync(specFile, 'utf-8');
-            const parser = new MarkdownParser(content);
-            const spec = parser.parseSpec(entry.name);
-            const requirementCount = spec.requirements.length;
-            specs.push({ name: entry.name, requirementCount });
-          } catch (error) {
-            // If spec cannot be parsed, include with 0 count
-            specs.push({ name: entry.name, requirementCount: 0 });
-          }
-        }
-      }
-    }
-
-    return specs;
-  }
-
-  private displaySummary(
-    changesData: { active: any[]; completed: any[] },
-    specsData: any[]
-  ): void {
-    const totalChanges = changesData.active.length + changesData.completed.length;
-    const totalSpecs = specsData.length;
-    const totalRequirements = specsData.reduce((sum, spec) => sum + spec.requirementCount, 0);
-    
-    // Calculate total task progress
-    let totalTasks = 0;
-    let completedTasks = 0;
-    
-    changesData.active.forEach(change => {
-      totalTasks += change.progress.total;
-      completedTasks += change.progress.completed;
-    });
-    
-    changesData.completed.forEach(() => {
-      // Completed changes count as 100% done (we don't know exact task count)
-      // This is a simplification
-    });
-
-    console.log(chalk.bold('Summary:'));
-    console.log(`  ${chalk.cyan('●')} Specifications: ${chalk.bold(totalSpecs)} specs, ${chalk.bold(totalRequirements)} requirements`);
-    console.log(`  ${chalk.yellow('●')} Active Changes: ${chalk.bold(changesData.active.length)} in progress`);
-    console.log(`  ${chalk.green('●')} Completed Changes: ${chalk.bold(changesData.completed.length)}`);
-    
-    if (totalTasks > 0) {
-      const overallProgress = Math.round((completedTasks / totalTasks) * 100);
-      console.log(`  ${chalk.magenta('●')} Task Progress: ${chalk.bold(`${completedTasks}/${totalTasks}`)} (${overallProgress}% complete)`);
-    }
-  }
-
-  private createProgressBar(completed: number, total: number, width: number = 20): string {
-    if (total === 0) return chalk.dim('─'.repeat(width));
-    
-    const percentage = completed / total;
-    const filled = Math.round(percentage * width);
-    const empty = width - filled;
-    
-    const filledBar = chalk.green('█'.repeat(filled));
-    const emptyBar = chalk.dim('░'.repeat(empty));
-    
-    return `[${filledBar}${emptyBar}]`;
-  }
-}