fission-ai__openspec/docs/experimental-release-plan.md

OpenSpec Experimental Release Plan

This document outlines the plan to release the experimental artifact workflow system for user testing.

Overview

The goal is to allow users to test the new artifact-driven workflow system alongside the existing OpenSpec commands. This experimental system (opsx) provides a more granular, step-by-step approach to creating change artifacts.

Three Workflow Modes

1. Old Workflow (Current Production)

• Commands: /openspec:proposal, /openspec:apply, /openspec:archive
• Behavior: Hardcoded slash commands that generate all artifacts in one command
• Status: Production, unchanged

2. New Artifact System - Batch Mode (Future)

• Commands: Refactored /openspec:proposal using schemas
• Behavior: Schema-driven but generates all artifacts at once (like legacy)
• Status: Not in scope for this experimental release
• Note: This is a future refactor to unify the old system with schemas

3. New Artifact System - Granular Mode (Experimental)

• Commands: /opsx:new, /opsx:continue
• Behavior: One artifact at a time, dependency-driven, iterative
• Status: Target for this experimental release

---

Work Items

1. Rename AWF to OPSX

Current State:

• Commands: /awf:start, /awf:continue
• Files: .claude/commands/awf/start.md, .claude/commands/awf/continue.md

Target State:

• Commands: /opsx:new, /opsx:continue
• Files: .claude/commands/opsx/new.md, .claude/commands/opsx/continue.md

Tasks:

• Create .claude/commands/opsx/ directory
• Rename start.md → new.md and update content
• Copy continue.md with updated references
• Update all references from "awf" to "opsx" in command content
• Update frontmatter (name, description) to use "opsx" naming
• Remove .claude/commands/awf/ directory

CLI Commands: The underlying CLI commands (openspec status, openspec instructions, etc.) remain unchanged. Only the slash command names change.

---

2. Remove WF Skill Files

Current State:

• .claude/commands/wf/start.md - References non-existent openspec wf commands
• .claude/commands/wf/continue.md - References non-existent openspec wf commands

Target State:

• Directory and files removed

Tasks:

• Delete .claude/commands/wf/start.md
• Delete .claude/commands/wf/continue.md
• Delete .claude/commands/wf/ directory

---

3. Add Agent Skills for Experimental Workflow

Purpose: Generate experimental workflow skills using the Agent Skills open standard.

Why Skills Instead of Slash Commands:

• Cross-editor compatibility: Skills work in Claude Code, Cursor, Windsurf, and other compatible editors automatically
• Simpler implementation: Single directory (.claude/skills/) instead of 18+ editor-specific configurators
• Standard format: Open standard with simple YAML frontmatter + markdown
• User invocation: Users explicitly invoke skills when they want to use them

Behavior:

1. Create .claude/skills/ directory if it doesn't exist
2. Generate two skills using the Agent Skills specification:
   • openspec-new-change/SKILL.md - Start a new change with artifact workflow
   • openspec-continue-change/SKILL.md - Continue working on a change (create next artifact)
3. Skills are added alongside existing /openspec:* commands (not replacing)

Supported Editors:

• Claude Code (native support)
• Cursor (native support via Settings → Rules → Import Settings)
• Windsurf (imports .claude configs)
• Cline, Codex, and other Agent Skills-compatible editors

Tasks:

• Create skill template content for openspec-new-change (based on current opsx:new)
• Create skill template content for openspec-continue-change (based on current opsx:continue)
• Add temporary artifact-experimental-setup command to CLI
• Implement skill file generation (YAML frontmatter + markdown body)
• Add success message with usage instructions

Note: The artifact-experimental-setup command is temporary and will be merged into openspec init once the experimental workflow is promoted to stable.

Skill Format: Each skill is a directory with a SKILL.md file:

.claude/skills/
├── openspec-new-change/
│   └── SKILL.md          # name, description, instructions
├── openspec-continue-change/
│   └── SKILL.md          # name, description, instructions
└── openspec-apply-change/
    └── SKILL.md          # name, description, instructions

CLI Interface:

openspec artifact-experimental-setup

