openspec-continue-change hard-coded artifact patterns override schema instruction field

[pacaplan]

Problem

When a schema's instruction field directs the agent to invoke a specific skill (e.g., "IMPORTANT: You MUST use the flokay:design skill for this step."), the openspec-continue-change skill ignores this directive and writes the artifact directly using hard-coded patterns.

This means schemas cannot delegate artifact creation to custom skills — a critical capability for workflows like Flokay that require collaborative, multi-step processes (e.g., brainstorming approaches before writing a design document).

Root Cause

openspec-continue-change/SKILL.md lines 94-107 contain hard-coded artifact creation guidance that takes precedence over the schema's instruction field:

**Artifact Creation Guidelines**

The artifact types and their purpose depend on the schema. Use the `instruction` field
from the instructions output to understand what to create.

Common artifact patterns:

**spec-driven schema** (proposal → specs → design → tasks):
- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
- **specs/<capability>/spec.md**: Create one spec per capability...
- **design.md**: Document technical decisions, architecture, and implementation approach.
- **tasks.md**: Break down implementation into checkboxed tasks.

For other schemas, follow the `instruction` field from the CLI output.

The implicit logic: if the schema matches the "spec-driven" pattern, use the hard-coded one-liners; only fall back to the instruction field for "other schemas." Since most custom schemas (like Flokay) resemble the spec-driven pattern, the agent uses the hard-coded shortcut instead of reading the actual instruction.

openspec-ff-change/SKILL.md has a milder version of the same issue — line 88 says "Follow the instruction field" but lacks explicit guidance about skill invocation, so the agent treats "You MUST use skill X" as informational context rather than a directive to invoke a skill via the Skill tool.

Impact

• Schema authors cannot delegate artifact creation to custom skills
• The instruction field in schema.yaml artifacts is effectively ignored for common artifact types
• Workflows that require interactive/collaborative artifact creation (brainstorming, evaluation, multi-step design) are broken — the agent just writes the artifact directly

Expected Behavior

When openspec instructions <artifact-id> returns an instruction field that references a skill (e.g., "You MUST use the flokay:design skill"), the orchestrating skills should invoke that skill using the Skill tool instead of writing the artifact directly.

Suggested Fix

1. openspec-continue-change: Remove or demote the hard-coded artifact patterns (lines 98-107). Add explicit skill-delegation guidance: "If the instruction field references a skill (e.g., 'You MUST use the X skill'), invoke that skill using the Skill tool instead of writing the artifact yourself."

2. openspec-ff-change: Add the same skill-delegation guidance.

3. Consider a convention in the instruction field (e.g., skill: flokay:design) that the orchestrating skills can parse unambiguously, rather than relying on natural language detection of "You MUST use..." directives.

[1code-async]

Task completed.

The enrichment comment has been posted on issue #777. Here's a summary of what was included:

Key findings:

• Corrected file locations: The issue references SKILL.md files, but skills are actually TypeScript template functions in src/core/templates/workflows/continue-change.ts and ff-change.ts
• Confirmed root cause: Hard-coded spec-driven artifact patterns in lines 99–107 of continue-change.ts create a two-tier system that bypasses the schema's instruction field for common artifact names
• Traced the instruction flow: The CLI infrastructure (types.ts → instruction-loader.ts → instructions.ts) already correctly passes through custom instructions from schema.yaml — the problem is isolated to the skill templates
• Identified all files needing changes: Both skill templates and their command template variants (4 locations total)
• Related issue: [Proposal/Enhancement] Hardcoded spec format prevents custom schemas from working #666 is related but distinct — it addresses hardcoded parsing/validation patterns, while openspec-continue-change hard-coded artifact patterns override schema instruction field #777 addresses hardcoded creation patterns in orchestrating skills
• Suggested approach: Replace the hard-coded patterns with a directive to follow the instruction field, with explicit guidance about skill delegation via the Skill tool

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Codebase Context

The issue author references SKILL.md files, but in this codebase skills are defined as TypeScript template functions, not markdown files. The actual locations are:

