feat: add Agent Skills for experimental artifact workflow (#424)

* feat: add Agent Skills for experimental artifact workflow

Implements Task #3 from the experimental release plan:
- Create skill templates for openspec-new-change and openspec-continue-change
- Add artifact-experimental-setup CLI command
- Generate Agent Skills in .claude/skills/ directory
- Support cross-editor compatibility (Claude Code, Cursor, Windsurf)

Skills follow the Agent Skills specification and provide:
- Natural language invocation by AI assistants
- Step-by-step artifact creation workflow
- Dependency-driven change management

* fix: update GitHub issues URL to correct repository

Replace placeholder `https://github.com/your-org/openspec/issues`
with correct URL `https://github.com/Fission-AI/OpenSpec/issues` in:
- docs/experimental-release-plan.md
- src/commands/artifact-workflow.ts

Verified against package.json repository.url field.

* feat: add openspec-apply-change skill for task implementation

Add the apply skill to guide agents through implementing tasks from an
OpenSpec change:

- Add `openspec instructions apply` CLI command that parses tasks.md and
  returns context files, progress tracking, and dynamic instructions
- Add `getApplyChangeSkillTemplate()` to skill-templates.ts with full
  workflow guidance for implementing tasks
- Update artifact-experimental-setup to generate all three skills:
  openspec-new-change, openspec-continue-change, openspec-apply-change

The apply skill supports the fluid "actions on a change" model:
- Can be invoked anytime (if tasks.md exists)
- Handles blocked/ready/all_done states
- Guides agents to pause on issues and suggest artifact updates
- Tracks progress via task checkboxes

* docs: mark apply skill implementation steps as complete

* feat: add Capabilities section to proposal template

Enrich the proposal template to explicitly capture capability discovery:

- Add "Capabilities" section with "New Capabilities" and "Modified
  Capabilities" subsections to proposal template
- Update proposal instruction in schema.yaml to guide agents on
  researching existing specs and listing capabilities
- Update skill instructions with detailed guidance for the Capabilities
  section

This creates a clear contract between proposal and specs phases - each
capability listed in the proposal will need a corresponding spec file.

* feat: remove redundant `openspec next` command

The `next` command was redundant with `status` - both show which artifacts
are ready to create. The status command provides more context (done/ready/blocked)
and is the single source of truth for artifact state.

Changes:
- Remove nextCommand function and CLI registration from artifact-workflow.ts
- Update skill templates to use status instead of next
- Update docs and specs to reflect removal
- Add REMOVED Requirements section to cli-artifact-workflow spec
- Remove 7 tests for the next command

Migration: Use `openspec status --change <id> --json` and filter artifacts
with `status: "ready"` to find artifacts that can be created next.

* docs: clarify kebab-case naming in proposal template

Update HTML comments in the Capabilities section to explicitly instruct
using kebab-case identifiers with examples (user-auth, data-export,
api-rate-limiting).

* feat: add change proposals for per-change schema metadata

Add two related change proposals for enabling schema selection in the
experimental artifact workflow:

1. add-per-change-schema-metadata: Store schema choice in .openspec.yaml
   per change, enabling auto-detection in workflow commands. Includes
   Zod schema design and delta specs for cli-artifact-workflow.

2. add-agent-schema-selection: Follow-up to update agent skills to
   support dynamic schema selection (depends on metadata change).

Also includes:
- Example .openspec.yaml in add-frontmatter-to-openspec-artifact-files
- Clarify "Modified Capabilities" guidance in proposal template

* remove test change

* feat: fix design.md as optional, update docs, add schema-aware apply proposal

Changes:
- Fix generateApplyInstructions to treat design.md as optional (not required)
- Update experimental-release-plan.md CLI output to match implementation
- Add openspec-apply-change skill to docs (was missing)
- Fix test flow numbering after adding apply skill verification step
- Add change proposal for making apply instructions schema-aware

The schema-aware proposal introduces an `implementation` block in schema.yaml
to define when a change becomes implementable and how to track progress.

Author: TabishB

docs/experimental-release-plan.md

@@ -210,9 +210,7 @@ openspec new change add-auth --schema tdd
 # Auto-reads schema from change.yaml — no --schema needed
 openspec status --change add-auth
 # Output: "Change: add-auth (schema: tdd)"
-
-openspec next --change add-auth
-# Knows to use TDD artifacts
+# Shows which artifacts are ready/blocked/done
 
 # Explicit override still works (with informational message)
 openspec status --change add-auth --schema spec-driven

docs/schema-workflow-gaps.md

@@ -0,0 +1,26 @@
+## Why
+
+With per-change schema metadata in place (see `add-per-change-schema-metadata`), agents can now create changes with different workflow schemas. However, the agent skills are still hardcoded to `spec-driven` artifacts and don't offer schema selection to users.
+
+## What Changes
+
+**Scope: Experimental artifact workflow agent skills**
+
+**Depends on:** `add-per-change-schema-metadata` (must be implemented first)
+
+- Update `openspec-new-change` skill to prompt user for schema selection
+- Update `openspec-continue-change` skill to work with any schema's artifacts
+- Update `openspec-apply-change` skill to handle schema-specific task structures
+- Add schema descriptions to help users choose appropriate workflow
+
+## Capabilities
+
+### Modified Capabilities
+- `cli-artifact-workflow`: Agent skills support dynamic schema selection
+
+## Impact
+
+- **Affected code**: `src/core/templates/skill-templates.ts`
+- **User experience**: Users can choose TDD, spec-driven, or future workflows when starting a change
+- **Agent behavior**: Skills read artifact list from schema rather than hardcoding
+- **Backward compatible**: Default remains `spec-driven` if user doesn't choose

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

@@ -0,0 +1,32 @@
+## 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-agent-schema-selection/tasks.md

@@ -0,0 +1,147 @@
+## Context
+
+The experimental artifact workflow supports multiple schemas (`spec-driven`, `tdd`), but schema selection must be passed on every command. This creates friction for agents and users.
+
+We need a lightweight metadata file to persist the schema choice per change.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Store schema choice once at change creation
+- Auto-detect schema in experimental workflow commands
+- Maintain backward compatibility (no metadata = default)
+- Validate metadata with Zod schema
+
+**Non-Goals:**
+- Migrate existing changes (they use default)
+- Extend to legacy commands
+- Store additional metadata beyond schema (keep minimal for now)
+
+## Decisions
+
+### Decision: Zod Schema Design
+
+The metadata file (`.openspec.yaml`) will be validated with this Zod schema:
+
+```typescript
+// src/core/artifact-graph/types.ts (or new metadata.ts)
+
+import { z } from 'zod';
+import { listSchemas } from './resolver.js';
+
+/**
+ * Schema for per-change metadata stored in .openspec.yaml
+ */
+export const ChangeMetadataSchema = z.object({
+  // Required: which workflow schema this change uses
+  schema: z.string().min(1, { message: 'schema is required' }).refine(
+    (val) => listSchemas().includes(val),
+    (val) => ({ message: `Unknown schema '${val}'. Available: ${listSchemas().join(', ')}` })
+  ),
+
+  // Optional: creation timestamp (ISO date string)
+  created: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+    message: 'created must be YYYY-MM-DD format'
+  }).optional(),
+});
+
+export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
+```
+
+**Rationale:**
+- `schema` is required and validated against available schemas at parse time
+- `created` is optional, ISO date format for consistency
+- Minimal fields - can extend later without breaking existing files
+- Follows existing codebase pattern (see `ArtifactSchema`, `SchemaYamlSchema`)
+
+### Decision: File Location and Format
+
+**Location:** `openspec/changes/<name>/.openspec.yaml`
+
+**Format:**
+```yaml
+schema: tdd
+created: 2025-01-05
+```
+
+**Alternatives considered:**
+- `change.yaml` - less hidden, but clutters directory
+- Frontmatter in `proposal.md` - couples to proposal existence
+- `openspec.json` - YAML matches existing schema files
+
+### Decision: Read/Write Functions
+
+```typescript
+// src/utils/change-metadata.ts
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { ChangeMetadataSchema, type ChangeMetadata } from '../core/artifact-graph/types.js';
+
+const METADATA_FILENAME = '.openspec.yaml';
+
+export function writeChangeMetadata(
+  changeDir: string,
+  metadata: ChangeMetadata
+): void {
+  // Validate before writing
+  const validated = ChangeMetadataSchema.parse(metadata);
+  const content = yaml.stringify(validated);
+  fs.writeFileSync(path.join(changeDir, METADATA_FILENAME), content);
+}
+
+export function readChangeMetadata(
+  changeDir: string
+): ChangeMetadata | null {
+  const metaPath = path.join(changeDir, METADATA_FILENAME);
+
+  if (!fs.existsSync(metaPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(metaPath, 'utf-8');
+  const parsed = yaml.parse(content);
+
+  // Validate and return (throws ZodError if invalid)
+  return ChangeMetadataSchema.parse(parsed);
+}
+```
+
+### Decision: Schema Resolution Order
+
+When determining which schema to use:
+
+1. **Explicit `--schema` flag** (highest priority - user override)
+2. **`.openspec.yaml` metadata** (persisted choice)
+3. **Default `spec-driven`** (fallback)
+
+```typescript
+function resolveSchemaForChange(
+  changeDir: string,
+  explicitSchema?: string
+): string {
+  if (explicitSchema) return explicitSchema;
+
+  const metadata = readChangeMetadata(changeDir);
+  if (metadata?.schema) return metadata.schema;
+
+  return 'spec-driven';
+}
+```
+
+## Risks / Trade-offs
+
+- **Extra file per change** → Minimal overhead, hidden file
+- **YAML parsing dependency** → Already using `yaml` package for schema files
+- **Schema validation at read time** → Fail fast with clear error if corrupted
+
+## Migration Plan
+
+No migration needed:
+- Existing changes without `.openspec.yaml` continue to work (use default)
+- New changes created with `openspec new change --schema X` get metadata file
+
+## Open Questions
+
+- Should `openspec new change` prompt for schema interactively if not specified? (Leaning no - default is fine)

openspec/changes/add-per-change-schema-metadata/design.md

@@ -0,0 +1,29 @@
+## Why
+
+Currently, the schema (workflow type) must be passed via `--schema` flag on every experimental workflow command. This is repetitive and error-prone. Agents have no way to know which schema a change uses, so they default to `spec-driven` and cannot leverage alternative workflows like `tdd`.
+
+## What Changes
+
+**Scope: Experimental artifact workflow only** (`openspec new change`, `openspec status`, `openspec instructions`, `openspec templates`)
+
+- Store schema choice in `.openspec.yaml` metadata file when creating a change via `openspec new change`
+- Auto-detect schema from metadata in experimental workflow commands
+- Make `--schema` flag optional (override only, metadata takes precedence)
+- Add `--schema` option to `openspec new change` command
+
+**Not affected**: Legacy commands (`openspec validate`, `openspec archive`, `openspec list`, `openspec show`)
+
+## Capabilities
+
+### New Capabilities
+- `change-metadata`: Reading/writing per-change metadata files
+
+### Modified Capabilities
+- `cli-artifact-workflow`: Commands auto-detect schema from change metadata
+
+## Impact
+
+- **Affected code**: `src/utils/change-utils.ts`, `src/core/artifact-graph/instruction-loader.ts`, `src/commands/artifact-workflow.ts`
+- **Agent skills**: Can be simplified - no longer need to pass schema explicitly
+- **Backward compatible**: Changes without `.openspec.yaml` fall back to `spec-driven` default
+- **Isolation**: All changes contained within experimental workflow code; legacy commands untouched

openspec/changes/add-per-change-schema-metadata/proposal.md

@@ -0,0 +1,98 @@
+## ADDED Requirements
+
+### Requirement: Change Metadata
+
+The system SHALL store and validate per-change metadata in `.openspec.yaml` files using a Zod schema.
+
+#### Scenario: Metadata file created with new change
+
+- **WHEN** user runs `openspec new change add-feature --schema tdd`
+- **THEN** the system creates `.openspec.yaml` in the change directory
+- **AND** the file contains `schema: tdd` and `created: <YYYY-MM-DD>`
+
+#### Scenario: Metadata validated on read
+
+- **WHEN** the system reads `.openspec.yaml`
+- **AND** the `schema` field references an unknown schema
+- **THEN** the system displays a validation error listing available schemas
+
+#### Scenario: Metadata schema validation
+
+- **WHEN** `.openspec.yaml` contains invalid YAML or missing required fields
+- **THEN** the system displays a Zod validation error with details
+
+#### Scenario: Missing metadata file
+
+- **WHEN** a change directory has no `.openspec.yaml` file
+- **THEN** the system falls back to the default schema (`spec-driven`)
+
+## MODIFIED Requirements
+
+### Requirement: New Change Command
+
+The system SHALL create new change directories with validation and optional schema metadata.
+
+#### Scenario: Create valid change
+
+- **WHEN** user runs `openspec new change add-feature`
+- **THEN** the system creates `openspec/changes/add-feature/` directory
+- **AND** creates `.openspec.yaml` with `schema: spec-driven` (default)
+
+#### Scenario: Create change with schema
+
+- **WHEN** user runs `openspec new change add-feature --schema tdd`
+- **THEN** the system creates `openspec/changes/add-feature/` directory
+- **AND** creates `.openspec.yaml` with `schema: tdd`
+
+#### Scenario: Invalid schema on create
+
+- **WHEN** user runs `openspec new change add-feature --schema unknown`
+- **THEN** the system displays an error listing available schemas
+- **AND** does not create the change directory
+
+#### Scenario: Invalid change name
+
+- **WHEN** user runs `openspec new change "Add Feature"` with invalid name
+- **THEN** the system displays validation error with guidance
+
+#### Scenario: Duplicate change name
+
+- **WHEN** user runs `openspec new change existing-change` for an existing change
+- **THEN** the system displays an error indicating the change already exists
+
+#### Scenario: Create with description
+
+- **WHEN** user runs `openspec new change add-feature --description "Add new feature"`
+- **THEN** the system creates the change directory with description in README.md
+
+### Requirement: Schema Selection
+
+The system SHALL support custom schema selection for workflow commands, with automatic detection from change metadata.
+
+#### Scenario: Schema auto-detected from metadata
+
+- **WHEN** user runs `openspec status --change <id>` without `--schema`
+- **AND** the change has `.openspec.yaml` with `schema: tdd`
+- **THEN** the system uses the `tdd` schema
+
+#### Scenario: Explicit schema overrides metadata
+
+- **WHEN** user runs `openspec status --change <id> --schema spec-driven`
+- **AND** the change has `.openspec.yaml` with `schema: tdd`
+- **THEN** the system uses `spec-driven` (explicit flag wins)
+
+#### Scenario: Default schema fallback
+
+- **WHEN** user runs workflow commands without `--schema`
+- **AND** the change has no `.openspec.yaml` file
+- **THEN** the system uses the "spec-driven" schema
+
+#### Scenario: Custom schema via flag
+
+- **WHEN** user runs `openspec status --change <id> --schema tdd`
+- **THEN** the system uses the specified schema for artifact graph
+
+#### Scenario: Unknown schema
+
+- **WHEN** user specifies an unknown schema
+- **THEN** the system displays an error listing available schemas

openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,29 @@
+## 1. Zod Schema and Types
+
+- [ ] 1.1 Add `ChangeMetadataSchema` Zod schema to `src/core/artifact-graph/types.ts`
+- [ ] 1.2 Export `ChangeMetadata` type inferred from schema
+
+## 2. Core Metadata Functions
+
+- [ ] 2.1 Create `src/utils/change-metadata.ts` with `writeChangeMetadata()` function
+- [ ] 2.2 Add `readChangeMetadata()` function with Zod validation
+- [ ] 2.3 Update `createChange()` to accept optional `schema` param and write metadata
+
+## 3. Auto-Detection in Instruction Loader
+
+- [ ] 3.1 Modify `loadChangeContext()` to read schema from `.openspec.yaml`
+- [ ] 3.2 Make `schemaName` parameter optional (fall back to metadata, then default)
+
+## 4. CLI Updates
+
+- [ ] 4.1 Add `--schema <name>` option to `openspec new change` command
+- [ ] 4.2 Verify existing commands (`status`, `instructions`) work with auto-detection
+
+## 5. Tests
+
+- [ ] 5.1 Test `ChangeMetadataSchema` validates correctly (valid/invalid cases)
+- [ ] 5.2 Test `writeChangeMetadata()` creates valid YAML
+- [ ] 5.3 Test `readChangeMetadata()` parses and validates schema
+- [ ] 5.4 Test `loadChangeContext()` auto-detects schema from metadata
+- [ ] 5.5 Test fallback to default when no metadata exists
+- [ ] 5.6 Test `--schema` flag overrides metadata