# Output:
# 🧪 Experimental Artifact Workflow Skills Created
#
#   ✓ .claude/skills/openspec-new-change/SKILL.md
#   ✓ .claude/skills/openspec-continue-change/SKILL.md
#   ✓ .claude/skills/openspec-apply-change/SKILL.md
#
# 📖 Usage:
#
#   Skills work automatically in compatible editors:
#   • Claude Code - Auto-detected, ready to use
#   • Cursor - Enable in Settings → Rules → Import Settings
#   • Windsurf - Auto-imports from .claude directory
#
#   Ask Claude naturally:
#   • "I want to start a new OpenSpec change to add <feature>"
#   • "Continue working on this change"
#
#   Claude will automatically use the appropriate skill.
#
# 💡 This is an experimental feature.
#    Feedback welcome at: https://github.com/Fission-AI/OpenSpec/issues

Implementation Notes:

• Simple file writing: Create directories and write templated SKILL.md files (no complex logic)
• Use existing FileSystemUtils.writeFile() pattern like slash command configurators
• Template structure: YAML frontmatter + markdown body
• Keep existing /opsx:* slash commands for now (manual cleanup later)
• Skills use invocation model (user explicitly asks Claude to use them)
• Skill description field guides when Claude suggests using the skill
• Each SKILL.md has required fields: name (matches directory) and description

---

4. Update /opsx:new Command Content

Current Behavior (awf:start):

1. Ask user what they want to build (if no input)
2. Create change directory
3. Show artifact status
4. Show what's ready
5. Get instructions for proposal
6. STOP and wait

New Behavior (opsx:new): Same flow but with updated naming:

• References to "awf" → "opsx"
• References to /awf:continue → /opsx:continue
• Update frontmatter name/description

Tasks:

• Update all "awf" references to "opsx"
• Update command references in prompt text
• Verify CLI commands still work (they use openspec, not awf)

---

5. Update /opsx:continue Command Content

Current Behavior (awf:continue):

1. Prompt for change selection (if not provided)
2. Check current status
3. Create ONE artifact based on what's ready
4. Show progress and what's unlocked
5. STOP

New Behavior (opsx:continue): Same flow with updated naming.

Tasks:

• Update all "awf" references to "opsx"
• Update command references in prompt text

---

6. End-to-End Testing

Objective: Run through a complete workflow with Claude using the new skills to create a real feature, validating the entire flow works.

Test Scenario: Use a real OpenSpec feature as the test case (dog-fooding).

Test Flow:

