fission-ai__openspec/openspec/changes/make-apply-instructions-schema-aware/proposal.md

Why

The generateApplyInstructions function is hardcoded to check for spec-driven artifacts (proposal.md, specs/, design.md, tasks.md). If a user selects a different schema like tdd, the apply instructions are meaningless - they check for files that don't exist in that schema.

This blocks the experimental workflow from supporting multiple schemas properly.

What Changes

Scope: Experimental artifact workflow (openspec instructions apply)

Depends on: add-per-change-schema-metadata (to know which schema a change uses)

• Make generateApplyInstructions read artifact definitions from the schema
• Dynamically determine which artifacts exist based on schema
• Define when a change becomes "implementable" (see Design Decision below)
• Generate schema-appropriate context files and instructions

Design Decision: When is a change implementable?

This is the key question. Different approaches:

Option A: Explicit apply artifact in schema

Add a field to mark which artifact is the "implementation gate":

artifacts:
  - id: tasks
    generates: tasks.md
    apply: true  # ← This artifact triggers apply mode

Pros: Explicit, flexible Cons: Another field to maintain, what if multiple artifacts are apply: true?

Option B: Leaf artifacts are implementable

The artifact(s) with no dependents (nothing depends on them) are the apply target.

• spec-driven: tasks is a leaf → apply = execute tasks
• tdd: docs is a leaf → but that doesn't make sense for TDD...

Pros: No extra schema field, derived from graph Cons: Doesn't match TDD semantics (implementation is the action, not docs)

Option C: Schema-level apply_phase definition

Add a top-level field to the schema:

name: spec-driven
apply_phase:
  requires: [tasks]  # Must exist before apply
  tracks: tasks.md   # File with checkboxes to track
  instruction: "Work through tasks, mark complete as you go"

name: tdd
apply_phase:
  requires: [tests]  # Must have tests before implementing
  tracks: null       # No checkbox tracking - just make tests pass
  instruction: "Run tests, implement until green, refactor"

Pros: Full flexibility, schema controls its own apply semantics Cons: More complex schema format

Option D: Convention-based (artifact ID matching)

If artifact ID is tasks or implementation, it's the apply target.

Pros: Simple, no schema changes Cons: Brittle, doesn't work for custom schemas

Option E: All artifacts complete → apply available

Apply becomes available when ALL schema artifacts exist. Implementation is whatever the user does after planning.

Pros: Simple, no schema changes Cons: Doesn't guide what "apply" means for different workflows

---

Decision: Add apply block to schema.yaml

Add a top-level apply field to schema definitions:

name: spec-driven
version: 1
description: Default OpenSpec workflow

artifacts:
  # ... existing artifacts ...

apply:
  requires: [tasks]           # Artifacts that must exist before apply
  tracks: tasks.md            # File with checkboxes for progress (optional)
  instruction: |              # Guidance shown to agent
    Read context files, work through pending tasks, mark complete as you go.
    Pause if you hit blockers or need clarification.

name: tdd
version: 1
description: Test-driven development workflow

artifacts:
  # ... existing artifacts ...

apply:
  requires: [tests]           # Must have tests before implementing
  tracks: null                # No checkbox tracking
  instruction: |
    Run tests to see failures. Implement minimal code to pass each test.
    Refactor while keeping tests green.

Key properties:

• requires: Array of artifact IDs that must exist before apply is available
• tracks: Path to file with checkboxes (relative to change dir), or null if no tracking
• instruction: Custom guidance for the apply phase

Fallback behavior: Schemas without apply block default to "all artifacts must exist"

Capabilities

Modified Capabilities

• cli-artifact-workflow: Apply instructions become schema-aware

Impact

• Affected code: src/commands/artifact-workflow.ts (generateApplyInstructions)
• Schema format: May need new apply_phase field
• Existing schemas: Need to add apply_phase to spec-driven and tdd
• Backward compatible: Schemas without apply_phase can use default behavior