feat: implement hierarchical spec IDs with recursive discovery

Support forward-slash-separated spec IDs (e.g., `cli/show`) alongside
flat IDs, enabling logical grouping of related specs into subtrees.

- Add specIdToPath/pathToSpecId utilities for ID↔path conversion
- Refactor getSpecIds() to use fast-glob recursive `**/spec.md` discovery
- Update all CLI commands (show, list, validate, view) for hierarchical IDs
- Add subtree prefix filtering with segment-boundary matching to `list`
- Extend fuzzy matching with leaf-segment scoring for better suggestions
- Update archive/apply pipeline with recursive delta spec discovery
- Update validator to include full hierarchical paths in error messages
- Create openspec/AGENTS.md with hierarchical spec path documentation
- Add unit, command, and integration tests (1370 passing)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: victorhsb

openspec/AGENTS.md

@@ -0,0 +1,175 @@
+# OpenSpec Agent Instructions
+
+Quick reference for AI assistants working with this project.
+
+---
+
+## Quick Reference
+
+### Spec IDs
+
+Spec IDs are **forward-slash-separated paths** relative to `openspec/specs/`. Both flat and hierarchical IDs are valid:
+
+| ID | File path |
+|----|-----------|
+| `auth` | `openspec/specs/auth/spec.md` |
+| `cli/show` | `openspec/specs/cli/show/spec.md` |
+| `domain/project/feature` | `openspec/specs/domain/project/feature/spec.md` |
+
+IDs always use `/` regardless of operating system.
+
+### CLI Commands
+
+```bash
+# List all specs
+openspec list --specs
+
+# List specs under a subtree (segment-boundary match)
+openspec list --specs cli/
+# "cli/" matches "cli/show", "cli/validate" — NOT "client/config"
+
+# Show a spec (flat or hierarchical)
+openspec show auth
+openspec show cli/show
+
+# Validate a spec
+openspec validate cli/show
+
+# Validate all specs
+openspec validate --specs
+```
+
+### Delta Spec Paths
+
+When writing delta specs for a change, mirror the hierarchical ID under `changes/<name>/specs/`:
+
+```
+openspec/changes/my-feature/specs/
+├── auth/
+│   └── spec.md          # delta for spec ID "auth"
+└── cli/
+    ├── show/
+    │   └── spec.md      # delta for spec ID "cli/show"
+    └── validate/
+        └── spec.md      # delta for spec ID "cli/validate"
+```
+
+---
+
+## Spec Format Templates
+
+### New Spec (`openspec/specs/<id>/spec.md`)
+
+```markdown
+## Purpose
+One sentence describing what this capability does.
+
+## Requirements
+
+### Requirement: <Descriptive Name>
+The system SHALL <behavior>.
+
+#### Scenario: <Scenario Name>
+- **GIVEN** <precondition>
+- **WHEN** <trigger>
+- **THEN** <expected outcome>
+- **AND** <additional outcome>
+```
+
+**For hierarchical specs**, the file lives at `openspec/specs/<domain>/<feature>/spec.md` but the content format is identical. Example for spec ID `cli/show`:
+
+```markdown
+## Purpose
+Display a specification's content by its hierarchical ID.
+
+## Requirements
+
+### Requirement: Hierarchical ID Resolution
+The show command SHALL accept forward-slash-separated spec IDs.
+
+#### Scenario: Show nested spec
+- **GIVEN** a spec exists at openspec/specs/cli/show/spec.md
+- **WHEN** the user runs `openspec show cli/show`
+- **THEN** the spec content is displayed
+```
+
+### Delta Spec (`changes/<name>/specs/<id>/spec.md`)
+
+```markdown
+## ADDED Requirements
+
+### Requirement: <New Requirement Name>
+The system SHALL <new behavior>.
+
+#### Scenario: <Scenario Name>
+- **WHEN** <trigger>
+- **THEN** <outcome>
+
+## MODIFIED Requirements
+
+### Requirement: <Existing Requirement Name>
+The system SHALL <updated behavior>.  ← (was: <old behavior>)
+
+#### Scenario: <Scenario Name>
+- **WHEN** <trigger>
+- **THEN** <updated outcome>
+
+## REMOVED Requirements
+
+### Requirement: <Requirement To Remove>
+Reason: <why it is being removed>
+
+## RENAMED Requirements
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+---
+
+## Workflow
+
+1. **Propose** — create `openspec/changes/<name>/` with `proposal.md`, `tasks.md`, and delta specs under `specs/`
+2. **Implement** — follow `tasks.md` checklist
+3. **Validate** — run `openspec validate --specs` and `openspec validate --changes`
+4. **Archive** — run `openspec archive <name>` to apply deltas and move to `changes/archive/`
+
+---
+
+## Pre-Validation Checklist
+
+Before running `openspec validate`:
+
+- [ ] Every `### Requirement:` block has at least one `#### Scenario:`
+- [ ] Scenarios use `**GIVEN**`/`**WHEN**`/`**THEN**`/`**AND**` keywords
+- [ ] Delta specs use `## ADDED`/`## MODIFIED`/`## REMOVED`/`## RENAMED` section headers
+- [ ] `## MODIFIED` and `## REMOVED` headers exactly match the headers in the current spec
+- [ ] Spec IDs use forward slashes (`cli/show`), not backslashes or hyphens as separators
+- [ ] Each spec file is at `<id>/spec.md` — e.g., `cli/show/spec.md` for ID `cli/show`
+
+---
+
+## Advanced Topics
+
+### Subtree Filtering
+
+`openspec list --specs <prefix>` filters by **segment boundary**:
+
+```bash
+openspec list --specs cli/     # ✓ cli/show, cli/validate
+                               # ✗ client/config (different segment)
+openspec spec list cli/        # same, via deprecated spec subcommand
+```
+
+### Cross-Platform Paths
+
+Spec IDs always use `/`. The CLI converts to OS-specific paths internally — you never need to use `\` in spec IDs on Windows.
+
+### Coexistence of Flat and Hierarchical IDs
+
+Flat IDs (`auth`, `cli-show`) and hierarchical IDs (`cli/show`) coexist without conflict. Migration is not required; both are discovered automatically.
+
+### Writing Specs: Behavior vs. Implementation
+
+- **Specs** (`spec.md`): externally observable behavior, interfaces, error conditions, constraints — no library/framework choices
+- **Design** (`design.md`): internal architecture, library choices, data structures
+- **Tasks** (`tasks.md`): implementation steps and checklist items

openspec/changes/hierarchical-specs/tasks.md

@@ -1,44 +1,44 @@
 ## 1. Core Discovery & Resolution
 
-- [ ] 1.1 Create `specIdToPath(specId: string, baseDir: string): string` and `pathToSpecId(filePath: string, specsDir: string): string` utility functions in `src/utils/` with `/`-normalization on all platforms
-- [ ] 1.2 Refactor `getSpecIds()` in `src/utils/item-discovery.ts` to recursively discover specs using `fast-glob` pattern `**/spec.md` under `openspec/specs/`, deriving IDs from relative paths
-- [ ] 1.3 Update all direct path construction (`path.join(SPECS_DIR, specId, 'spec.md')`) across the codebase to use `specIdToPath()`
-- [ ] 1.4 Add unit tests for `specIdToPath` and `pathToSpecId` including Windows path separator normalization
-- [ ] 1.5 Add unit tests for recursive `getSpecIds()` with flat, nested, mixed, and hidden directory fixtures
+- [x] 1.1 Create `specIdToPath(specId: string, baseDir: string): string` and `pathToSpecId(filePath: string, specsDir: string): string` utility functions in `src/utils/` with `/`-normalization on all platforms
+- [x] 1.2 Refactor `getSpecIds()` in `src/utils/item-discovery.ts` to recursively discover specs using `fast-glob` pattern `**/spec.md` under `openspec/specs/`, deriving IDs from relative paths
+- [x] 1.3 Update all direct path construction (`path.join(SPECS_DIR, specId, 'spec.md')`) across the codebase to use `specIdToPath()`
+- [x] 1.4 Add unit tests for `specIdToPath` and `pathToSpecId` including Windows path separator normalization
+- [x] 1.5 Add unit tests for recursive `getSpecIds()` with flat, nested, mixed, and hidden directory fixtures
 
 ## 2. CLI Commands — Spec Subcommands
 
-- [ ] 2.1 Update `src/commands/spec.ts` `show` subcommand to accept and resolve hierarchical spec IDs (e.g., `cli/show`)
-- [ ] 2.2 Update `src/commands/spec.ts` `list` subcommand to display full hierarchical IDs and accept an optional subtree prefix argument
-- [ ] 2.3 Update `src/commands/spec.ts` `validate` subcommand to accept and resolve hierarchical spec IDs
-- [ ] 2.4 Update interactive selection prompts in `spec show` and `spec validate` to display hierarchical IDs
+- [x] 2.1 Update `src/commands/spec.ts` `show` subcommand to accept and resolve hierarchical spec IDs (e.g., `cli/show`)
+- [x] 2.2 Update `src/commands/spec.ts` `list` subcommand to display full hierarchical IDs and accept an optional subtree prefix argument
+- [x] 2.3 Update `src/commands/spec.ts` `validate` subcommand to accept and resolve hierarchical spec IDs
+- [x] 2.4 Update interactive selection prompts in `spec show` and `spec validate` to display hierarchical IDs
 
 ## 3. CLI Commands — Top-Level Show, Validate, List
 
-- [ ] 3.1 Update `src/commands/show.ts` type detection to resolve hierarchical spec IDs and include them in fuzzy-match suggestions
-- [ ] 3.2 Update `src/commands/validate.ts` type detection and bulk validation (`--all`, `--specs`) to use recursive spec discovery
-- [ ] 3.3 Update `src/core/list.ts` to use recursive spec discovery and support subtree filtering argument for `--specs`
-- [ ] 3.4 Update `src/core/view.ts` dashboard to display hierarchical spec IDs in the specifications section
+- [x] 3.1 Update `src/commands/show.ts` type detection to resolve hierarchical spec IDs and include them in fuzzy-match suggestions
+- [x] 3.2 Update `src/commands/validate.ts` type detection and bulk validation (`--all`, `--specs`) to use recursive spec discovery
+- [x] 3.3 Update `src/core/list.ts` to use recursive spec discovery and support subtree filtering argument for `--specs`
+- [x] 3.4 Update `src/core/view.ts` dashboard to display hierarchical spec IDs in the specifications section
 
 ## 4. Fuzzy Matching
 
-- [ ] 4.1 Extend `src/utils/match.ts` to support leaf-segment matching — when no exact match, search for specs whose last path segment matches the query
-- [ ] 4.2 Add tests for fuzzy matching with hierarchical IDs (full path typo, leaf match, multiple leaf matches)
+- [x] 4.1 Extend `src/utils/match.ts` to support leaf-segment matching — when no exact match, search for specs whose last path segment matches the query
+- [x] 4.2 Add tests for fuzzy matching with hierarchical IDs (full path typo, leaf match, multiple leaf matches)
 
 ## 5. Archive & Delta Spec Handling
 
-- [ ] 5.1 Update delta spec discovery in `src/core/archive.ts` / `src/core/specs-apply.ts` to recursively walk `changes/<name>/specs/` for delta specs at any depth
-- [ ] 5.2 Update archive confirmation display to show full hierarchical paths for new and updated specs
-- [ ] 5.3 Ensure archive creates intermediate directories when applying delta specs to new hierarchical paths
-- [ ] 5.4 Add tests for archiving changes with hierarchical delta specs
+- [x] 5.1 Update delta spec discovery in `src/core/archive.ts` / `src/core/specs-apply.ts` to recursively walk `changes/<name>/specs/` for delta specs at any depth
+- [x] 5.2 Update archive confirmation display to show full hierarchical paths for new and updated specs
+- [x] 5.3 Ensure archive creates intermediate directories when applying delta specs to new hierarchical paths
+- [x] 5.4 Add tests for archiving changes with hierarchical delta specs
 
 ## 6. Validation & Edge Cases
 
-- [ ] 6.1 Update `src/commands/validate.ts` error messages and file path references to include full hierarchical spec paths
-- [ ] 6.2 Update `src/core/validation/validator.ts` to handle hierarchical spec IDs in structured location paths
-- [ ] 6.3 Add integration tests: mixed flat + hierarchical specs coexisting, subtree listing, and cross-platform path handling
+- [x] 6.1 Update `src/commands/validate.ts` error messages and file path references to include full hierarchical spec paths
+- [x] 6.2 Update `src/core/validation/validator.ts` to handle hierarchical spec IDs in structured location paths
+- [x] 6.3 Add integration tests: mixed flat + hierarchical specs coexisting, subtree listing, and cross-platform path handling
 
 ## 7. Documentation & Cleanup
 
-- [ ] 7.1 Update `openspec/AGENTS.md` with examples of hierarchical spec paths in templates and references
-- [ ] 7.2 Update CLI help text for `spec list` to document subtree filtering syntax
+- [x] 7.1 Update `openspec/AGENTS.md` with examples of hierarchical spec paths in templates and references
+- [x] 7.2 Update CLI help text for `spec list` to document subtree filtering syntax

src/cli/index.ts

@@ -170,18 +170,18 @@ program
   });
 
 program
-  .command('list')
-  .description('List items (changes by default). Use --specs to list specs.')
+  .command('list [prefix]')
+  .description('List items (changes by default). Use --specs to list specs, optionally filtered by subtree prefix (e.g. "cli/" shows only specs under cli/).')
   .option('--specs', 'List specs instead of changes')
   .option('--changes', 'List changes explicitly (default)')
   .option('--sort <order>', 'Sort order: "recent" (default) or "name"', 'recent')
   .option('--json', 'Output as JSON (for programmatic use)')
-  .action(async (options?: { specs?: boolean; changes?: boolean; sort?: string; json?: boolean }) => {
+  .action(async (prefix?: string, options?: { specs?: boolean; changes?: boolean; sort?: string; json?: boolean }) => {
     try {
       const listCommand = new ListCommand();
       const mode: 'changes' | 'specs' = options?.specs ? 'specs' : 'changes';
       const sort = options?.sort === 'name' ? 'name' : 'recent';
-      await listCommand.execute('.', mode, { sort, json: options?.json });
+      await listCommand.execute('.', mode, { sort, json: options?.json, specsPrefix: prefix });
     } catch (error) {
       console.log(); // Empty line for spacing
       ora().fail(`Error: ${(error as Error).message}`);

src/commands/spec.ts

@@ -1,11 +1,11 @@
 import { program } from 'commander';
-import { existsSync, readdirSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
 import { MarkdownParser } from '../core/parsers/markdown-parser.js';
 import { Validator } from '../core/validation/validator.js';
 import type { Spec } from '../core/schemas/index.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';
+import { specIdToPath } from '../utils/spec-paths.js';
 
 const SPECS_DIR = 'openspec/specs';
 
@@ -82,7 +82,7 @@ export class SpecCommand {
       }
     }
 
-    const specPath = join(this.SPECS_DIR, specId, 'spec.md');
+    const specPath = specIdToPath(specId, this.SPECS_DIR);
     if (!existsSync(specPath)) {
       throw new Error(`Spec '${specId}' not found at openspec/specs/${specId}/spec.md`);
     }
@@ -137,42 +137,42 @@ export function registerSpecCommand(rootProgram: typeof program) {
     });
 
   specCommand
-    .command('list')
-    .description('List all available specifications')
+    .command('list [prefix]')
+    .description('List all available specifications. Optionally filter by subtree prefix (e.g. "cli/" lists only specs under cli/)')
+    .addHelpText('after', `
+Subtree filtering:
+  openspec spec list           List all specs
+  openspec spec list cli/      List only specs whose ID starts with "cli/" (segment boundary)
+                               Matches: cli/show, cli/validate
+                               Does not match: client/config
+
+Spec IDs use forward-slash separators (e.g. "cli/show", "domain/project/feature").
+The prefix must end with "/" or one is appended automatically.`)
     .option('--json', 'Output as JSON')
     .option('--long', 'Show id and title with counts')
-    .action((options: { json?: boolean; long?: boolean }) => {
+    .action(async (prefix: string | undefined, options: { json?: boolean; long?: boolean }) => {
       try {
-        if (!existsSync(SPECS_DIR)) {
-          console.log('No items found');
-          return;
+        let allIds = await getSpecIds();
+
+        if (prefix) {
+          // Segment-boundary filtering: prefix must end with "/" to denote a boundary.
+          // "cli/" matches "cli/foo" and "cli/bar/baz" but NOT "client/foo".
+          const normalizedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`;
+          allIds = allIds.filter(id => id.startsWith(normalizedPrefix));
         }
 