1. Run openspec artifact-experimental-setup to create skills
2. Verify .claude/skills/openspec-new-change/SKILL.md created
3. Verify .claude/skills/openspec-continue-change/SKILL.md created
4. Verify .claude/skills/openspec-apply-change/SKILL.md created
5. Ask Claude: "I want to start a new OpenSpec change to add feature X"
6. Verify Claude invokes the openspec-new-change skill
7. Verify change directory created at openspec/changes/add-feature-x/
8. Verify proposal template shown
9. Ask Claude: "Continue working on this change"
10. Verify Claude invokes the openspec-continue-change skill
11. Verify proposal.md created with content
12. Ask Claude: "Continue" (create specs)
13. Verify specs/*.md created
14. Ask Claude: "Continue" (create design)
15. Verify design.md created
16. Ask Claude: "Continue" (create tasks)
17. Verify tasks.md created
18. Verify status shows 4/4 complete
19. Implement the feature based on tasks
20. Run /openspec:archive to archive the change

Validation Checklist:

• openspec artifact-experimental-setup creates correct directory structure
• Skills are auto-detected in Claude Code
• Skill descriptions trigger appropriate invocations
• Skills create change directory and show proposal template
• Skills correctly identify ready artifacts
• Skills create artifacts with meaningful content
• Dependency detection works (specs requires proposal, etc.)
• Progress tracking is accurate
• Template content is useful and well-structured
• Error handling works (invalid names, missing changes, etc.)
• Works with different schemas (spec-driven, tdd)
• Test in Cursor (Settings → Rules → Import Settings)

Document Results:

• Create test log documenting what worked and what didn't
• Note any friction points or confusing UX
• Identify bugs or improvements needed before user release

---

7. Documentation for Users

Create user-facing documentation explaining:

1. What is the experimental workflow?

   • A new way to create OpenSpec changes step-by-step using Agent Skills
   • One artifact at a time with dependency tracking
   • More interactive and iterative than the batch approach
   • Works across Claude Code, Cursor, Windsurf, and other compatible editors

2. How to set up experimental workflow

   openspec artifact-experimental-setup
   

   Note: This is a temporary command that will be integrated into openspec init once promoted to stable.

3. Available skills

   • openspec-new-change - Start a new change with artifact workflow
   • openspec-continue-change - Continue working (create next artifact)

4. How to use

   • Claude Code: Skills are auto-detected, just ask Claude naturally
     • "I want to start a new OpenSpec change to add X"
     • "Continue working on this change"
   • Cursor: Enable in Settings → Rules → Import Settings
   • Windsurf: Auto-imports .claude directory

5. Example workflow

   • Step-by-step walkthrough with natural language interactions
   • Show how Claude invokes skills based on user requests

6. Feedback mechanism

   • GitHub issue template for feedback
   • What to report (bugs, UX issues, suggestions)

Tasks:

• Create docs/experimental-workflow.md user guide
• Add GitHub issue template for experimental feedback
• Update README with mention of experimental features

---

Dependency Graph

1. Remove WF skill files
   └── (no dependencies)

2. Rename AWF to OPSX
   └── (no dependencies)

3. Add Agent Skills
   └── Depends on: Rename AWF to OPSX (uses opsx content as templates)

4. Update opsx:new content
   └── Depends on: Rename AWF to OPSX

5. Update opsx:continue content
   └── Depends on: Rename AWF to OPSX

6. E2E Testing
   └── Depends on: Add Agent Skills (tests the skills workflow)

7. User Documentation
   └── Depends on: E2E Testing (need to know final behavior)

---

Out of Scope

The following are explicitly NOT part of this experimental release:

1. Batch mode refactor - Making legacy /openspec:proposal use schemas
2. New schemas - Only shipping with existing spec-driven and tdd
3. Schema customization UI - No openspec schema list or similar
4. Multiple editor support in CLI - Skills work cross-editor automatically via .claude/skills/
5. Replacing existing commands - Skills are additive, not replacing /openspec:* or /opsx:*

---

Success Criteria

The experimental release is ready when:

1. openspec-new-change, openspec-continue-change, and openspec-apply-change skills work end-to-end
2. openspec artifact-experimental-setup creates skills in .claude/skills/
3. Skills work in Claude Code and are compatible with Cursor/Windsurf
4. At least one complete workflow has been tested manually
5. User documentation exists explaining how to generate and use skills
6. Feedback mechanism is in place
7. WF skill files are removed
8. No references to "awf" remain in user-facing content

---

Open Questions

1. Schema selection - Should opsx:new allow selecting a schema, or always use spec-driven?

   • Current: Always uses spec-driven as default
   • Consider: Add --schema tdd option or prompt

2. Namespace in CLI - Should experimental CLI commands be namespaced?

   • Current: openspec status, openspec instructions (no namespace)
   • Alternative: openspec opsx status (explicit experimental namespace)
   • Recommendation: Keep current, less typing for users

3. Deprecation path - If opsx becomes the default, how do we migrate?

   • Not needed for experimental release
   • Document that command names may change

---

Estimated Work Breakdown

Item	Complexity	Notes
Remove WF files	Trivial	Just delete 2 files + directory
Rename AWF → OPSX	Low	File renames + content updates
Add Agent Skills	Low	Simple: 3-4 files, single output directory, standard format
Update opsx:new content	Low	Text replacements
Update opsx:continue content	Low	Text replacements
E2E Testing	Medium	Manual testing, documenting results
User Documentation	Medium	New docs, issue template

Key Improvement: Switching to Agent Skills reduces complexity significantly:

• Before: 20+ files (type definitions, 18+ editor configurators, editor selection UI)
• After: 3-4 files (skill templates, simple CLI command)
• Cross-editor: Works automatically in Claude Code, Cursor, Windsurf without extra code

---

User Feedback from E2E Testing

What Worked Well

1. Clear dependency graph ⭐ HIGH PRIORITY - KEEP

   • The status command showing blocked/unblocked artifacts was intuitive:

     [x] proposal
     [ ] design
     [-] tasks (blocked by: design, specs)
     

   • Users always knew what they could work on next
   • Relevance: Core UX strength to preserve

2. Structured instructions output ⭐ HIGH PRIORITY - KEEP

   • openspec instructions <artifact> gave templates, output paths, and context in one call
   • Very helpful for understanding what to create
   • Relevance: Essential for agent-driven workflow

3. Simple scaffolding ✅ WORKS WELL

   • openspec new change "name" just worked - created directory structure without fuss
   • Relevance: Good baseline, room for improvement (see pain points)

---

Pain Points & Confusion

1. Redundant CLI calls ⚠️ MEDIUM PRIORITY

   • Users called both status AND next every time, but they overlap significantly
   • status already shows what's blocked
   • Recommendation: Consider merging or making next give actionable guidance beyond just listing names
   • Relevance: Reduces friction in iterative workflow

2. Specs directory structure was ambiguous 🔥 HIGH PRIORITY - FIX

   • Instructions said: Write to: .../specs/**/*.md
   • Users had to guess: specs/spec.md? specs/game/spec.md? specs/tic-tac-toe/spec.md?
   • Users ended up doing manual mkdir -p .../specs/tic-tac-toe then writing spec.md inside
   • Recommendation: CLI should scaffold this directory structure automatically
   • Relevance: Critical agent UX - ambiguous paths cause workflow friction