• openspec-continue-change: src/core/templates/workflows/continue-change.ts — the getContinueChangeSkillTemplate() function (lines 9–124) and the getOpsxContinueCommandTemplate() command variant (lines 126–241)
• openspec-ff-change: src/core/templates/workflows/ff-change.ts — the getFfChangeSkillTemplate() function (lines 9–107) and the getOpsxFfCommandTemplate() command variant (lines 109–207)

Both templates embed their instructions as string literals in the instructions property of the returned SkillTemplate/CommandTemplate objects.

Confirming the Root Cause

continue-change.ts lines 95–108 — The "Artifact Creation Guidelines" section contains the hard-coded spec-driven artifact patterns:

Common artifact patterns:

**spec-driven schema** (proposal → specs → design → tasks):
- **proposal.md**: Ask user about the change if not clear...
- **specs/<capability>/spec.md**: Create one spec per capability...
- **design.md**: Document technical decisions...
- **tasks.md**: Break down implementation into checkboxed tasks.

For other schemas, follow the `instruction` field from the CLI output.

This creates a two-tier system: if the schema looks like spec-driven, use the hard-coded one-liners; otherwise, fall back to the instruction field. Custom schemas that use the same artifact names (proposal, specs, design, tasks) will match the hard-coded pattern even though their instruction fields may specify completely different behavior (e.g., delegating to a custom skill).

ff-change.ts line 89 says "Follow the instruction field" but has no guidance about what to do if the instruction references a skill to invoke. The agent will treat "You MUST use the flokay:design skill" as prose context rather than a directive to call the Skill tool.

How the instruction Field Flows

The schema-level instruction field is:

1. Defined as instruction: z.string().optional() in src/core/artifact-graph/types.ts:9 (part of ArtifactSchema)
2. Loaded by generateInstructions() in src/core/artifact-graph/instruction-loader.ts:268 via artifact.instruction
3. Output by openspec instructions <artifact-id> --json as the instruction JSON field
4. Rendered by printInstructionsText() in src/commands/workflow/instructions.ts:178–183 inside <instruction> tags

So the CLI infrastructure already correctly passes through custom instruction values from schema.yaml. The problem is entirely in the skill templates that don't respect the instruction when it conflicts with their hard-coded patterns.

Files That Need Changes

1. src/core/templates/workflows/continue-change.ts — Remove or deprioritize lines 99–107 (the hard-coded spec-driven artifact patterns). Add skill-delegation guidance: if the instruction field references a skill, invoke it via the Skill tool instead of writing the artifact directly. Both the skill template (line 95+) and command template (line 214+) need the same fix.

2. src/core/templates/workflows/ff-change.ts — Add explicit skill-delegation guidance in the "Artifact Creation Guidelines" section (line 87+) for both the skill template and command template (line 189+).

Related Issue

#666 — "[Proposal/Enhancement] Hardcoded spec format prevents custom schemas from working" — is closely related but distinct. #666 addresses hardcoded parsing and validation patterns (e.g., ## Requirements headers) that prevent custom spec formats from validating. This issue (#777) addresses hardcoded creation patterns in the orchestrating skills that prevent custom instruction fields from being followed. Both stem from the same root problem — hardcoded assumptions about the spec-driven schema — but affect different layers of the system.

Suggested Approach

1. Minimal fix: In the "Artifact Creation Guidelines" of both continue-change.ts and ff-change.ts, replace the hard-coded spec-driven patterns with a single directive:

   Follow the instruction field from openspec instructions output. If the instruction references a skill (e.g., "use the X:Y skill"), invoke that skill using the Skill tool instead of writing the artifact yourself.

2. Structured convention (optional, as the issue suggests): Support a machine-readable skill: prefix in the instruction field (e.g., skill: flokay:design) that the orchestrating skills can parse unambiguously. This would require a small change to the ArtifactSchema type in types.ts (adding a delegateSkill field) or a parsing convention in the skill templates.

3. Testing: Any change should be verified against both the default spec-driven schema (in schemas/spec-driven/schema.yaml) and a custom schema with skill-delegation instructions to ensure backward compatibility.