-        const specs = readdirSync(SPECS_DIR, { withFileTypes: true })
-          .filter(dirent => dirent.isDirectory())
-          .map(dirent => {
-            const specPath = join(SPECS_DIR, dirent.name, 'spec.md');
-            if (existsSync(specPath)) {
-              try {
-                const spec = parseSpecFromFile(specPath, dirent.name);
-                
-                return {
-                  id: dirent.name,
-                  title: spec.name,
-                  requirementCount: spec.requirements.length
-                };
-              } catch {
-                return {
-                  id: dirent.name,
-                  title: dirent.name,
-                  requirementCount: 0
-                };
-              }
+        const specs = allIds.map(id => {
+          const specPath = specIdToPath(id, SPECS_DIR);
+          if (existsSync(specPath)) {
+            try {
+              const spec = parseSpecFromFile(specPath, id);
+              return { id, title: spec.name, requirementCount: spec.requirements.length };
+            } catch {
+              return { id, title: id, requirementCount: 0 };
             }
-            return null;
-          })
-          .filter((spec): spec is { id: string; title: string; requirementCount: number } => spec !== null)
-          .sort((a, b) => a.id.localeCompare(b.id));
+          }
+          return null;
+        }).filter((spec): spec is { id: string; title: string; requirementCount: number } => spec !== null);
 
         if (options.json) {
           console.log(JSON.stringify(specs, null, 2));
@@ -217,8 +217,8 @@ export function registerSpecCommand(rootProgram: typeof program) {
           }
         }
 
-        const specPath = join(SPECS_DIR, specId, 'spec.md');
-        
+        const specPath = specIdToPath(specId, SPECS_DIR);
+
         if (!existsSync(specPath)) {
           throw new Error(`Spec '${specId}' not found at openspec/specs/${specId}/spec.md`);
         }