3. Repetitive --change flag ⚠️ MEDIUM PRIORITY

   • Every command needed --change "tic-tac-toe-game"
   • After 10+ calls, this felt verbose
   • Recommendation: openspec use "tic-tac-toe-game" to set context, then subsequent commands assume that change
   • Relevance: Quality of life improvement for iterative sessions

4. No validation feedback 🔥 HIGH PRIORITY - ADD

   • After writing each artifact, users just ran status hoping it would show [x]
   • Questions raised:
     • How did it know the artifact was "done"? File existence?
     • What if spec format was wrong (e.g., wrong heading levels)?
   • Recommendation: Add openspec validate --change "name" to check content quality
   • Relevance: Critical for user confidence and catching errors early

5. Query-heavy, action-light CLI 🔥 HIGH PRIORITY - ENHANCE

   • Most commands retrieve info. The only "action" is new change
   • Artifact creation is manual Write to guessed paths
   • Recommendation: openspec create proposal --change "name" could scaffold the file with template pre-filled, then user just edits
   • Relevance: Directly impacts agent productivity - reduce manual file writing

6. Instructions output was verbose ⚠️ LOW PRIORITY

   • XML-style output (<artifact>, <template>, <instruction>) was parseable but long
   • Key info (output path, template) was buried in ~50 lines
   • Recommendation: Add compact mode or structured JSON output for agents
   • Relevance: Nice-to-have for agent parsing efficiency

---

Workflow Friction

1. Mandatory "STOP and wait" after showing proposal template ⚠️ MEDIUM PRIORITY

   • The skill said "STOP and wait" after showing the proposal template
   • This felt overly cautious when user had already provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthetics")
   • Recommendation: Make the pause optional or conditional based on context clarity
   • Relevance: Reduces unnecessary round-trips in agent conversations

2. No connection to implementation 🔥 HIGH PRIORITY - ROADMAP ITEM

   • After 4/4 artifacts complete, then what? The workflow ends at planning
   • No openspec apply or guidance on how to execute the tasks
   • User asked "would you like me to implement?" but that's outside OpenSpec's scope currently
   • Recommendation: Add implementation bridge - either:
     • openspec apply command to start execution phase
     • Clear handoff to existing /openspec:apply workflow
     • Documentation on next steps after planning completes
   • Relevance: Critical missing piece - users expect end-to-end workflow

---

Priority Summary

MUST FIX (High Priority):

