Merge branch 'main' into docs/experimental-workflow-guide

Adds documentation for the experimental artifact-based workflow:
- Setup instructions (Claude Code only for now)
- Command reference for all /opsx:* commands
- Usage examples and tips
- Comparison with standard workflow
- Feedback links to Discord and GitHub

docs/experimental-workflow.md

@@ -0,0 +1,107 @@
+# Experimental Workflow (OPSX)
+
+> **Status:** Experimental. Things might break. Feedback welcome on [Discord](https://discord.gg/BYjPaKbqMt).
+>
+> **Compatibility:** Claude Code only (for now)
+
+## What Is It?
+
+OPSX is a new way to work with OpenSpec changes. Instead of one big proposal, you build **artifacts** step-by-step:
+
+```
+proposal → specs → design → tasks → implementation → archive
+```
+
+Each artifact has dependencies. Can't write tasks until you have specs. Can't implement until you have tasks. The system tracks what's ready and what's blocked.
+
+## Setup
+
+```bash
+# 1. Make sure you have openspec installed and initialized
+openspec init
+
+# 2. Generate the experimental skills
+openspec artifact-experimental-setup
+```
+
+This creates skills in `.claude/skills/` that Claude Code auto-detects.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact |
+| `/opsx:ff` | Fast-forward (create all artifacts at once) |
+| `/opsx:apply` | Implement the tasks |
+| `/opsx:sync` | Sync delta specs to main specs |
+| `/opsx:archive` | Archive when done |
+
+## Usage
+
+### Start a new change
+```
+/opsx:new
+```
+You'll be asked what you want to build and which workflow schema to use.
+
+### Build artifacts step-by-step
+```
+/opsx:continue
+```
+Creates one artifact at a time. Good for reviewing each step.
+
+### Or fast-forward
+```
+/opsx:ff add-dark-mode
+```
+Creates all artifacts in one go. Good when you know what you want.
+
+### Implement
+```
+/opsx:apply
+```
+Works through tasks, checking them off as you go.
+
+### Sync specs and archive
+```
+/opsx:sync      # Update main specs with your delta specs
+/opsx:archive   # Move to archive when done
+```
+
+## What's Different?
+
+**Standard workflow** (`/openspec:proposal`):
+- One big proposal document
+- Linear phases: plan → implement → archive
+- All-or-nothing artifact creation
+
+**Experimental workflow** (`/opsx:*`):
+- Discrete artifacts with dependencies
+- Fluid actions (not phases) - update artifacts anytime
+- Step-by-step or fast-forward
+- Schema-driven (can customize the workflow)
+
+The key insight: work isn't linear. You implement, realize the design is wrong, update it, continue. OPSX supports this.
+
+## Schemas
+
+Schemas define what artifacts exist and their dependencies. Currently available:
+
+- **spec-driven** (default): proposal → specs → design → tasks
+- **tdd**: tests → implementation → docs
+
+Run `openspec schemas` to see available schemas.
+
+## Tips
+
+- Use `/opsx:ff` when you have a clear idea, `/opsx:continue` when exploring
+- Tasks track progress via checkboxes in `tasks.md`
+- Delta specs (in `specs/`) get synced to main specs with `/opsx:sync`
+- If you get stuck, the status command shows what's blocked: `openspec status --change "name"`
+
+## Feedback
+
+This is rough. That's intentional - we're learning what works.
+
+Found a bug? Have ideas? Join us on [Discord](https://discord.gg/BYjPaKbqMt) or open an issue on [GitHub](https://github.com/Fission-AI/openspec/issues).

openspec/changes/add-agent-schema-selection/tasks.md

@@ -1,32 +0,0 @@
-## Prerequisites
-
-- [ ] 0.1 Implement `add-per-change-schema-metadata` change first
-
-## 1. Schema Discovery
-
-- [ ] 1.1 Add CLI command or helper to list schemas with descriptions (for agent use)
-- [ ] 1.2 Ensure `openspec templates --schema <name>` returns artifact list for any schema
-
-## 2. Update New Change Skill
-
-- [ ] 2.1 Add schema selection prompt using AskUserQuestion tool
-- [ ] 2.2 Present available schemas with descriptions (spec-driven, tdd, etc.)
-- [ ] 2.3 Pass selected schema to `openspec new change --schema <name>`
-- [ ] 2.4 Update output to show which schema/workflow was selected
-
-## 3. Update Continue Change Skill
-
-- [ ] 3.1 Remove hardcoded artifact references (proposal, specs, design, tasks)
-- [ ] 3.2 Read artifact list dynamically from `openspec status --json`
-- [ ] 3.3 Adjust artifact creation guidelines to be schema-agnostic
-- [ ] 3.4 Handle schema-specific artifact types (e.g., TDD's `tests` artifact)
-
-## 4. Update Apply Change Skill
-
-- [ ] 4.1 Make task detection work with different schema structures
-- [ ] 4.2 Adjust context file reading for schema-specific artifacts
-
-## 5. Documentation
-
-- [ ] 5.1 Add schema descriptions to help text or skill instructions
-- [ ] 5.2 Document when to use each schema (TDD for bug fixes, spec-driven for features, etc.)

openspec/changes/add-scaffold-command/proposal.md

@@ -1,11 +0,0 @@
-## Why
-Manual setup for new changes leads to formatting mistakes in spec deltas and slows agents who must recreate the same file skeletons for every proposal. A built-in scaffold command will generate compliant templates so assistants can focus on the change content instead of structure.
-
-## What Changes
-- Add an `openspec scaffold <change-id>` CLI command that creates a change directory (if it does not already exist) with validated `proposal.md`, `tasks.md`, and spec delta templates.
-- Update CLI documentation and quick-reference guidance so agents discover the scaffold workflow before drafting files manually, including reminders on when to create spec deltas.
-- Add automated coverage (unit/integ tests) to ensure the command respects naming rules, copies templates correctly, fails for existing directories, and produces output that passes `openspec validate --strict` untouched.
-
-## Impact
-- Affected specs: `specs/cli-scaffold`
-- Affected code: `src/cli/index.ts`, `src/commands`, `docs/`

openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md

@@ -1,36 +0,0 @@
-## ADDED Requirements
-### Requirement: Scaffolding Command Registration
-The CLI SHALL expose an `openspec scaffold <change-id>` command that validates the change identifier before generating files.
-
-#### Scenario: Registering scaffold command
-- **WHEN** a user runs `openspec scaffold add-user-notifications`
-- **THEN** the CLI SHALL reject invalid identifiers (non kebab-case) before proceeding
-- **AND** display usage documentation via `openspec scaffold --help`
-- **AND** exit with code 0 after successful scaffolding
-
-### Requirement: Change Directory Structure
-The scaffold command SHALL create the standard change workspace (if it does not already exist) with proposal, tasks, optional design, and `specs/` directories laid out according to OpenSpec conventions.
-
-#### Scenario: Generating change workspace
-- **WHEN** scaffolding a new change with id `add-user-notifications`
-- **THEN** create `openspec/changes/add-user-notifications/` if it does not exist
-- **AND** copy the default template bundle (proposal, tasks, design placeholders) into that directory in a single operation
-- **AND** create an empty `openspec/changes/add-user-notifications/specs/` directory ready for capability-specific deltas that will be authored later
-
-### Requirement: Template Content Guidance
-The scaffold command SHALL populate generated Markdown files with OpenSpec-compliant templates so authors can copy, edit, and pass validation without reformatting.
-
-#### Scenario: Populating proposal and tasks templates
-- **WHEN** the scaffold command writes `proposal.md`
-- **THEN** include the `## Why`, `## What Changes`, and `## Impact` headings with placeholder guidance text
-- **AND** ensure `tasks.md` starts with `## 1. Implementation` and numbered checklist items using `- [ ]` syntax
-- **AND** annotate optional sections (like `design.md`) with inline TODO comments so users understand when to keep or delete them
-- **AND** include a short reminder inside `specs/README.md` (or similar) instructing authors to add deltas once they know the affected capability
-
-### Requirement: Idempotent Execution
-The scaffold command SHALL be safe to rerun, preserving user edits while filling in any missing managed sections.
-
-#### Scenario: Rerunning scaffold on existing change
-- **WHEN** the command is executed again for an existing change directory containing user-edited files
-- **THEN** leave existing content untouched except for managed placeholder regions or missing files that need creation
-- **AND** update the filesystem summary to highlight which files were skipped, created, or refreshed

openspec/changes/add-scaffold-command/tasks.md

@@ -1,12 +0,0 @@
-## 1. CLI scaffolding command
-- [ ] 1.1 Register an `openspec scaffold` command in the CLI entrypoint with `change-id` argument validation.
-- [ ] 1.2 Implement generator logic that copies the default change template bundle (`proposal.md`, `tasks.md`, optional `design.md`, `specs/README.md`) into `openspec/changes/<id>/`, creating the directory tree in a single pass.
-- [ ] 1.3 Detect when `openspec/changes/<id>/` already exists and exit with a clear error instead of overwriting user files.
-
-## 2. Templates and documentation
-- [ ] 2.1 Update `openspec/AGENTS.md` quick reference so agents see `openspec scaffold` before drafting files manually.
-- [ ] 2.2 Refresh CLI docs/README/help text to mention the scaffold workflow, template bundle contents, and when to add spec deltas manually.
-
-## 3. Test coverage
-- [ ] 3.1 Add unit tests covering name validation, template copying, and existing-directory failures.
-- [ ] 3.2 Add integration coverage ensuring a freshly scaffolded change (without deltas) passes `openspec validate --strict` until the author customizes it.

openspec/changes/archive/2026-01-06-add-agent-schema-selection/tasks.md

@@ -0,0 +1,32 @@
+## Prerequisites
+
+- [x] 0.1 Implement `add-per-change-schema-metadata` change first
+
+## 1. Schema Discovery
+
+- [x] 1.1 Add CLI command or helper to list schemas with descriptions (for agent use)
+- [x] 1.2 Ensure `openspec templates --schema <name>` returns artifact list for any schema
+
+## 2. Update New Change Skill
+
+- [x] 2.1 Add schema selection prompt using AskUserQuestion tool
+- [x] 2.2 Present available schemas with descriptions (spec-driven, tdd, etc.)
+- [x] 2.3 Pass selected schema to `openspec new change --schema <name>`
+- [x] 2.4 Update output to show which schema/workflow was selected
+
+## 3. Update Continue Change Skill
+
+- [x] 3.1 Remove hardcoded artifact references (proposal, specs, design, tasks)
+- [x] 3.2 Read artifact list dynamically from `openspec status --json`
+- [x] 3.3 Adjust artifact creation guidelines to be schema-agnostic
+- [x] 3.4 Handle schema-specific artifact types (e.g., TDD's `tests` artifact)
+
+## 4. Update Apply Change Skill
+
+- [x] 4.1 Make task detection work with different schema structures
+- [x] 4.2 Adjust context file reading for schema-specific artifacts
+
+## 5. Documentation
+
+- [x] 5.1 Add schema descriptions to help text or skill instructions
+- [x] 5.2 Document when to use each schema (TDD for bug fixes, spec-driven for features, etc.)

openspec/changes/archive/2026-01-06-add-specs-apply-command/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-06

openspec/changes/archive/2026-01-06-add-specs-apply-command/design.md

@@ -0,0 +1,77 @@
+## Context
+
+Currently, delta specs are only applied to main specs when running `openspec archive`. This bundles two concerns:
+1. Applying spec changes (delta → main)
+2. Archiving the change (move to archive folder)
+
+Users want flexibility to sync specs earlier, especially when iterating. The archive command already contains the reconciliation logic in `buildUpdatedSpec()`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Decouple spec syncing from archiving
+- Provide `/opsx:sync` skill for agents to sync specs on demand
+- Keep operation idempotent (safe to run multiple times)
+
+**Non-Goals:**
+- Tracking whether specs have been synced (no state)
+- Changing archive behavior (it will continue to apply specs)
+- Supporting partial application (all deltas sync together)
+
+## Decisions
+
+### 1. Reuse existing reconciliation logic
+
+**Decision**: Extract `buildUpdatedSpec()` logic from `ArchiveCommand` into a shared module.
+
+**Rationale**: The archive command already implements delta parsing and application. Rather than duplicate, we extract and reuse.
+
+**Alternatives considered**:
+- Duplicate logic in new command (rejected: maintenance burden)
+- Have sync call archive with flags (rejected: coupling)
+
+### 2. No state tracking
+
+**Decision**: Don't track whether specs have been synced. Each invocation reads delta and main specs, reconciles.
+
+**Rationale**:
+- Idempotent operations don't need state
+- Avoids sync issues between flag and reality
+- Simpler implementation and mental model
+
+**Alternatives considered**:
+- Track `specsSynced: true` in `.openspec.yaml` (rejected: unnecessary complexity)
+- Store snapshot of synced deltas (rejected: over-engineering)
+
+### 3. Agent-driven approach (no CLI command)
+
+**Decision**: The `/opsx:sync` skill is fully agent-driven - the agent reads delta specs and directly edits main specs.
+
+**Rationale**:
+- Allows intelligent merging (add scenarios without copying entire requirements)
+- Delta represents *intent*, not wholesale replacement
+- More flexible and natural editing workflow
+- Archive still uses programmatic merge (for finalized changes)
+
+### 4. Archive behavior unchanged
+
+**Decision**: Archive continues to apply specs as part of its flow. If specs are already reconciled, the operation is a no-op.
+
+**Rationale**: Backward compatibility. Users who don't use `/opsx:sync` get the same experience.
+
+## Risks / Trade-offs
+
+**[Risk] Multiple changes modify same spec**
+→ Last to sync wins. Same as today with archive. Users should coordinate or use sequential archives.
+
+**[Risk] User syncs specs then continues editing deltas**
+→ Running `/opsx:sync` again reconciles. Idempotent design handles this.
+
+**[Trade-off] No undo mechanism**
+→ Users can `git checkout` main specs if needed. Explicit undo command is out of scope.
+
+## Implementation Approach
+
+1. Extract spec application logic from `ArchiveCommand.buildUpdatedSpec()` into `src/core/specs-apply.ts`
+2. Add skill template for `/opsx:sync` in `skill-templates.ts`
+3. Register skill in managed skills

openspec/changes/archive/2026-01-06-add-specs-apply-command/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+Spec application is currently bundled with archive - users must run `openspec archive` to apply delta specs to main specs. This couples two distinct concerns (applying specs vs. archiving the change) and forces users to wait until they're "done" to see main specs updated. Users want the flexibility to sync specs earlier in the workflow while iterating.
+
+## What Changes
+
+- Add `/opsx:sync` skill that syncs delta specs to main specs as a standalone action
+- The operation is idempotent - safe to run multiple times, agent reconciles main specs to match deltas
+- Archive continues to work as today (applies specs if not already reconciled, then moves to archive)
+- No new state tracking - the agent reads delta and main specs, reconciles on each run
+- Agent-driven approach allows intelligent merging (partial updates, adding scenarios)
+
+**Workflow becomes:**
+```
+/opsx:new → /opsx:continue → /opsx:apply → archive
+                                  │
+                                  └── /opsx:sync (optional, anytime)
+```
+
+## Capabilities
+
+### New Capabilities
+- `specs-sync-skill`: Skill template for `/opsx:sync` command that reconciles main specs with delta specs
+
+### Modified Capabilities
+- None (agent-driven, no CLI command needed)
+
+## Impact
+
+- **Skills**: New `openspec-sync-specs` skill in `skill-templates.ts`
+- **Archive**: No changes needed - already does reconciliation, will continue to work
+- **Agent workflow**: Users gain flexibility to sync specs before archive

openspec/changes/archive/2026-01-06-add-specs-apply-command/specs/specs-sync-skill/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: Specs Sync Skill
+The system SHALL provide an `/opsx:sync` skill that syncs delta specs from a change to the main specs.
+
+#### Scenario: Sync delta specs to main specs
+- **WHEN** agent executes `/opsx:sync` with a change name
+- **THEN** the agent reads delta specs from `openspec/changes/<name>/specs/`
+- **AND** reads corresponding main specs from `openspec/specs/`
+- **AND** reconciles main specs to match what the deltas describe
+
+#### Scenario: Idempotent operation
+- **WHEN** agent executes `/opsx:sync` multiple times on the same change
+- **THEN** the result is the same as running it once
+- **AND** no duplicate requirements are created
+
+#### Scenario: Change selection prompt
+- **WHEN** agent executes `/opsx:sync` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows changes that have delta specs
+
+### Requirement: Delta Reconciliation Logic
+The agent SHALL reconcile main specs with delta specs using the delta operation headers.
+
+#### Scenario: ADDED requirements
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** the requirement does not exist in main spec
+- **THEN** add the requirement to main spec
+
+#### Scenario: ADDED requirement already exists
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** a requirement with the same name already exists in main spec
+- **THEN** update the existing requirement to match the delta version
+
+#### Scenario: MODIFIED requirements
+- **WHEN** delta contains `## MODIFIED Requirements` with a requirement
+- **AND** the requirement exists in main spec
+- **THEN** replace the requirement in main spec with the delta version
+
+#### Scenario: REMOVED requirements
+- **WHEN** delta contains `## REMOVED Requirements` with a requirement name
+- **AND** the requirement exists in main spec
+- **THEN** remove the requirement from main spec
+
+#### Scenario: RENAMED requirements
+- **WHEN** delta contains `## RENAMED Requirements` with FROM:/TO: format
+- **AND** the FROM requirement exists in main spec
+- **THEN** rename the requirement to the TO name
+
+#### Scenario: New capability spec
+- **WHEN** delta spec exists for a capability not in main specs
+- **THEN** create new main spec file at `openspec/specs/<capability>/spec.md`
+
+### Requirement: Skill Output
+The skill SHALL provide clear feedback on what was synced.
+
+#### Scenario: Show synced changes
+- **WHEN** reconciliation completes successfully
+- **THEN** display summary of changes per capability:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+
+#### Scenario: No changes needed
+- **WHEN** main specs already match delta specs
+- **THEN** display "Specs already in sync - no changes needed"

openspec/changes/archive/2026-01-06-add-specs-apply-command/tasks.md

@@ -0,0 +1,40 @@
+## Tasks
+
+### Core Implementation
+
+- [x] Extract spec application logic from `ArchiveCommand` into `src/core/specs-apply.ts`
+  - Move `buildUpdatedSpec()`, `findSpecUpdates()`, `writeUpdatedSpec()` to shared module
+  - Keep `ArchiveCommand` importing from the new module
+  - Ensure all validation logic is preserved
+
+### Skill Template
+
+- [x] Add `getSyncSpecsSkillTemplate()` function in `src/core/templates/skill-templates.ts`
+  - Skill name: `openspec-sync-specs`
+  - Description: Sync delta specs to main specs
+  - **Agent-driven**: Instructions for agent to read deltas and edit main specs directly
+
+- [x] Add `/opsx:sync` slash command template in `skill-templates.ts`
+  - Mirror the skill template for slash command format
+  - **Agent-driven**: No CLI command, agent does the merge
+
+### Registration
+
+- [x] Register skill in managed skills (via `artifact-experimental-setup`)
+  - Add to skill list with appropriate metadata
+  - Ensure it appears in setup output
+
+### Design Decision
+
+**Why agent-driven instead of CLI-driven?**
+
+The programmatic merge operates at requirement-level granularity:
+- MODIFIED requires copying ALL scenarios, not just the changed ones
+- If agent forgets a scenario, it gets deleted
+- Delta specs become bloated with copied content
+
+Agent-driven approach:
+- Agent can apply partial updates (add a scenario without copying others)
+- Delta represents *intent*, not wholesale replacement
+- More flexible and natural editing workflow
+- Archive still uses programmatic merge (for finalized changes)

openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,60 @@
+## ADDED Requirements
+
+### Requirement: Schema Apply Block
+
+The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
+
+#### Scenario: Schema with apply block
+
+- **WHEN** a schema defines an `apply` block
+- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
+- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
+- **AND** uses `apply.instruction` for guidance shown to the agent
+
+#### Scenario: Schema without apply block
+
+- **WHEN** a schema has no `apply` block
+- **THEN** the system requires all artifacts to exist before apply is available
+- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
+
+### Requirement: Apply Instructions Command
+
+The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
+
+#### Scenario: Generate apply instructions
+
+- **WHEN** user runs `openspec instructions apply --change <id>`
+- **AND** all required artifacts (per schema's `apply.requires`) exist
+- **THEN** the system outputs:
+  - Context files from all existing artifacts
+  - Schema-specific instruction text
+  - Progress tracking file path (if `apply.tracks` is set)
+
+#### Scenario: Apply blocked by missing artifacts
+
+- **WHEN** user runs `openspec instructions apply --change <id>`
+- **AND** required artifacts are missing
+- **THEN** the system indicates apply is blocked
+- **AND** lists which artifacts must be created first
+
+#### Scenario: Apply instructions JSON output
+
+- **WHEN** user runs `openspec instructions apply --change <id> --json`
+- **THEN** the system outputs JSON with:
+  - `contextFiles`: array of paths to existing artifacts
+  - `instruction`: the apply instruction text
+  - `tracks`: path to progress file or null
+  - `applyRequires`: list of required artifact IDs
+
+## MODIFIED Requirements
+
+### Requirement: Status Command
+
+The system SHALL display artifact completion status for a change, including apply readiness.
+
+#### Scenario: Status JSON includes apply requirements
+
+- **WHEN** user runs `openspec status --change <id> --json`
+- **THEN** the system outputs JSON with:
+  - `changeName`, `schemaName`, `isComplete`, `artifacts` array
+  - `applyRequires`: array of artifact IDs needed for apply phase

openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md

@@ -0,0 +1,35 @@
+## Prerequisites
+
+- [x] 0.1 Implement `add-per-change-schema-metadata` first (to auto-detect schema)
+
+## 1. Schema Format
+
+- [x] 1.1 Add `ApplyPhaseSchema` Zod schema to `src/core/artifact-graph/types.ts`
+- [x] 1.2 Update `SchemaYamlSchema` to include optional `apply` field
+- [x] 1.3 Export `ApplyPhase` type
+
+## 2. Update Existing Schemas
+
+- [x] 2.1 Add `apply` block to `schemas/spec-driven/schema.yaml`
+- [x] 2.2 Add `apply` block to `schemas/tdd/schema.yaml`
+
+## 3. Refactor generateApplyInstructions
+
+- [x] 3.1 Load schema via `resolveSchema(schemaName)`
+- [x] 3.2 Read `apply.requires` to determine required artifacts
+- [x] 3.3 Check artifact existence dynamically (not hardcoded paths)
+- [x] 3.4 Use `apply.tracks` for progress tracking (or skip if null)
+- [x] 3.5 Use `apply.instruction` for the instruction text
+- [x] 3.6 Build `contextFiles` from all existing artifacts in schema
+
+## 4. Handle Fallback
+
+- [x] 4.1 If schema has no `apply` block, require all artifacts to exist
+- [x] 4.2 Default instruction: "All artifacts complete. Proceed with implementation."
+
+## 5. Tests
+
+- [x] 5.1 Test apply instructions with spec-driven schema
+- [x] 5.2 Test apply instructions with tdd schema
+- [x] 5.3 Test fallback when schema has no apply block
+- [x] 5.4 Test blocked state when required artifacts missing

openspec/changes/archive/2026-01-06-opsx-archive-command/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-07

openspec/changes/archive/2026-01-06-opsx-archive-command/design.md

@@ -0,0 +1,84 @@
+## Context
+
+The experimental workflow (OPSX) provides a complete lifecycle for creating changes:
+- `/opsx:new` - Scaffold a new change with schema
+- `/opsx:continue` - Create next artifact
+- `/opsx:ff` - Fast-forward all artifacts
+- `/opsx:apply` - Implement tasks
+- `/opsx:sync` - Sync delta specs to main
+
+The missing piece is archiving. The existing `openspec archive` command works but:
+1. Applies specs programmatically (not agent-driven)
+2. Doesn't use the artifact graph for completion checking
+3. Doesn't integrate with the OPSX workflow philosophy
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add `/opsx:archive` skill to complete the OPSX workflow lifecycle
+- Use artifact graph for schema-aware completion checking
+- Integrate with `/opsx:sync` for agent-driven spec syncing
+- Preserve `.openspec.yaml` schema metadata in archive
+
+**Non-Goals:**
+- Replacing the existing `openspec archive` CLI command
+- Changing how specs are applied in the CLI command
+- Modifying the artifact graph or schema system
+
+## Decisions
+
+### Decision 1: Skill-only implementation (no new CLI command)
+
+The `/opsx:archive` will be a slash command/skill only, not a new CLI command.
+
+**Rationale**: The existing `openspec archive` CLI command already handles the core archive functionality (moving to archive folder, date prefixing). The OPSX version just needs different pre-archive checks and optional sync prompting, which are agent behaviors better suited to a skill.
+
+**Alternatives considered**:
+- Adding flags to `openspec archive` (e.g., `--experimental`) - Rejected: adds complexity to CLI, harder to maintain two code paths
+- New CLI command `openspec archive-experimental` - Rejected: unnecessary duplication, agent skills are the OPSX pattern
+
+### Decision 2: Prompt for sync before archive
+
+The skill will check for unsynced delta specs and prompt the user before archiving.
+
+**Rationale**: The OPSX philosophy is agent-driven intelligent merging via `/opsx:sync`. Rather than programmatically applying specs like the regular archive command, we prompt the user to sync first if needed. This maintains workflow flexibility (user can decline and just archive).
+
+**Flow**:
+1. Check if `specs/` directory exists in the change
+2. If yes, ask: "This change has delta specs. Would you like to sync them to main specs before archiving?"
+3. If user says yes, execute `/opsx:sync` logic
+4. Proceed with archive regardless of answer
+
+### Decision 3: Use artifact graph for completion checking
+
+The skill will use `openspec status --change "<name>" --json` to check artifact completion instead of just validating proposal.md and specs.
+
+**Rationale**: The experimental workflow is schema-aware. Different schemas have different required artifacts. The artifact graph knows which artifacts are complete/incomplete for the current schema.
+
+**Behavior**:
+- Show warning if any artifacts are not `done`
+- Don't block archive (user may have valid reasons to archive early)
+- List incomplete artifacts so user can make informed decision
+
+### Decision 4: Reuse tasks.md completion check from regular archive
+
+The skill will parse tasks.md and warn about incomplete tasks, same as regular archive.
+
+**Rationale**: Task completion checking is valuable regardless of workflow. The logic is simple (count `- [ ]` vs `- [x]`) and doesn't need special OPSX handling.
+
+### Decision 5: Move change to archive/ with date prefix
+
+Same archive behavior as regular command: move to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+**Rationale**: Consistency with existing archive convention. The `.openspec.yaml` file moves with the change, preserving schema metadata.
+
+## Risks / Trade-offs
+
+**Risk**: Users confused about when to use `/opsx:archive` vs `openspec archive`
+→ **Mitigation**: Documentation should clarify: use `/opsx:archive` if you've been using the OPSX workflow, use `openspec archive` otherwise. Both produce the same archived result.
+
+**Risk**: Incomplete sync if user declines and has delta specs
+→ **Mitigation**: The prompt is informational; user has full control. They may want to archive without syncing (e.g., abandoned change). Log a note in output.
+
+**Trade-off**: No programmatic spec application in OPSX archive
+→ **Accepted**: This is intentional. OPSX philosophy is agent-driven merging. If user wants programmatic application, use `openspec archive` instead.

openspec/changes/archive/2026-01-06-opsx-archive-command/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The experimental workflow (OPSX) provides a schema-driven, artifact-by-artifact approach to creating changes with `/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:apply`, and `/opsx:sync`. However, there's no corresponding archive command to finalize and archive completed changes. Users must currently fall back to the regular `openspec archive` command, which doesn't integrate with the OPSX philosophy of agent-driven spec syncing and schema-aware artifact tracking.
+
+## What Changes
+
+- Add `/opsx:archive` slash command for archiving changes in the experimental workflow
+- Use artifact graph to check completion status (schema-aware) instead of just validating proposal + specs
+- Prompt for `/opsx:sync` before archiving instead of programmatically applying specs
+- Preserve `.openspec.yaml` schema metadata when moving to archive
+- Integrate with existing OPSX commands for a cohesive workflow
+
+## Capabilities
+
+### New Capabilities
+
+- `opsx-archive-skill`: Slash command and skill for archiving completed changes in the experimental workflow. Checks artifact completion via artifact graph, verifies task completion, optionally syncs specs via `/opsx:sync`, and moves the change to `archive/YYYY-MM-DD-<name>/`.
+
+### Modified Capabilities
+
+(none - this is a new skill that doesn't modify existing specs)
+
+## Impact
+
+- New file: `.claude/commands/opsx/archive.md`
+- New skill definition (generated via `openspec artifact-experimental-setup`)
+- No changes to existing archive command or other OPSX commands
+- Completes the OPSX command suite for full lifecycle management

openspec/changes/archive/2026-01-06-opsx-archive-command/specs/opsx-archive-skill/spec.md

@@ -0,0 +1,122 @@
+## ADDED Requirements
+
+### Requirement: OPSX Archive Skill
+
+The system SHALL provide an `/opsx:archive` skill that archives completed changes in the experimental workflow.
+
+#### Scenario: Archive a change with all artifacts complete
+
+- **WHEN** agent executes `/opsx:archive` with a change name
+- **AND** all artifacts in the schema are complete
+- **AND** all tasks are complete
+- **THEN** the agent moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+- **AND** displays success message with archived location
+
+#### Scenario: Change selection prompt
+
+- **WHEN** agent executes `/opsx:archive` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows only active changes (excludes archive/)
+
+### Requirement: Artifact Completion Check
+
+The skill SHALL check artifact completion status using the artifact graph before archiving.
+
+#### Scenario: Incomplete artifacts warning
+
+- **WHEN** agent checks artifact status
+- **AND** one or more artifacts have status other than `done`
+- **THEN** display warning listing incomplete artifacts
+- **AND** prompt user for confirmation to continue
+- **AND** proceed if user confirms
+
+#### Scenario: All artifacts complete
+
+- **WHEN** agent checks artifact status
+- **AND** all artifacts have status `done`
+- **THEN** proceed without warning
+
+### Requirement: Task Completion Check
+
+The skill SHALL check task completion status from tasks.md before archiving.
+
+#### Scenario: Incomplete tasks found
+
+- **WHEN** agent reads tasks.md
+- **AND** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display warning showing count of incomplete tasks
+- **AND** prompt user for confirmation to continue
+- **AND** proceed if user confirms
+
+#### Scenario: All tasks complete
+
+- **WHEN** agent reads tasks.md
+- **AND** all tasks are complete (marked with `- [x]`)
+- **THEN** proceed without task-related warning
+
+#### Scenario: No tasks file
+
+- **WHEN** tasks.md does not exist
+- **THEN** proceed without task-related warning
+
+### Requirement: Spec Sync Prompt
+
+The skill SHALL prompt to sync delta specs before archiving if specs exist.
+
+#### Scenario: Delta specs exist
+
+- **WHEN** agent checks for delta specs
+- **AND** `specs/` directory exists in the change with spec files
+- **THEN** prompt user: "This change has delta specs. Would you like to sync them to main specs before archiving?"
+- **AND** if user confirms, execute `/opsx:sync` logic
+- **AND** proceed with archive regardless of sync choice
+
+#### Scenario: No delta specs
+
+- **WHEN** agent checks for delta specs
+- **AND** no `specs/` directory or no spec files exist
+- **THEN** proceed without sync prompt
+
+### Requirement: Archive Process
+
+The skill SHALL move the change to the archive folder with date prefix.
+
+#### Scenario: Successful archive
+
+- **WHEN** archiving a change
+- **THEN** create `archive/` directory if it doesn't exist
+- **AND** generate target name as `YYYY-MM-DD-<change-name>` using current date
+- **AND** move entire change directory to archive location
+- **AND** preserve `.openspec.yaml` file in archived change
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive directory already exists
+- **THEN** fail with error message
+- **AND** suggest renaming existing archive or using different date
+
+### Requirement: Skill Output
+
+The skill SHALL provide clear feedback about the archive operation.
+
+#### Scenario: Archive complete with sync
+
+- **WHEN** archive completes after syncing specs
+- **THEN** display summary:
+  - Specs synced (from `/opsx:sync` output)
+  - Change archived to location
+  - Schema that was used
+
+#### Scenario: Archive complete without sync
+
+- **WHEN** archive completes without syncing specs
+- **THEN** display summary:
+  - Note that specs were not synced (if applicable)
+  - Change archived to location
+  - Schema that was used
+
+#### Scenario: Archive complete with warnings
+
+- **WHEN** archive completes with incomplete artifacts or tasks
+- **THEN** include note about what was incomplete
+- **AND** suggest reviewing if archive was intentional

openspec/changes/archive/2026-01-06-opsx-archive-command/tasks.md

@@ -0,0 +1,23 @@
+## 1. Create Slash Command
+
+- [x] 1.1 Create `.claude/commands/opsx/archive.md` with skill definition
+- [x] 1.2 Add YAML frontmatter (name, description, category, tags)
+- [x] 1.3 Implement change selection logic (prompt if not provided)
+- [x] 1.4 Implement artifact completion check using `openspec status --json`
+- [x] 1.5 Implement task completion check (parse tasks.md for `- [ ]`)
+- [x] 1.6 Implement spec sync prompt (check for specs/ directory, offer `/opsx:sync`)
+- [x] 1.7 Implement archive process (move to archive/YYYY-MM-DD-<name>/)
+- [x] 1.8 Add output formatting for success/warning cases
+
+## 2. Regenerate Skills
+
+- [x] 2.1 Run `openspec artifact-experimental-setup` to regenerate skills
+- [x] 2.2 Verify skill appears in `.claude/skills/` directory
+
+## 3. Testing
+
+- [x] 3.1 Test `/opsx:archive` with a complete change (all artifacts, all tasks done)
+- [x] 3.2 Test `/opsx:archive` with incomplete artifacts (verify warning shown)
+- [x] 3.3 Test `/opsx:archive` with incomplete tasks (verify warning shown)
+- [x] 3.4 Test `/opsx:archive` with delta specs (verify sync prompt shown)
+- [x] 3.5 Test `/opsx:archive` without change name (verify selection prompt)

openspec/changes/make-apply-instructions-schema-aware/tasks.md

@@ -1,35 +0,0 @@
-## Prerequisites
-
-- [ ] 0.1 Implement `add-per-change-schema-metadata` first (to auto-detect schema)
-
-## 1. Schema Format
-
-- [ ] 1.1 Add `ApplyPhaseSchema` Zod schema to `src/core/artifact-graph/types.ts`
-- [ ] 1.2 Update `SchemaYamlSchema` to include optional `apply` field
-- [ ] 1.3 Export `ApplyPhase` type
-
-## 2. Update Existing Schemas
-
-- [ ] 2.1 Add `apply` block to `schemas/spec-driven/schema.yaml`
-- [ ] 2.2 Add `apply` block to `schemas/tdd/schema.yaml`
-
-## 3. Refactor generateApplyInstructions
-
-- [ ] 3.1 Load schema via `resolveSchema(schemaName)`
-- [ ] 3.2 Read `apply.requires` to determine required artifacts
-- [ ] 3.3 Check artifact existence dynamically (not hardcoded paths)
-- [ ] 3.4 Use `apply.tracks` for progress tracking (or skip if null)
-- [ ] 3.5 Use `apply.instruction` for the instruction text
-- [ ] 3.6 Build `contextFiles` from all existing artifacts in schema
-
-## 4. Handle Fallback
-
-- [ ] 4.1 If schema has no `apply` block, require all artifacts to exist
-- [ ] 4.2 Default instruction: "All artifacts complete. Proceed with implementation."
-
-## 5. Tests
-
-- [ ] 5.1 Test apply instructions with spec-driven schema
-- [ ] 5.2 Test apply instructions with tdd schema
-- [ ] 5.3 Test fallback when schema has no apply block
-- [ ] 5.4 Test blocked state when required artifacts missing

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

@@ -1,12 +0,0 @@
-## 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

@@ -1,25 +0,0 @@
-## 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

@@ -1,16 +0,0 @@
-## 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-artifact-workflow/spec.md

@@ -27,6 +27,13 @@ The system SHALL display artifact completion status for a change, including scaf
 - **WHEN** user runs `openspec status --change <id> --json`
 - **THEN** the system outputs JSON with changeName, schemaName, isComplete, and artifacts array
 
+#### Scenario: Status JSON includes apply requirements
+
+- **WHEN** user runs `openspec status --change <id> --json`
+- **THEN** the system outputs JSON with:
+  - `changeName`, `schemaName`, `isComplete`, `artifacts` array
+  - `applyRequires`: array of artifact IDs needed for apply phase
+
 #### Scenario: Status on scaffolded change
 
 - **WHEN** user runs `openspec status --change <id>` on a change with no artifacts
@@ -159,6 +166,52 @@ The system SHALL implement artifact workflow commands in isolation for easy remo
 - **WHEN** user runs `--help` on any artifact workflow command
 - **THEN** help text indicates the command is experimental
 
+### Requirement: Schema Apply Block
+
+The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
+
+#### Scenario: Schema with apply block
+
+- **WHEN** a schema defines an `apply` block
+- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
+- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
+- **AND** uses `apply.instruction` for guidance shown to the agent
+
+#### Scenario: Schema without apply block
+
+- **WHEN** a schema has no `apply` block
+- **THEN** the system requires all artifacts to exist before apply is available
+- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
+
+### Requirement: Apply Instructions Command
+
+The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
+
+#### Scenario: Generate apply instructions
+
+- **WHEN** user runs `openspec instructions apply --change <id>`
+- **AND** all required artifacts (per schema's `apply.requires`) exist
+- **THEN** the system outputs:
+  - Context files from all existing artifacts
+  - Schema-specific instruction text
+  - Progress tracking file path (if `apply.tracks` is set)
+
+#### Scenario: Apply blocked by missing artifacts
+
+- **WHEN** user runs `openspec instructions apply --change <id>`
+- **AND** required artifacts are missing
+- **THEN** the system indicates apply is blocked
+- **AND** lists which artifacts must be created first
+
+#### Scenario: Apply instructions JSON output
+
+- **WHEN** user runs `openspec instructions apply --change <id> --json`
+- **THEN** the system outputs JSON with:
+  - `contextFiles`: array of paths to existing artifacts
+  - `instruction`: the apply instruction text
+  - `tracks`: path to progress file or null
+  - `applyRequires`: list of required artifact IDs
+
 ## REMOVED Requirements
 
 ### Requirement: Next Command

openspec/specs/opsx-archive-skill/spec.md

@@ -0,0 +1,122 @@
+# OPSX Archive Skill Spec
+
+### Requirement: OPSX Archive Skill
+
+The system SHALL provide an `/opsx:archive` skill that archives completed changes in the experimental workflow.
+
+#### Scenario: Archive a change with all artifacts complete
+
+- **WHEN** agent executes `/opsx:archive` with a change name
+- **AND** all artifacts in the schema are complete
+- **AND** all tasks are complete
+- **THEN** the agent moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+- **AND** displays success message with archived location
+
+#### Scenario: Change selection prompt
+
+- **WHEN** agent executes `/opsx:archive` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows only active changes (excludes archive/)
+
+### Requirement: Artifact Completion Check
+
+The skill SHALL check artifact completion status using the artifact graph before archiving.
+
+#### Scenario: Incomplete artifacts warning
+
+- **WHEN** agent checks artifact status
+- **AND** one or more artifacts have status other than `done`
+- **THEN** display warning listing incomplete artifacts
+- **AND** prompt user for confirmation to continue
+- **AND** proceed if user confirms
+
+#### Scenario: All artifacts complete
+
+- **WHEN** agent checks artifact status
+- **AND** all artifacts have status `done`
+- **THEN** proceed without warning
+
+### Requirement: Task Completion Check
+
+The skill SHALL check task completion status from tasks.md before archiving.
+
+#### Scenario: Incomplete tasks found
+
+- **WHEN** agent reads tasks.md
+- **AND** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display warning showing count of incomplete tasks
+- **AND** prompt user for confirmation to continue
+- **AND** proceed if user confirms
+
+#### Scenario: All tasks complete
+
+- **WHEN** agent reads tasks.md
+- **AND** all tasks are complete (marked with `- [x]`)
+- **THEN** proceed without task-related warning
+
+#### Scenario: No tasks file
+
+- **WHEN** tasks.md does not exist
+- **THEN** proceed without task-related warning
+
+### Requirement: Spec Sync Prompt
+
+The skill SHALL prompt to sync delta specs before archiving if specs exist.
+
+#### Scenario: Delta specs exist
+
+- **WHEN** agent checks for delta specs
+- **AND** `specs/` directory exists in the change with spec files
+- **THEN** prompt user: "This change has delta specs. Would you like to sync them to main specs before archiving?"
+- **AND** if user confirms, execute `/opsx:sync` logic
+- **AND** proceed with archive regardless of sync choice
+
+#### Scenario: No delta specs
+
+- **WHEN** agent checks for delta specs
+- **AND** no `specs/` directory or no spec files exist
+- **THEN** proceed without sync prompt
+
+### Requirement: Archive Process
+
+The skill SHALL move the change to the archive folder with date prefix.
+
+#### Scenario: Successful archive
+
+- **WHEN** archiving a change
+- **THEN** create `archive/` directory if it doesn't exist
+- **AND** generate target name as `YYYY-MM-DD-<change-name>` using current date
+- **AND** move entire change directory to archive location
+- **AND** preserve `.openspec.yaml` file in archived change
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive directory already exists
+- **THEN** fail with error message
+- **AND** suggest renaming existing archive or using different date
+
+### Requirement: Skill Output
+
+The skill SHALL provide clear feedback about the archive operation.
+
+#### Scenario: Archive complete with sync
+
+- **WHEN** archive completes after syncing specs
+- **THEN** display summary:
+  - Specs synced (from `/opsx:sync` output)
+  - Change archived to location
+  - Schema that was used
+
+#### Scenario: Archive complete without sync
+
+- **WHEN** archive completes without syncing specs
+- **THEN** display summary:
+  - Note that specs were not synced (if applicable)
+  - Change archived to location
+  - Schema that was used
+
+#### Scenario: Archive complete with warnings
+
+- **WHEN** archive completes with incomplete artifacts or tasks
+- **THEN** include note about what was incomplete
+- **AND** suggest reviewing if archive was intentional

openspec/specs/specs-sync-skill/spec.md

@@ -0,0 +1,72 @@
+# specs-sync-skill Specification
+
+## Purpose
+Defines the agent skill for syncing delta specs from changes to main specs.
+
+## Requirements
+
+### Requirement: Specs Sync Skill
+The system SHALL provide an `/opsx:sync` skill that syncs delta specs from a change to the main specs.
+
+#### Scenario: Sync delta specs to main specs
+- **WHEN** agent executes `/opsx:sync` with a change name
+- **THEN** the agent reads delta specs from `openspec/changes/<name>/specs/`
+- **AND** reads corresponding main specs from `openspec/specs/`
+- **AND** reconciles main specs to match what the deltas describe
+
+#### Scenario: Idempotent operation
+- **WHEN** agent executes `/opsx:sync` multiple times on the same change
+- **THEN** the result is the same as running it once
+- **AND** no duplicate requirements are created
+
+#### Scenario: Change selection prompt
+- **WHEN** agent executes `/opsx:sync` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows changes that have delta specs
+
+### Requirement: Delta Reconciliation Logic
+The agent SHALL reconcile main specs with delta specs using the delta operation headers.
+
+#### Scenario: ADDED requirements
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** the requirement does not exist in main spec
+- **THEN** add the requirement to main spec
+
+#### Scenario: ADDED requirement already exists
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** a requirement with the same name already exists in main spec
+- **THEN** update the existing requirement to match the delta version
+
+#### Scenario: MODIFIED requirements
+- **WHEN** delta contains `## MODIFIED Requirements` with a requirement
+- **AND** the requirement exists in main spec
+- **THEN** replace the requirement in main spec with the delta version
+
+#### Scenario: REMOVED requirements
+- **WHEN** delta contains `## REMOVED Requirements` with a requirement name
+- **AND** the requirement exists in main spec
+- **THEN** remove the requirement from main spec
+
+#### Scenario: RENAMED requirements
+- **WHEN** delta contains `## RENAMED Requirements` with FROM:/TO: format
+- **AND** the FROM requirement exists in main spec
+- **THEN** rename the requirement to the TO name
+
+#### Scenario: New capability spec
+- **WHEN** delta spec exists for a capability not in main specs
+- **THEN** create new main spec file at `openspec/specs/<capability>/spec.md`
+
+### Requirement: Skill Output
+The skill SHALL provide clear feedback on what was applied.
+
+#### Scenario: Show applied changes
+- **WHEN** reconciliation completes successfully
+- **THEN** display summary of changes per capability:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+
+#### Scenario: No changes needed
+- **WHEN** main specs already match delta specs
+- **THEN** display "Specs already in sync - no changes needed"

schemas/spec-driven/schema.yaml

@@ -139,3 +139,10 @@ artifacts:
     requires:
       - specs
       - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.

schemas/tdd/schema.yaml

@@ -204,3 +204,10 @@ artifacts:
       Reference the spec for requirements, implementation for details.
     requires:
       - implementation
+
+apply:
+  requires: [tests]
+  tracks: null
+  instruction: |
+    Run tests to see failures. Implement minimal code to pass each test.
+    Refactor while keeping tests green.

src/commands/artifact-workflow.ts

@@ -19,14 +19,16 @@ import {
   formatChangeStatus,
   generateInstructions,
   listSchemas,
+  listSchemasWithInfo,
   getSchemaDir,
   resolveSchema,
   ArtifactGraph,
   type ChangeStatus,
   type ArtifactInstructions,
+  type SchemaInfo,
 } from '../core/artifact-graph/index.js';
 import { createChange, validateChangeName } from '../utils/change-utils.js';
-import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate } from '../core/templates/skill-templates.js';
+import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate } from '../core/templates/skill-templates.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 
 // -----------------------------------------------------------------------------
@@ -42,12 +44,8 @@ interface TaskItem {
 interface ApplyInstructions {
   changeName: string;
   changeDir: string;
-  contextFiles: {
-    proposal?: string;
-    specs: string;
-    design?: string;
-    tasks: string;
-  };
+  schemaName: string;
+  contextFiles: Record<string, string>;
   progress: {
     total: number;
     complete: number;
@@ -427,8 +425,72 @@ function parseTasksFile(content: string): TaskItem[] {
   return tasks;
 }
 
+/**
+ * Checks if an artifact output exists in the change directory.
+ * Supports glob patterns (e.g., "specs/*.md") by verifying at least one matching file exists.
+ */
+function artifactOutputExists(changeDir: string, generates: string): boolean {
+  // Normalize the generates path to use platform-specific separators
+  const normalizedGenerates = generates.split('/').join(path.sep);
+  const fullPath = path.join(changeDir, normalizedGenerates);
+
+  // If it's a glob pattern (contains ** or *), check for matching files
+  if (generates.includes('*')) {
+    // Extract the directory part before the glob pattern
+    const parts = normalizedGenerates.split(path.sep);
+    const dirParts: string[] = [];
+    let patternPart = '';
+    for (const part of parts) {
+      if (part.includes('*')) {
+        patternPart = part;
+        break;
+      }
+      dirParts.push(part);
+    }
+    const dirPath = path.join(changeDir, ...dirParts);
+
+    // Check if directory exists
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+      return false;
+    }
+
+    // Extract expected extension from pattern (e.g., "*.md" -> ".md")
+    const extMatch = patternPart.match(/\*(\.[a-zA-Z0-9]+)$/);
+    const expectedExt = extMatch ? extMatch[1] : null;
+
+    // Recursively check for matching files
+    const hasMatchingFiles = (dir: string): boolean => {
+      try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            // For ** patterns, recurse into subdirectories
+            if (generates.includes('**') && hasMatchingFiles(path.join(dir, entry.name))) {
+              return true;
+            }
+          } else if (entry.isFile()) {
+            // Check if file matches expected extension (or any file if no extension specified)
+            if (!expectedExt || entry.name.endsWith(expectedExt)) {
+              return true;
+            }
+          }
+        }
+      } catch {
+        return false;
+      }
+      return false;
+    };
+
+    return hasMatchingFiles(dirPath);
+  }
+
+  return fs.existsSync(fullPath);
+}
+
 /**
  * Generates apply instructions for implementing tasks from a change.
+ * Schema-aware: reads apply phase configuration from schema to determine
+ * required artifacts, tracking file, and instruction.
  */
 async function generateApplyInstructions(
   projectRoot: string,
@@ -439,39 +501,43 @@ async function generateApplyInstructions(
   const context = loadChangeContext(projectRoot, changeName, schemaName);
   const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
 
-  // Check if required artifacts exist (tasks.md is the minimum requirement)
-  const tasksPath = path.join(changeDir, 'tasks.md');
-  const proposalPath = path.join(changeDir, 'proposal.md');
-  const designPath = path.join(changeDir, 'design.md');
-  const specsPath = path.join(changeDir, 'specs');
+  // Get the full schema to access the apply phase configuration
+  const schema = resolveSchema(context.schemaName);
+  const applyConfig = schema.apply;
 
-  const hasProposal = fs.existsSync(proposalPath);
-  const hasDesign = fs.existsSync(designPath);
-  const hasTasks = fs.existsSync(tasksPath);
-  const hasSpecs = fs.existsSync(specsPath);
+  // Determine required artifacts and tracking file from schema
+  // Fallback: if no apply block, require all artifacts
+  const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
+  const tracksFile = applyConfig?.tracks ?? null;
+  const schemaInstruction = applyConfig?.instruction ?? null;
 
-  // Determine state and missing artifacts
+  // Check which required artifacts are missing
   const missingArtifacts: string[] = [];
-  if (!hasTasks) {
-    // Check what's missing to create tasks (design is optional)
-    if (!hasProposal) missingArtifacts.push('proposal');
-    if (!hasSpecs) missingArtifacts.push('specs');
-    if (missingArtifacts.length === 0) missingArtifacts.push('tasks');
+  for (const artifactId of requiredArtifactIds) {
+    const artifact = schema.artifacts.find((a) => a.id === artifactId);
+    if (artifact && !artifactOutputExists(changeDir, artifact.generates)) {
+      missingArtifacts.push(artifactId);
+    }
   }
 
-  // Build context files object
-  const contextFiles: ApplyInstructions['contextFiles'] = {
-    specs: path.join(changeDir, 'specs/**/*.md'),
-    tasks: tasksPath,
-  };
-  if (hasProposal) contextFiles.proposal = proposalPath;
-  if (hasDesign) contextFiles.design = designPath;
+  // Build context files from all existing artifacts in schema
+  const contextFiles: Record<string, string> = {};
+  for (const artifact of schema.artifacts) {
+    if (artifactOutputExists(changeDir, artifact.generates)) {
+      contextFiles[artifact.id] = path.join(changeDir, artifact.generates);
+    }
+  }
 
-  // Parse tasks if file exists
+  // Parse tasks if tracking file exists
   let tasks: TaskItem[] = [];
-  if (hasTasks) {
-    const tasksContent = await fs.promises.readFile(tasksPath, 'utf-8');
-    tasks = parseTasksFile(tasksContent);
+  let tracksFileExists = false;
+  if (tracksFile) {
+    const tracksPath = path.join(changeDir, tracksFile);
+    tracksFileExists = fs.existsSync(tracksPath);
+    if (tracksFileExists) {
+      const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
+      tasks = parseTasksFile(tasksContent);
+    }
   }
 
   // Calculate progress
@@ -479,27 +545,39 @@ async function generateApplyInstructions(
   const complete = tasks.filter((t) => t.done).length;
   const remaining = total - complete;
 
-  // Determine state
+  // Determine state and instruction
   let state: ApplyInstructions['state'];
   let instruction: string;
 
-  if (!hasTasks || missingArtifacts.length > 0) {
+  if (missingArtifacts.length > 0) {
     state = 'blocked';
     instruction = `Cannot apply this change yet. Missing artifacts: ${missingArtifacts.join(', ')}.\nUse the openspec-continue-change skill to create the missing artifacts first.`;
-  } else if (remaining === 0 && total > 0) {
+  } else if (tracksFile && !tracksFileExists) {
+    // Tracking file configured but doesn't exist yet
+    const tracksFilename = path.basename(tracksFile);
+    state = 'blocked';
+    instruction = `The ${tracksFilename} file is missing and must be created.\nUse openspec-continue-change to generate the tracking file.`;
+  } else if (tracksFile && tracksFileExists && total === 0) {
+    // Tracking file exists but contains no tasks
+    const tracksFilename = path.basename(tracksFile);
+    state = 'blocked';
+    instruction = `The ${tracksFilename} file exists but contains no tasks.\nAdd tasks to ${tracksFilename} or regenerate it with openspec-continue-change.`;
+  } else if (tracksFile && remaining === 0 && total > 0) {
     state = 'all_done';
     instruction = 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
-  } else if (total === 0) {
-    state = 'blocked';
-    instruction = 'The tasks.md file exists but contains no tasks.\nAdd tasks to tasks.md or regenerate it with openspec-continue-change.';
+  } else if (!tracksFile) {
+    // No tracking file (e.g., TDD schema) - ready to apply
+    state = 'ready';
+    instruction = schemaInstruction?.trim() ?? 'All required artifacts complete. Proceed with implementation.';
   } else {
     state = 'ready';
-    instruction = 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
+    instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
   }
 
   return {
     changeName,
     changeDir,
+    schemaName: context.schemaName,
     contextFiles,
     progress: { total, complete, remaining },
     tasks,
@@ -539,9 +617,10 @@ async function applyInstructionsCommand(options: ApplyInstructionsOptions): Prom
 }
 
 function printApplyInstructionsText(instructions: ApplyInstructions): void {
-  const { changeName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+  const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
 
   console.log(`## Apply: ${changeName}`);
+  console.log(`Schema: ${schemaName}`);
   console.log();
 
   // Warning for blocked state
@@ -553,26 +632,26 @@ function printApplyInstructionsText(instructions: ApplyInstructions): void {
     console.log();
   }
 
-  // Context files
-  console.log('### Context Files');
-  if (contextFiles.proposal) {
-    console.log(`- proposal: ${contextFiles.proposal}`);
+  // Context files (dynamically from schema)
+  const contextFileEntries = Object.entries(contextFiles);
+  if (contextFileEntries.length > 0) {
+    console.log('### Context Files');
+    for (const [artifactId, filePath] of contextFileEntries) {
+      console.log(`- ${artifactId}: ${filePath}`);
+    }
+    console.log();
   }
-  console.log(`- specs: ${contextFiles.specs}`);
-  if (contextFiles.design) {
-    console.log(`- design: ${contextFiles.design}`);
-  }
-  console.log(`- tasks: ${contextFiles.tasks}`);
-  console.log();
 
-  // Progress
-  console.log('### Progress');
-  if (state === 'all_done') {
-    console.log(`${progress.complete}/${progress.total} complete ✓`);
-  } else {
-    console.log(`${progress.complete}/${progress.total} complete`);
+  // Progress (only show if we have tracking)
+  if (progress.total > 0 || tasks.length > 0) {
+    console.log('### Progress');
+    if (state === 'all_done') {
+      console.log(`${progress.complete}/${progress.total} complete ✓`);
+    } else {
+      console.log(`${progress.complete}/${progress.total} complete`);
+    }
+    console.log();
   }
-  console.log();
 
   // Tasks
   if (tasks.length > 0) {
@@ -717,17 +796,26 @@ async function artifactExperimentalSetupCommand(): Promise<void> {
     const newChangeSkill = getNewChangeSkillTemplate();
     const continueChangeSkill = getContinueChangeSkillTemplate();
     const applyChangeSkill = getApplyChangeSkillTemplate();
+    const ffChangeSkill = getFfChangeSkillTemplate();
+    const syncSpecsSkill = getSyncSpecsSkillTemplate();
+    const archiveChangeSkill = getArchiveChangeSkillTemplate();
 
     // Get command templates
     const newCommand = getOpsxNewCommandTemplate();
     const continueCommand = getOpsxContinueCommandTemplate();
     const applyCommand = getOpsxApplyCommandTemplate();
+    const ffCommand = getOpsxFfCommandTemplate();
+    const syncCommand = getOpsxSyncCommandTemplate();
+    const archiveCommand = getOpsxArchiveCommandTemplate();
 
     // Create skill directories and SKILL.md files
     const skills = [
       { template: newChangeSkill, dirName: 'openspec-new-change' },
       { template: continueChangeSkill, dirName: 'openspec-continue-change' },
       { template: applyChangeSkill, dirName: 'openspec-apply-change' },
+      { template: ffChangeSkill, dirName: 'openspec-ff-change' },
+      { template: syncSpecsSkill, dirName: 'openspec-sync-specs' },
+      { template: archiveChangeSkill, dirName: 'openspec-archive-change' },
     ];
 
     const createdSkillFiles: string[] = [];
@@ -755,6 +843,9 @@ ${template.instructions}
       { template: newCommand, fileName: 'new.md' },
       { template: continueCommand, fileName: 'continue.md' },
       { template: applyCommand, fileName: 'apply.md' },
+      { template: ffCommand, fileName: 'ff.md' },
+      { template: syncCommand, fileName: 'sync.md' },
+      { template: archiveCommand, fileName: 'archive.md' },
     ];
 
     const createdCommandFiles: string[] = [];
@@ -810,6 +901,9 @@ ${template.content}
     console.log('  • /opsx:new - Start a new change');
     console.log('  • /opsx:continue - Create the next artifact');
     console.log('  • /opsx:apply - Implement tasks');
+    console.log('  • /opsx:ff - Fast-forward: create all artifacts at once');
+    console.log('  • /opsx:sync - Sync delta specs to main specs');
+    console.log('  • /opsx:archive - Archive a completed change');
     console.log();
     console.log(chalk.yellow('💡 This is an experimental feature.'));
     console.log('   Feedback welcome at: https://github.com/Fission-AI/OpenSpec/issues');
@@ -820,6 +914,34 @@ ${template.content}
   }
 }
 
+// -----------------------------------------------------------------------------
+// Schemas Command
+// -----------------------------------------------------------------------------
+
+interface SchemasOptions {
+  json?: boolean;
+}
+
+async function schemasCommand(options: SchemasOptions): Promise<void> {
+  const schemas = listSchemasWithInfo();
+
+  if (options.json) {
+    console.log(JSON.stringify(schemas, null, 2));
+    return;
+  }
+
+  console.log('Available schemas:');
+  console.log();
+
+  for (const schema of schemas) {
+    const sourceLabel = schema.source === 'user' ? chalk.dim(' (user override)') : '';
+    console.log(`  ${chalk.bold(schema.name)}${sourceLabel}`);
+    console.log(`    ${schema.description}`);
+    console.log(`    Artifacts: ${schema.artifacts.join(' → ')}`);
+    console.log();
+  }
+}
+
 // -----------------------------------------------------------------------------
 // Command Registration
 // -----------------------------------------------------------------------------
@@ -884,6 +1006,21 @@ export function registerArtifactWorkflowCommands(program: Command): void {
       }
     });
 
+  // Schemas command
+  program
+    .command('schemas')
+    .description('[Experimental] List available workflow schemas with descriptions')
+    .option('--json', 'Output as JSON (for agent use)')
+    .action(async (options: SchemasOptions) => {
+      try {
+        await schemasCommand(options);
+      } catch (error) {
+        console.log();
+        ora().fail(`Error: ${(error as Error).message}`);
+        process.exit(1);
+      }
+    });
+
   // New command group with change subcommand
   const newCmd = program.command('new').description('[Experimental] Create new items');
 

src/core/archive.ts

@@ -4,17 +4,11 @@ import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progre
 import { Validator } from './validation/validator.js';
 import chalk from 'chalk';
 import {
-  extractRequirementsSection,
-  parseDeltaSpec,
-  normalizeRequirementName,
-  type RequirementBlock,
-} from './parsers/requirement-blocks.js';
-
-interface SpecUpdate {
-  source: string;
-  target: string;
-  exists: boolean;
-}
+  findSpecUpdates,
+  buildUpdatedSpec,
+  writeUpdatedSpec,
+  type SpecUpdate,
+} from './specs-apply.js';
 
 export class ArchiveCommand {
   async execute(
@@ -167,7 +161,7 @@ export class ArchiveCommand {
       console.log('Skipping spec updates (--skip-specs flag provided).');
     } else {
       // Find specs to update
-      const specUpdates = await this.findSpecUpdates(changeDir, mainSpecsDir);
+      const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
       
       if (specUpdates.length > 0) {
         console.log('\nSpecs to update:');
@@ -194,7 +188,7 @@ export class ArchiveCommand {
           const prepared: Array<{ update: SpecUpdate; rebuilt: string; counts: { added: number; modified: number; removed: number; renamed: number } }> = [];
           try {
             for (const update of specUpdates) {
-              const built = await this.buildUpdatedSpec(update, changeName!);
+              const built = await buildUpdatedSpec(update, changeName!);
               prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
             }
           } catch (err: any) {
@@ -219,7 +213,7 @@ export class ArchiveCommand {
                 return;
               }
             }
-            await this.writeUpdatedSpec(p.update, p.rebuilt, p.counts);
+            await writeUpdatedSpec(p.update, p.rebuilt, p.counts);
             totals.added += p.counts.added;
             totals.modified += p.counts.modified;
             totals.removed += p.counts.removed;
@@ -301,323 +295,6 @@ export class ArchiveCommand {
     }
   }
 
-  // Deprecated: replaced by shared task-progress utilities
-  private async checkIncompleteTasks(_tasksPath: string): Promise<number> {
-    return 0;
-  }
-
-  private async findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]> {
-    const updates: SpecUpdate[] = [];
-    const changeSpecsDir = path.join(changeDir, 'specs');
-
-    try {
-      const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
-      
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
-          const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
-          
-          try {
-            await fs.access(specFile);
-            
-            // Check if target exists
-            let exists = false;
-            try {
-              await fs.access(targetFile);
-              exists = true;
-            } catch {
-              exists = false;
-            }
-
-            updates.push({
-              source: specFile,
-              target: targetFile,
-              exists
-            });
-          } catch {
-            // Source spec doesn't exist, skip
-          }
-        }
-      }
-    } catch {
-      // No specs directory in change
-    }
-
-    return updates;
-  }
-
-  private async buildUpdatedSpec(update: SpecUpdate, changeName: string): Promise<{ rebuilt: string; counts: { added: number; modified: number; removed: number; renamed: number } }> {
-    // Read change spec content (delta-format expected)
-    const changeContent = await fs.readFile(update.source, 'utf-8');
-
-    // Parse deltas from the change spec file
-    const plan = parseDeltaSpec(changeContent);
-    const specName = path.basename(path.dirname(update.target));
-
-    // Pre-validate duplicates within sections
-    const addedNames = new Set<string>();
-    for (const add of plan.added) {
-      const name = normalizeRequirementName(add.name);
-      if (addedNames.has(name)) {
-        throw new Error(
-          `${specName} validation failed - duplicate requirement in ADDED for header "### Requirement: ${add.name}"`
-        );
-      }
-      addedNames.add(name);
-    }
-    const modifiedNames = new Set<string>();
-    for (const mod of plan.modified) {
-      const name = normalizeRequirementName(mod.name);
-      if (modifiedNames.has(name)) {
-        throw new Error(
-          `${specName} validation failed - duplicate requirement in MODIFIED for header "### Requirement: ${mod.name}"`
-        );
-      }
-      modifiedNames.add(name);
-    }
-    const removedNamesSet = new Set<string>();
-    for (const rem of plan.removed) {
-      const name = normalizeRequirementName(rem);
-      if (removedNamesSet.has(name)) {
-        throw new Error(
-          `${specName} validation failed - duplicate requirement in REMOVED for header "### Requirement: ${rem}"`
-        );
-      }
-      removedNamesSet.add(name);
-    }
-    const renamedFromSet = new Set<string>();
-    const renamedToSet = new Set<string>();
-    for (const { from, to } of plan.renamed) {
-      const fromNorm = normalizeRequirementName(from);
-      const toNorm = normalizeRequirementName(to);
-      if (renamedFromSet.has(fromNorm)) {
-        throw new Error(
-          `${specName} validation failed - duplicate FROM in RENAMED for header "### Requirement: ${from}"`
-        );
-      }
-      if (renamedToSet.has(toNorm)) {
-        throw new Error(
-          `${specName} validation failed - duplicate TO in RENAMED for header "### Requirement: ${to}"`
-        );
-      }
-      renamedFromSet.add(fromNorm);
-      renamedToSet.add(toNorm);
-    }
-
-    // Pre-validate cross-section conflicts
-    const conflicts: Array<{ name: string; a: string; b: string }> = [];
-    for (const n of modifiedNames) {
-      if (removedNamesSet.has(n)) conflicts.push({ name: n, a: 'MODIFIED', b: 'REMOVED' });
-      if (addedNames.has(n)) conflicts.push({ name: n, a: 'MODIFIED', b: 'ADDED' });
-    }
-    for (const n of addedNames) {
-      if (removedNamesSet.has(n)) conflicts.push({ name: n, a: 'ADDED', b: 'REMOVED' });
-    }
-    // Renamed interplay: MODIFIED must reference the NEW header, not FROM
-    for (const { from, to } of plan.renamed) {
-      const fromNorm = normalizeRequirementName(from);
-      const toNorm = normalizeRequirementName(to);
-      if (modifiedNames.has(fromNorm)) {
-        throw new Error(
-          `${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`
-        );
-      }
-      // Detect ADDED colliding with a RENAMED TO
-      if (addedNames.has(toNorm)) {
-        throw new Error(
-          `${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"`
-        );
-      }
-    }
-    if (conflicts.length > 0) {
-      const c = conflicts[0];
-      throw new Error(
-        `${specName} validation failed - requirement present in multiple sections (${c.a} and ${c.b}) for header "### Requirement: ${c.name}"`
-      );
-    }
-    const hasAnyDelta = (plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length) > 0;
-    if (!hasAnyDelta) {
-      throw new Error(
-        `Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
-        `Provide ADDED/MODIFIED/REMOVED/RENAMED sections in change spec.`
-      );
-    }
-
-    // Load or create base target content
-    let targetContent: string;
-    let isNewSpec = false;
-    try {
-      targetContent = await fs.readFile(update.target, 'utf-8');
-    } catch {
-      // Target spec does not exist; MODIFIED and RENAMED are not allowed for new specs
-      // REMOVED will be ignored with a warning since there's nothing to remove
-      if (plan.modified.length > 0 || plan.renamed.length > 0) {
-        throw new Error(
-          `${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.`
-        );
-      }
-      // Warn about REMOVED requirements being ignored for new specs
-      if (plan.removed.length > 0) {
-        console.log(
-          chalk.yellow(
-            `⚠️  Warning: ${specName} - ${plan.removed.length} REMOVED requirement(s) ignored for new spec (nothing to remove).`
-          )
-        );
-      }
-      isNewSpec = true;
-      targetContent = this.buildSpecSkeleton(specName, changeName);
-    }
-
-    // Extract requirements section and build name->block map
-    const parts = extractRequirementsSection(targetContent);
-    const nameToBlock = new Map<string, RequirementBlock>();
-    for (const block of parts.bodyBlocks) {
-      nameToBlock.set(normalizeRequirementName(block.name), block);
-    }
-
-    // Apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED
-    // RENAMED
-    for (const r of plan.renamed) {
-      const from = normalizeRequirementName(r.from);
-      const to = normalizeRequirementName(r.to);
-      if (!nameToBlock.has(from)) {
-        throw new Error(
-          `${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found`
-        );
-      }
-      if (nameToBlock.has(to)) {
-        throw new Error(
-          `${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`
-        );
-      }
-      const block = nameToBlock.get(from)!;
-      const newHeader = `### Requirement: ${to}`;
-      const rawLines = block.raw.split('\n');
-      rawLines[0] = newHeader;
-      const renamedBlock: RequirementBlock = {
-        headerLine: newHeader,
-        name: to,
-        raw: rawLines.join('\n'),
-      };
-      nameToBlock.delete(from);
-      nameToBlock.set(to, renamedBlock);
-    }
-
-    // REMOVED
-    for (const name of plan.removed) {
-      const key = normalizeRequirementName(name);
-      if (!nameToBlock.has(key)) {
-        // For new specs, REMOVED requirements are already warned about and ignored
-        // For existing specs, missing requirements are an error
-        if (!isNewSpec) {
-          throw new Error(
-            `${specName} REMOVED failed for header "### Requirement: ${name}" - not found`
-          );
-        }
-        // Skip removal for new specs (already warned above)
-        continue;
-      }
-      nameToBlock.delete(key);
-    }
-
-    // MODIFIED
-    for (const mod of plan.modified) {
-      const key = normalizeRequirementName(mod.name);
-      if (!nameToBlock.has(key)) {
-        throw new Error(
-          `${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`
-        );
-      }
-      // Replace block with provided raw (ensure header line matches key)
-      const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/);
-      if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
-        throw new Error(
-          `${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`
-        );
-      }
-      nameToBlock.set(key, mod);
-    }
-
-    // ADDED
-    for (const add of plan.added) {
-      const key = normalizeRequirementName(add.name);
-      if (nameToBlock.has(key)) {
-        throw new Error(
-          `${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`
-        );
-      }
-      nameToBlock.set(key, add);
-    }
-
-    // Duplicates within resulting map are implicitly prevented by key uniqueness.
-
-    // Recompose requirements section preserving original ordering where possible
-    const keptOrder: RequirementBlock[] = [];
-    const seen = new Set<string>();
-    for (const block of parts.bodyBlocks) {
-      const key = normalizeRequirementName(block.name);
-      const replacement = nameToBlock.get(key);
-      if (replacement) {
-        keptOrder.push(replacement);
-        seen.add(key);
-      }
-    }
-    // Append any newly added that were not in original order
-    for (const [key, block] of nameToBlock.entries()) {
-      if (!seen.has(key)) {
-        keptOrder.push(block);
-      }
-    }
-
-    const reqBody = [
-      parts.preamble && parts.preamble.trim() ? parts.preamble.trimEnd() : ''
-    ]
-      .filter(Boolean)
-      .concat(keptOrder.map(b => b.raw))
-      .join('\n\n')
-      .trimEnd();
-
-    const rebuilt = [
-      parts.before.trimEnd(),
-      parts.headerLine,
-      reqBody,
-      parts.after
-    ]
-      .filter((s, idx) => !(idx === 0 && s === ''))
-      .join('\n')
-      .replace(/\n{3,}/g, '\n\n');
-
-    return {
-      rebuilt,
-      counts: {
-        added: plan.added.length,
-        modified: plan.modified.length,
-        removed: plan.removed.length,
-        renamed: plan.renamed.length,
-      }
-    };
-  }
-
-  private async writeUpdatedSpec(update: SpecUpdate, rebuilt: string, counts: { added: number; modified: number; removed: number; renamed: number }): Promise<void> {
-    // Create target directory if needed
-    const targetDir = path.dirname(update.target);
-    await fs.mkdir(targetDir, { recursive: true });
-    await fs.writeFile(update.target, rebuilt);
-
-    const specName = path.basename(path.dirname(update.target));
-    console.log(`Applying changes to openspec/specs/${specName}/spec.md:`);
-    if (counts.added) console.log(`  + ${counts.added} added`);
-    if (counts.modified) console.log(`  ~ ${counts.modified} modified`);
-    if (counts.removed) console.log(`  - ${counts.removed} removed`);
-    if (counts.renamed) console.log(`  → ${counts.renamed} renamed`);
-  }
-
-  private buildSpecSkeleton(specFolderName: string, changeName: string): string {
-    const titleBase = specFolderName;
-    return `# ${titleBase} Specification\n\n## Purpose\nTBD - created by archiving change ${changeName}. Update Purpose after archive.\n\n## Requirements\n`;
-  }
-
   private getArchiveDate(): string {
     // Returns date in YYYY-MM-DD format
     return new Date().toISOString().split('T')[0];

src/core/artifact-graph/index.ts

@@ -21,10 +21,12 @@ export { detectCompleted } from './state.js';
 export {
   resolveSchema,
   listSchemas,
+  listSchemasWithInfo,
   getSchemaDir,
   getPackageSchemasDir,
   getUserSchemasDir,
   SchemaLoadError,
+  type SchemaInfo,
 } from './resolver.js';
 
 // Instruction loading

src/core/artifact-graph/instruction-loader.ts

@@ -99,6 +99,8 @@ export interface ChangeStatus {
   schemaName: string;
   /** Whether all artifacts are complete */
   isComplete: boolean;
+  /** Artifact IDs required before apply phase (from schema's apply.requires) */
+  applyRequires: string[];
   /** Status of each artifact */
   artifacts: ArtifactStatus[];
 }
@@ -252,6 +254,10 @@ function getUnlockedArtifacts(graph: ArtifactGraph, artifactId: string): string[
  * @returns Formatted change status
  */
 export function formatChangeStatus(context: ChangeContext): ChangeStatus {
+  // Load schema to get apply phase configuration
+  const schema = resolveSchema(context.schemaName);
+  const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
+
   const artifacts = context.graph.getAllArtifacts();
   const ready = new Set(context.graph.getNextArtifacts(context.completed));
   const blocked = context.graph.getBlocked(context.completed);
@@ -290,6 +296,7 @@ export function formatChangeStatus(context: ChangeContext): ChangeStatus {
     changeName: context.changeName,
     schemaName: context.schemaName,
     isComplete: context.graph.isComplete(context.completed),
+    applyRequires,
     artifacts: artifactStatuses,
   };
 }

src/core/artifact-graph/resolver.ts

@@ -156,3 +156,71 @@ export function listSchemas(): string[] {
 
   return Array.from(schemas).sort();
 }
+
+/**
+ * Schema info with metadata (name, description, artifacts).
+ */
+export interface SchemaInfo {
+  name: string;
+  description: string;
+  artifacts: string[];
+  source: 'package' | 'user';
+}
+
+/**
+ * Lists all available schemas with their descriptions and artifact lists.
+ * Useful for agent skills to present schema selection to users.
+ */
+export function listSchemasWithInfo(): SchemaInfo[] {
+  const schemas: SchemaInfo[] = [];
+  const seenNames = new Set<string>();
+
+  // Add user override schemas first (they take precedence)
+  const userDir = getUserSchemasDir();
+  if (fs.existsSync(userDir)) {
+    for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
+        if (fs.existsSync(schemaPath)) {
+          try {
+            const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+            schemas.push({
+              name: entry.name,
+              description: schema.description || '',
+              artifacts: schema.artifacts.map((a) => a.id),
+              source: 'user',
+            });
+            seenNames.add(entry.name);
+          } catch {
+            // Skip invalid schemas
+          }
+        }
+      }
+    }
+  }
+
+  // Add package built-in schemas (if not overridden)
+  const packageDir = getPackageSchemasDir();
+  if (fs.existsSync(packageDir)) {
+    for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !seenNames.has(entry.name)) {
+        const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+        if (fs.existsSync(schemaPath)) {
+          try {
+            const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+            schemas.push({
+              name: entry.name,
+              description: schema.description || '',
+              artifacts: schema.artifacts.map((a) => a.id),
+              source: 'package',
+            });
+          } catch {
+            // Skip invalid schemas
+          }
+        }
+      }
+    }
+  }
+
+  return schemas.sort((a, b) => a.name.localeCompare(b.name));
+}

src/core/artifact-graph/types.ts

@@ -10,16 +10,29 @@ export const ArtifactSchema = z.object({
   requires: z.array(z.string()).default([]),
 });
 
+// Apply phase configuration for schema-aware apply instructions
+export const ApplyPhaseSchema = z.object({
+  // Artifact IDs that must exist before apply is available
+  requires: z.array(z.string()).min(1, { error: 'At least one required artifact' }),
+  // Path to file with checkboxes for progress (relative to change dir), or null if no tracking
+  tracks: z.string().nullable().optional(),
+  // Custom guidance for the apply phase
+  instruction: z.string().optional(),
+});
+
 // Full schema YAML structure
 export const SchemaYamlSchema = z.object({
   name: z.string().min(1, { error: 'Schema name is required' }),
   version: z.number().int().positive({ error: 'Version must be a positive integer' }),
   description: z.string().optional(),
   artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+  // Optional apply phase configuration (for schema-aware apply instructions)
+  apply: ApplyPhaseSchema.optional(),
 });
 
 // Derived TypeScript types
 export type Artifact = z.infer<typeof ArtifactSchema>;
+export type ApplyPhase = z.infer<typeof ApplyPhaseSchema>;
 export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
 
 // Per-change metadata schema

src/core/specs-apply.ts

@@ -0,0 +1,483 @@
+/**
+ * Spec Application Logic
+ *
+ * Extracted from ArchiveCommand to enable standalone spec application.
+ * Applies delta specs from a change to main specs without archiving.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import {
+  extractRequirementsSection,
+  parseDeltaSpec,
+  normalizeRequirementName,
+  type RequirementBlock,
+} from './parsers/requirement-blocks.js';
+import { Validator } from './validation/validator.js';
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+export interface SpecUpdate {
+  source: string;
+  target: string;
+  exists: boolean;
+}
+
+export interface ApplyResult {
+  capability: string;
+  added: number;
+  modified: number;
+  removed: number;
+  renamed: number;
+}
+
+export interface SpecsApplyOutput {
+  changeName: string;
+  capabilities: ApplyResult[];
+  totals: {
+    added: number;
+    modified: number;
+    removed: number;
+    renamed: number;
+  };
+  noChanges: boolean;
+}
+
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+
+/**
+ * Find all delta spec files that need to be applied from a change.
+ */
+export async function findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]> {
+  const updates: SpecUpdate[] = [];
+  const changeSpecsDir = path.join(changeDir, 'specs');
+
+  try {
+    const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+        const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
+
+        try {
+          await fs.access(specFile);
+
+          // Check if target exists
+          let exists = false;
+          try {
+            await fs.access(targetFile);
+            exists = true;
+          } catch {
+            exists = false;
+          }
+
+          updates.push({
+            source: specFile,
+            target: targetFile,
+            exists,
+          });
+        } catch {
+          // Source spec doesn't exist, skip
+        }
+      }
+    }
+  } catch {
+    // No specs directory in change
+  }
+
+  return updates;
+}
+
+/**
+ * Build an updated spec by applying delta operations.
+ * Returns the rebuilt content and counts of operations.
+ */
+export async function buildUpdatedSpec(
+  update: SpecUpdate,
+  changeName: string
+): Promise<{ rebuilt: string; counts: { added: number; modified: number; removed: number; renamed: number } }> {
+  // Read change spec content (delta-format expected)
+  const changeContent = await fs.readFile(update.source, 'utf-8');
+
+  // Parse deltas from the change spec file
+  const plan = parseDeltaSpec(changeContent);
+  const specName = path.basename(path.dirname(update.target));
+
+  // Pre-validate duplicates within sections
+  const addedNames = new Set<string>();
+  for (const add of plan.added) {
+    const name = normalizeRequirementName(add.name);
+    if (addedNames.has(name)) {
+      throw new Error(
+        `${specName} validation failed - duplicate requirement in ADDED for header "### Requirement: ${add.name}"`
+      );
+    }
+    addedNames.add(name);
+  }
+  const modifiedNames = new Set<string>();
+  for (const mod of plan.modified) {
+    const name = normalizeRequirementName(mod.name);
+    if (modifiedNames.has(name)) {
+      throw new Error(
+        `${specName} validation failed - duplicate requirement in MODIFIED for header "### Requirement: ${mod.name}"`
+      );
+    }
+    modifiedNames.add(name);
+  }
+  const removedNamesSet = new Set<string>();
+  for (const rem of plan.removed) {
+    const name = normalizeRequirementName(rem);
+    if (removedNamesSet.has(name)) {
+      throw new Error(
+        `${specName} validation failed - duplicate requirement in REMOVED for header "### Requirement: ${rem}"`
+      );
+    }
+    removedNamesSet.add(name);
+  }
+  const renamedFromSet = new Set<string>();
+  const renamedToSet = new Set<string>();
+  for (const { from, to } of plan.renamed) {
+    const fromNorm = normalizeRequirementName(from);
+    const toNorm = normalizeRequirementName(to);
+    if (renamedFromSet.has(fromNorm)) {
+      throw new Error(
+        `${specName} validation failed - duplicate FROM in RENAMED for header "### Requirement: ${from}"`
+      );
+    }
+    if (renamedToSet.has(toNorm)) {
+      throw new Error(
+        `${specName} validation failed - duplicate TO in RENAMED for header "### Requirement: ${to}"`
+      );
+    }
+    renamedFromSet.add(fromNorm);
+    renamedToSet.add(toNorm);
+  }
+
+  // Pre-validate cross-section conflicts
+  const conflicts: Array<{ name: string; a: string; b: string }> = [];
+  for (const n of modifiedNames) {
+    if (removedNamesSet.has(n)) conflicts.push({ name: n, a: 'MODIFIED', b: 'REMOVED' });
+    if (addedNames.has(n)) conflicts.push({ name: n, a: 'MODIFIED', b: 'ADDED' });
+  }
+  for (const n of addedNames) {
+    if (removedNamesSet.has(n)) conflicts.push({ name: n, a: 'ADDED', b: 'REMOVED' });
+  }
+  // Renamed interplay: MODIFIED must reference the NEW header, not FROM
+  for (const { from, to } of plan.renamed) {
+    const fromNorm = normalizeRequirementName(from);
+    const toNorm = normalizeRequirementName(to);
+    if (modifiedNames.has(fromNorm)) {
+      throw new Error(
+        `${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`
+      );
+    }
+    // Detect ADDED colliding with a RENAMED TO
+    if (addedNames.has(toNorm)) {
+      throw new Error(
+        `${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"`
+      );
+    }
+  }
+  if (conflicts.length > 0) {
+    const c = conflicts[0];
+    throw new Error(
+      `${specName} validation failed - requirement present in multiple sections (${c.a} and ${c.b}) for header "### Requirement: ${c.name}"`
+    );
+  }
+  const hasAnyDelta = plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length > 0;
+  if (!hasAnyDelta) {
+    throw new Error(
+      `Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
+        `Provide ADDED/MODIFIED/REMOVED/RENAMED sections in change spec.`
+    );
+  }
+
+  // Load or create base target content
+  let targetContent: string;
+  let isNewSpec = false;
+  try {
+    targetContent = await fs.readFile(update.target, 'utf-8');
+  } catch {
+    // Target spec does not exist; MODIFIED and RENAMED are not allowed for new specs
+    // REMOVED will be ignored with a warning since there's nothing to remove
+    if (plan.modified.length > 0 || plan.renamed.length > 0) {
+      throw new Error(
+        `${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.`
+      );
+    }
+    // Warn about REMOVED requirements being ignored for new specs
+    if (plan.removed.length > 0) {
+      console.log(
+        chalk.yellow(
+          `⚠️  Warning: ${specName} - ${plan.removed.length} REMOVED requirement(s) ignored for new spec (nothing to remove).`
+        )
+      );
+    }
+    isNewSpec = true;
+    targetContent = buildSpecSkeleton(specName, changeName);
+  }
+
+  // Extract requirements section and build name->block map
+  const parts = extractRequirementsSection(targetContent);
+  const nameToBlock = new Map<string, RequirementBlock>();
+  for (const block of parts.bodyBlocks) {
+    nameToBlock.set(normalizeRequirementName(block.name), block);
+  }
+
+  // Apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED
+  // RENAMED
+  for (const r of plan.renamed) {
+    const from = normalizeRequirementName(r.from);
+    const to = normalizeRequirementName(r.to);
+    if (!nameToBlock.has(from)) {
+      throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found`);
+    }
+    if (nameToBlock.has(to)) {
+      throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`);
+    }
+    const block = nameToBlock.get(from)!;
+    const newHeader = `### Requirement: ${to}`;
+    const rawLines = block.raw.split('\n');
+    rawLines[0] = newHeader;
+    const renamedBlock: RequirementBlock = {
+      headerLine: newHeader,
+      name: to,
+      raw: rawLines.join('\n'),
+    };
+    nameToBlock.delete(from);
+    nameToBlock.set(to, renamedBlock);
+  }
+
+  // REMOVED
+  for (const name of plan.removed) {
+    const key = normalizeRequirementName(name);
+    if (!nameToBlock.has(key)) {
+      // For new specs, REMOVED requirements are already warned about and ignored
+      // For existing specs, missing requirements are an error
+      if (!isNewSpec) {
+        throw new Error(`${specName} REMOVED failed for header "### Requirement: ${name}" - not found`);
+      }
+      // Skip removal for new specs (already warned above)
+      continue;
+    }
+    nameToBlock.delete(key);
+  }
+
+  // MODIFIED
+  for (const mod of plan.modified) {
+    const key = normalizeRequirementName(mod.name);
+    if (!nameToBlock.has(key)) {
+      throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
+    }
+    // Replace block with provided raw (ensure header line matches key)
+    const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/);
+    if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
+      throw new Error(
+        `${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`
+      );
+    }
+    nameToBlock.set(key, mod);
+  }
+
+  // ADDED
+  for (const add of plan.added) {
+    const key = normalizeRequirementName(add.name);
+    if (nameToBlock.has(key)) {
+      throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`);
+    }
+    nameToBlock.set(key, add);
+  }
+
+  // Duplicates within resulting map are implicitly prevented by key uniqueness.
+
+  // Recompose requirements section preserving original ordering where possible
+  const keptOrder: RequirementBlock[] = [];
+  const seen = new Set<string>();
+  for (const block of parts.bodyBlocks) {
+    const key = normalizeRequirementName(block.name);
+    const replacement = nameToBlock.get(key);
+    if (replacement) {
+      keptOrder.push(replacement);
+      seen.add(key);
+    }
+  }
+  // Append any newly added that were not in original order
+  for (const [key, block] of nameToBlock.entries()) {
+    if (!seen.has(key)) {
+      keptOrder.push(block);
+    }
+  }
+
+  const reqBody = [parts.preamble && parts.preamble.trim() ? parts.preamble.trimEnd() : '']
+    .filter(Boolean)
+    .concat(keptOrder.map((b) => b.raw))
+    .join('\n\n')
+    .trimEnd();
+
+  const rebuilt = [parts.before.trimEnd(), parts.headerLine, reqBody, parts.after]
+    .filter((s, idx) => !(idx === 0 && s === ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n');
+
+  return {
+    rebuilt,
+    counts: {
+      added: plan.added.length,
+      modified: plan.modified.length,
+      removed: plan.removed.length,
+      renamed: plan.renamed.length,
+    },
+  };
+}
+
+/**
+ * Write an updated spec to disk.
+ */
+export async function writeUpdatedSpec(
+  update: SpecUpdate,
+  rebuilt: string,
+  counts: { added: number; modified: number; removed: number; renamed: number }
+): Promise<void> {
+  // Create target directory if needed
+  const targetDir = path.dirname(update.target);
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.writeFile(update.target, rebuilt);
+
+  const specName = path.basename(path.dirname(update.target));
+  console.log(`Applying changes to openspec/specs/${specName}/spec.md:`);
+  if (counts.added) console.log(`  + ${counts.added} added`);
+  if (counts.modified) console.log(`  ~ ${counts.modified} modified`);
+  if (counts.removed) console.log(`  - ${counts.removed} removed`);
+  if (counts.renamed) console.log(`  → ${counts.renamed} renamed`);
+}
+
+/**
+ * Build a skeleton spec for new capabilities.
+ */
+export function buildSpecSkeleton(specFolderName: string, changeName: string): string {
+  const titleBase = specFolderName;
+  return `# ${titleBase} Specification\n\n## Purpose\nTBD - created by archiving change ${changeName}. Update Purpose after archive.\n\n## Requirements\n`;
+}
+
+/**
+ * Apply all delta specs from a change to main specs.
+ *
+ * @param projectRoot - The project root directory
+ * @param changeName - The name of the change to apply
+ * @param options - Options for the operation
+ * @returns Result of the operation with counts
+ */
+export async function applySpecs(
+  projectRoot: string,
+  changeName: string,
+  options: {
+    dryRun?: boolean;
+    skipValidation?: boolean;
+    silent?: boolean;
+  } = {}
+): Promise<SpecsApplyOutput> {
+  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+  const mainSpecsDir = path.join(projectRoot, 'openspec', 'specs');
+
+  // Verify change exists
+  try {
+    const stat = await fs.stat(changeDir);
+    if (!stat.isDirectory()) {
+      throw new Error(`Change '${changeName}' not found.`);
+    }
+  } catch {
+    throw new Error(`Change '${changeName}' not found.`);
+  }
+
+  // Find specs to update
+  const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
+
+  if (specUpdates.length === 0) {
+    return {
+      changeName,
+      capabilities: [],
+      totals: { added: 0, modified: 0, removed: 0, renamed: 0 },
+      noChanges: true,
+    };
+  }
+
+  // Prepare all updates first (validation pass, no writes)
+  const prepared: Array<{
+    update: SpecUpdate;
+    rebuilt: string;
+    counts: { added: number; modified: number; removed: number; renamed: number };
+  }> = [];
+
+  for (const update of specUpdates) {
+    const built = await buildUpdatedSpec(update, changeName);
+    prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+  }
+
+  // Validate rebuilt specs unless validation is skipped
+  if (!options.skipValidation) {
+    const validator = new Validator();
+    for (const p of prepared) {
+      const specName = path.basename(path.dirname(p.update.target));
+      const report = await validator.validateSpecContent(specName, p.rebuilt);
+      if (!report.valid) {
+        const errors = report.issues
+          .filter((i) => i.level === 'ERROR')
+          .map((i) => `  ✗ ${i.message}`)
+          .join('\n');
+        throw new Error(`Validation errors in rebuilt spec for ${specName}:\n${errors}`);
+      }
+    }
+  }
+
+  // Build results
+  const capabilities: ApplyResult[] = [];
+  const totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+
+  for (const p of prepared) {
+    const capability = path.basename(path.dirname(p.update.target));
+
+    if (!options.dryRun) {
+      // Write the updated spec
+      const targetDir = path.dirname(p.update.target);
+      await fs.mkdir(targetDir, { recursive: true });
+      await fs.writeFile(p.update.target, p.rebuilt);
+
+      if (!options.silent) {
+        console.log(`Applying changes to openspec/specs/${capability}/spec.md:`);
+        if (p.counts.added) console.log(`  + ${p.counts.added} added`);
+        if (p.counts.modified) console.log(`  ~ ${p.counts.modified} modified`);
+        if (p.counts.removed) console.log(`  - ${p.counts.removed} removed`);
+        if (p.counts.renamed) console.log(`  → ${p.counts.renamed} renamed`);
+      }
+    } else if (!options.silent) {
+      console.log(`Would apply changes to openspec/specs/${capability}/spec.md:`);
+      if (p.counts.added) console.log(`  + ${p.counts.added} added`);
+      if (p.counts.modified) console.log(`  ~ ${p.counts.modified} modified`);
+      if (p.counts.removed) console.log(`  - ${p.counts.removed} removed`);
+      if (p.counts.renamed) console.log(`  → ${p.counts.renamed} renamed`);
+    }
+
+    capabilities.push({
+      capability,
+      ...p.counts,
+    });
+
+    totals.added += p.counts.added;
+    totals.modified += p.counts.modified;
+    totals.removed += p.counts.removed;
+    totals.renamed += p.counts.renamed;
+  }
+
+  return {
+    changeName,
+    capabilities,
+    totals,
+    noChanges: false,
+  };
+}

test/commands/artifact-workflow.test.ts

@@ -348,6 +348,209 @@ describe('artifact-workflow CLI commands', () => {
     });
   });
 
+  describe('instructions apply command', () => {
+    it('shows apply instructions for spec-driven schema with tasks', async () => {
+      await createTestChange('apply-change', ['proposal', 'design', 'specs', 'tasks']);
+
+      const result = await runCLI(['instructions', 'apply', '--change', 'apply-change'], {
+        cwd: tempDir,
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('## Apply: apply-change');
+      expect(result.stdout).toContain('Schema: spec-driven');
+      expect(result.stdout).toContain('### Context Files');
+      expect(result.stdout).toContain('### Instruction');
+    });
+
+    it('shows blocked state when required artifacts are missing', async () => {
+      // Only create proposal - missing tasks (required by spec-driven apply block)
+      await createTestChange('blocked-apply', ['proposal']);
+
+      const result = await runCLI(['instructions', 'apply', '--change', 'blocked-apply'], {
+        cwd: tempDir,
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('Blocked');
+      expect(result.stdout).toContain('Missing artifacts: tasks');
+    });
+
+    it('outputs JSON for apply instructions', async () => {
+      await createTestChange('json-apply', ['proposal', 'design', 'specs', 'tasks']);
+
+      const result = await runCLI(
+        ['instructions', 'apply', '--change', 'json-apply', '--json'],
+        { cwd: tempDir }
+      );
+      expect(result.exitCode).toBe(0);
+
+      const json = JSON.parse(result.stdout);
+      expect(json.changeName).toBe('json-apply');
+      expect(json.schemaName).toBe('spec-driven');
+      expect(json.state).toBe('ready');
+      expect(json.contextFiles).toBeDefined();
+      expect(typeof json.contextFiles).toBe('object');
+    });
+
+    it('shows schema instruction from apply block', async () => {
+      await createTestChange('instr-apply', ['proposal', 'design', 'specs', 'tasks']);
+
+      const result = await runCLI(['instructions', 'apply', '--change', 'instr-apply'], {
+        cwd: tempDir,
+      });
+      expect(result.exitCode).toBe(0);
+      // Should show the instruction from spec-driven schema apply block
+      expect(result.stdout).toContain('work through pending tasks');
+    });
+
+    it('shows all_done state when all tasks are complete', async () => {
+      const changeDir = await createTestChange('done-apply', [
+        'proposal',
+        'design',
+        'specs',
+        'tasks',
+      ]);
+      // Overwrite tasks with all completed
+      await fs.writeFile(
+        path.join(changeDir, 'tasks.md'),
+        '## Tasks\n- [x] Task 1\n- [x] Task 2'
+      );
+
+      const result = await runCLI(['instructions', 'apply', '--change', 'done-apply'], {
+        cwd: tempDir,
+      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('complete ✓');
+      expect(result.stdout).toContain('ready to be archived');
+    });
+
+    it('uses tdd schema apply configuration', async () => {
+      // Create a TDD-style change with spec and tests
+      const changeDir = path.join(changesDir, 'tdd-apply');
+      await fs.mkdir(changeDir, { recursive: true });
+      await fs.writeFile(path.join(changeDir, 'spec.md'), '## Feature\nTest spec.');
+      const testsDir = path.join(changeDir, 'tests');
+      await fs.mkdir(testsDir, { recursive: true });
+      await fs.writeFile(path.join(testsDir, 'test.test.ts'), 'test("works", () => {})');
+
+      const result = await runCLI(
+        ['instructions', 'apply', '--change', 'tdd-apply', '--schema', 'tdd'],
+        { cwd: tempDir }
+      );
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('Schema: tdd');
+      // TDD schema has no task tracking, so should show schema instruction
+      expect(result.stdout).toContain('Run tests to see failures');
+    });
+
+    it('spec-driven schema uses apply block configuration', async () => {
+      // Verify that spec-driven schema uses its apply block (requires: [tasks])
+      await createTestChange('apply-config-test', ['proposal', 'design', 'specs', 'tasks']);
+
+      const result = await runCLI(
+        ['instructions', 'apply', '--change', 'apply-config-test', '--json'],
+        { cwd: tempDir }
+      );
+      expect(result.exitCode).toBe(0);
+
+      const json = JSON.parse(result.stdout);
+      // spec-driven schema has apply block with requires: [tasks], so should be ready
+      expect(json.schemaName).toBe('spec-driven');
+      expect(json.state).toBe('ready');
+    });
+
+    it('fallback: requires all artifacts when schema has no apply block', async () => {
+      // Create a minimal schema without an apply block in user schemas dir
+      const userDataDir = path.join(tempDir, 'user-data');
+      const noApplySchemaDir = path.join(userDataDir, 'openspec', 'schemas', 'no-apply');
+      const templatesDir = path.join(noApplySchemaDir, 'templates');
+      await fs.mkdir(templatesDir, { recursive: true });
+
+      // Minimal schema with 2 artifacts, no apply block
+      const schemaContent = `
+name: no-apply
+version: 1
+description: Test schema without apply block
+artifacts:
+  - id: first
+    generates: first.md
+    description: First artifact
+    template: first.md
+    requires: []
+  - id: second
+    generates: second.md
+    description: Second artifact
+    template: second.md
+    requires: [first]
+`;
+      await fs.writeFile(path.join(noApplySchemaDir, 'schema.yaml'), schemaContent);
+      await fs.writeFile(path.join(templatesDir, 'first.md'), '# First\n');
+      await fs.writeFile(path.join(templatesDir, 'second.md'), '# Second\n');
+
+      // Create a change with only the first artifact (missing second)
+      const changeDir = path.join(changesDir, 'no-apply-test');
+      await fs.mkdir(changeDir, { recursive: true });
+      await fs.writeFile(path.join(changeDir, 'first.md'), '# First artifact content');
+
+      // Run with XDG_DATA_HOME pointing to our temp user data dir
+      const result = await runCLI(
+        ['instructions', 'apply', '--change', 'no-apply-test', '--schema', 'no-apply', '--json'],
+        {
+          cwd: tempDir,
+          env: { XDG_DATA_HOME: userDataDir },
+        }
+      );
+      expect(result.exitCode).toBe(0);
+
+      const json = JSON.parse(result.stdout);
+      // Without apply block, fallback requires ALL artifacts - second is missing
+      expect(json.schemaName).toBe('no-apply');
+      expect(json.state).toBe('blocked');
+      expect(json.missingArtifacts).toContain('second');
+    });
+
+    it('fallback: ready when all artifacts exist for schema without apply block', async () => {
+      // Create a minimal schema without an apply block
+      const userDataDir = path.join(tempDir, 'user-data-2');
+      const noApplySchemaDir = path.join(userDataDir, 'openspec', 'schemas', 'no-apply-full');
+      const templatesDir = path.join(noApplySchemaDir, 'templates');
+      await fs.mkdir(templatesDir, { recursive: true });
+
+      const schemaContent = `
+name: no-apply-full
+version: 1
+description: Test schema without apply block
+artifacts:
+  - id: only
+    generates: only.md
+    description: Only artifact
+    template: only.md
+    requires: []
+`;
+      await fs.writeFile(path.join(noApplySchemaDir, 'schema.yaml'), schemaContent);
+      await fs.writeFile(path.join(templatesDir, 'only.md'), '# Only\n');
+
+      // Create a change with the artifact present
+      const changeDir = path.join(changesDir, 'no-apply-full-test');
+      await fs.mkdir(changeDir, { recursive: true });
+      await fs.writeFile(path.join(changeDir, 'only.md'), '# Content');
+
+      const result = await runCLI(
+        ['instructions', 'apply', '--change', 'no-apply-full-test', '--schema', 'no-apply-full', '--json'],
+        {
+          cwd: tempDir,
+          env: { XDG_DATA_HOME: userDataDir },
+        }
+      );
+      expect(result.exitCode).toBe(0);
+
+      const json = JSON.parse(result.stdout);
+      // All artifacts exist, should be ready with default instruction
+      expect(json.schemaName).toBe('no-apply-full');
+      expect(json.state).toBe('ready');
+      expect(json.instruction).toContain('All required artifacts complete');
+    });
+  });
+
   describe('help text', () => {
     it('marks status command as experimental in help', async () => {
       const result = await runCLI(['status', '--help']);