1. Specs directory structure ambiguity (#2)
2. Add validation feedback (#4)
3. Make CLI more action-oriented (#5)
4. Bridge to implementation phase (#2 in Workflow Friction)
5. Keep clear dependency graph (#1 in What Worked)
6. Keep structured instructions (#2 in What Worked)

SHOULD FIX (Medium Priority):

1. Reduce redundant CLI calls (#1)
2. Repetitive --change flag (#3)
3. Mandatory STOP behavior (#1 in Workflow Friction)

NICE TO HAVE (Low Priority):

1. Compact instructions output mode (#6)

---

Design Decisions (from E2E Testing Feedback)

Based on dev testing and analysis of agent workflow friction, we identified three blockers for experimental release and made the following decisions.

Blockers Identified

From the pain points in E2E testing, three issues are blocking the experimental release:

1. Specs directory ambiguity - Agents don't know where to write spec files or how to name capabilities
2. CLI is query-heavy - Most commands retrieve info, artifact creation is manual
3. Apply integration missing - After 4/4 artifacts complete, no guidance on implementation phase

Decision 1: Capability Discovery in Proposal (RESOLVED)

Problem: The specs artifact instruction says "Create one spec file per capability in specs/<name>/spec.md" but:

• Agent doesn't know what <name> should be
• Capability identification requires research (existing specs, codebase)
• Proposal template asks for "Affected specs" but doesn't structure it
• Research happens implicitly, output isn't captured

Decision: Enrich the proposal template to explicitly capture capability discovery.

Current proposal template:

## Why
## What Changes
## Impact
- Affected specs: List capabilities...  ← vague, easy to skip
- Affected code: ...

New proposal template:

## Why
## What Changes
## Capabilities

### New Capabilities
<!-- Capabilities being introduced (will create new specs/<name>/spec.md) -->
- `<name>`: <brief description of what this capability covers>

### Modified Capabilities
<!-- Existing capabilities being changed (will update existing specs) -->
- `<existing-name>`: <what's changing>

## Impact
<!-- Affected code, APIs, dependencies, systems -->

Rationale:

• Proposal already asks for capabilities (just poorly) - this makes it explicit
• Captured output is reviewable (vs implicit research that can't be verified)
• Creates clear contract between proposal and specs phases
• Distinguishes NEW vs MODIFIED upfront (critical for specs phase)
• Agent can't skip research - it's part of the deliverable

Implementation:

• Update schemas/spec-driven/templates/proposal.md
• Update proposal instruction in schemas/spec-driven/schema.yaml
• Update skill instructions to guide capability discovery

Decision 2: CLI Action Commands (IN PROGRESS)

Problem: CLI is mostly query-oriented. Agents run openspec status, openspec next, openspec instructions but then must manually write files.

Decision 2a: Remove openspec next command (RESOLVED)

Problem: The next command is redundant. It only shows which artifacts are ready, but status already shows this information (artifacts with status "ready" vs "blocked" vs "done").

Current behavior:

openspec status --change "X"  # Shows: proposal (done), specs (ready), design (blocked), tasks (blocked)
openspec next --change "X"    # Shows: ["specs"]  ← redundant

Decision: Remove the next command. Agents should use status which provides the same info plus more context.

Implementation:

• Remove next command from CLI
• Update skill instructions to use status instead of next
• Update AGENTS.md references

Decision 2b: CLI Scaffolding (RESOLVED - NO)

Problem: After getting instructions, agents manually write files. Should CLI scaffold artifacts instead?

Options considered:

• Add openspec create <artifact> commands that scaffold files with templates
• Keep current approach where agent writes files directly from instructions
• Hybrid: CLI can scaffold, agent can also write directly

Decision: Keep current flow. No scaffolding commands.

Rationale (from agent ergonomics perspective):

• One Write is better than multiple Edits - agent composes full content atomically
• instructions already provides template in context - scaffolding just moves it to a file
• Fewer tool calls: instructions + Write (2) vs create + instructions + Read + Edit×N (4+)
• Scaffolding doesn't solve the real problem (not knowing WHAT to write)
• Real problem solved by proposal template change (capability discovery)

For multi-file artifacts (specs): Scaffolding can't help because CLI doesn't know capability names until proposal is complete. The capability discovery in proposal solves this.

Decision 3: Apply Integration (RESOLVED)

Original problem: After planning completes (4/4 artifacts), the experimental workflow ends. No guidance on implementation.

Key insight: No phases, just actions.

Through discussion, we realized phases (planning → implementation → archive) are an artificial constraint. Work is fluid:

• You might start implementing, realize the design is wrong → update design.md
• You're halfway through tasks, discover a new requirement → update specs
• You bounce between "planning" and "implementing" constantly

The better model: Actions on a Change

A change is a thing (with artifacts). Actions are verbs you perform on a change. Actions aren't phases - they're fluid operations you can perform anytime.

Action	What it does	Skill	CLI Command
new	Create a change (scaffold directory)	opsx:new	openspec new change
continue	Create next artifact (dependency-aware)	opsx:continue	openspec instructions
apply	Implement tasks (execute, check off)	opsx:apply (NEW)	TBD
update	Refresh/update artifacts based on learnings	opsx:update (NEW)	TBD
explore	Research, ask questions, understand	opsx:explore (NEW)	TBD
validate	Check artifacts are correct/complete	TBD	openspec validate
archive	Finalize and move to archive	existing	openspec archive

Key principles:

• Actions are modeled as skills (primary interface for agents)
• Some skills have matching CLI commands for convenience
• Skills and CLI commands are decoupled - not everything needs both
• Actions can be performed in any order (with soft prerequisites)
• No linear phase gates

What the schema defines:

• Artifacts (what they are, where they go)
• Dependencies (what must exist first)
• Required vs optional
• Templates + instructions

What the schema does NOT define:

• Phases
• When you can modify things
• Linear workflow

Progress tracking:

• tasks.md checkboxes = implementation progress
• Artifact existence = planning progress
• Archive readiness = user decides (or all tasks done)

For experimental release:

• Create opsx:apply skill (guidance for implementing tasks)
• Document the "actions on a change" model
• Other actions (update, explore) can come later

---

Design: openspec-apply-change Skill

Overview

The apply skill guides agents through implementing tasks from a completed (or in-progress) change. Unlike the old /openspec:apply command, this skill:

• Is fluid - can be invoked anytime, not just after all artifacts are done
• Allows artifact updates - if implementation reveals issues, update design/specs
• Works until done - keeps going through tasks until complete or blocked
• Tracks progress via checkboxes - tasks.md is the source of truth

Skill Metadata

name: openspec-apply-change
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.

When to Invoke

The skill should be invoked when:

• User says "implement this change" or "start implementing"
• User says "work on the tasks" or "do the next task"
• User says "apply this change"
• All artifacts are complete and user wants to proceed
• User wants to continue implementation after a break

Input

• Optionally: change name
• Optionally: specific task number to work on
• If omitted: prompt for change selection (same pattern as continue-change)

Steps

**Steps**

1. **If no change name provided, prompt for selection**

   Run `openspec list --json` to get available changes. Use **AskUserQuestion** to let user select.

   Show changes that have tasks.md (implementation-ready).
   Mark changes with incomplete tasks as "(In Progress)".

2. **Get apply instructions**

   ```bash
   openspec instructions apply --change "<name>" --json

This returns:

• Context file paths (proposal, specs, design, tasks)
• Progress (total, complete, remaining)
• Task list with status
• Dynamic instruction based on current state

Handle states:

• If blocked (missing artifacts): show message, suggest openspec-continue-change
• If all done: congratulate, suggest archive
• Otherwise: proceed to implementation

3. Read context files

   Read the files listed in the instructions:

   • proposal.md - why and what
   • specs/*.md - requirements and scenarios
   • design.md - technical approach (if exists)
   • tasks.md - the implementation checklist

4. Show current progress

   Display:

   • Progress: "N/M tasks complete"
   • Remaining tasks overview
   • Dynamic instruction from CLI

5. Implement tasks (loop until done or blocked)

   For each pending task:

   • Show which task is being worked on
   • Make the code changes required
   • Keep changes minimal and focused
   • Mark task complete in tasks.md: - [ ] → - [x]
   • Continue to next task

   Pause if:

   • Task is unclear → ask for clarification
   • Implementation reveals a design issue → suggest updating artifacts
   • Error or blocker encountered → report and wait for guidance
   • User interrupts

6. On completion or pause, show status

   Display:

   • Tasks completed this session
   • Overall progress: "N/M tasks complete"
   • If all done: suggest archive
   • If paused: explain why and wait for guidance

#### Output Format

**During implementation:**

Implementing: add-user-auth

Working on task 3/7: Create UserAuth service class [...implementation happening...] ✓ Task complete

Working on task 4/7: Add login endpoint to AuthController [...implementation happening...] ✓ Task complete

Working on task 5/7: Add JWT token generation [...implementation happening...]

**On completion:**

Implementation Complete

Change: add-user-auth Progress: 7/7 tasks complete ✓

Completed This Session

• Create UserAuth service class
• Add login endpoint to AuthController
• Add JWT token generation
• Add logout endpoint
• Add auth middleware
• Write unit tests
• Update API documentation

All tasks complete! Ready to archive this change.

**On pause (issue encountered):**

Implementation Paused

Change: add-user-auth Progress: 4/7 tasks complete

Issue Encountered

Task 5 "Add JWT token generation" - the design specifies using RS256 but the existing auth library only supports HS256.

Options:

1. Update design.md to use HS256 instead
2. Add a new JWT library that supports RS256
3. Other approach

What would you like to do?

#### Guardrails

- Keep going through tasks until done or blocked
- Always read context before starting (specs, design)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess

#### Fluid Workflow Integration

The apply skill supports the "actions on a change" model:

**Can be invoked anytime:**
- Before all artifacts are done (if tasks.md exists)
- After partial implementation
- Interleaved with other actions (update, continue)

**Allows artifact updates:**
- If implementation reveals design issues → suggest `opsx:update` or manual edit
- If requirements need clarification → suggest updating specs
- Not phase-locked - work fluidly

**Example fluid workflow:**

User: "Implement add-user-auth" → openspec-apply-change: implements tasks 1, 2, 3, 4... → Pauses at task 5: "Design says RS256 but library only supports HS256"

User: "Let's use HS256 instead, update the design" → User edits design.md (or uses opsx:update in future)

User: "Continue implementing" → openspec-apply-change: implements tasks 5, 6, 7 → "All tasks complete! Ready to archive."

#### CLI Commands Used

```bash
openspec list --json                        # List changes for selection
openspec status --change "<name>"           # Check artifact completion
openspec instructions apply --change "<name>" # Get apply instructions (NEW)
# File reads via Read tool for proposal, specs, design, tasks
# File edits via Edit tool for checking off tasks

New CLI Command: openspec instructions apply

For consistency with artifact instructions.

Usage:

openspec instructions apply --change "<name>" [--json]

Output (Markdown format):

## Apply: add-user-auth

### Context Files
- proposal: openspec/changes/add-user-auth/proposal.md
- specs: openspec/changes/add-user-auth/specs/**/*.md
- design: openspec/changes/add-user-auth/design.md
- tasks: openspec/changes/add-user-auth/tasks.md

### Progress
2/7 complete

### Tasks
- [x] Create UserAuth service class
- [x] Add login endpoint
- [ ] Add JWT token generation
- [ ] Add logout endpoint
- [ ] Add auth middleware
- [ ] Write unit tests
- [ ] Update API documentation

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

Benefits of CLI command:

• Consistency - same pattern as openspec instructions <artifact>
• Structured output - progress, tasks, context paths in one call
• Clean format - markdown is readable and compact (vs verbose XML)
• Extensibility - can add more sections later if needed
• JSON option - --json flag available for programmatic use

Differences from Old /openspec:apply

Aspect	Old /openspec:apply	New openspec-apply-change
Invocation	After all artifacts done	Anytime (if tasks.md exists)
Granularity	All tasks at once	All tasks, but pauses on issues
Artifact updates	Not mentioned	Encouraged when needed
Progress tracking	Update all at end	Update after each task
Flow control	Push through everything	Pause on blockers, resume after
Context loading	Read once at start	Read context, reference as needed
Issue handling	Not specified	Pause, present options, wait for guidance

Implementation Notes

1. Add CLI command: Add openspec instructions apply to artifact-workflow.ts
   • Parse tasks.md for progress (count done/pending)
   • Return context paths, progress, task list, simple instruction
2. Add to skill-templates.ts: Create getApplyChangeSkillTemplate() function
3. Update artifact-experimental-setup: Generate this skill alongside new/continue
4. Update skills list: Add to .claude/skills/ directory
5. Test the flow: Verify it works with existing changes that have tasks.md

---

Next Steps

1. Review this plan and confirm scope (Done - blockers identified)
2. Design decisions (Done - all 3 blockers resolved)
3. Design apply skill (Done - documented above)
4. Implement proposal template change (Decision 1 - capability discovery) (Done)
5. Remove openspec next command (Decision 2a) (Done)
6. Add openspec instructions apply CLI command (Done)
7. Create openspec-apply-change skill (Done)
8. Conduct E2E testing with updated workflow
9. Write user docs (document "actions on a change" model)
10. Release to test users