feat: add /opsx:ff command for fast-forward artifact creation

[TabishB]

Summary

• Adds /opsx:ff command that creates all artifacts needed for implementation in one go
• Exposes applyRequires in openspec status --json output so agents know when to stop
• Schema-agnostic: uses each schema's apply.requires configuration

Changes

• instruction-loader.ts: Add applyRequires field to ChangeStatus interface and formatChangeStatus()
• skill-templates.ts: Add templates for ff skill and command
• artifact-workflow.ts: Register the new templates in setup command

Test plan

• Build passes
• Run openspec artifact-experimental-setup and verify /opsx:ff appears in output
• Run openspec status --change <name> --json and verify applyRequires field exists
• Test /opsx:ff command creates artifacts until apply-ready state

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added fast-forward artifact workflow support with dedicated skill and command templates.
  • Introduced new /opsx:ff slash command for expedited artifact operations.
  • Extended help documentation to surface the new fast-forward command option to users.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR introduces fast-forward (ff) artifact support by adding new template functions for ff skills and commands, integrating them into the experimental artifact workflow, and extending the ChangeStatus interface with an applyRequires field to track artifact dependencies for the apply phase.

Changes

Cohort / File(s)	Summary
Template Functions src/core/templates/skill-templates.ts	Adds two new public functions: getFfChangeSkillTemplate() and getOpsxFfCommandTemplate() that define fast-forward OpenSpec workflows. ⚠️ Duplicate declarations — both functions appear twice in the file, requiring verification and cleanup.
Workflow Integration src/commands/artifact-workflow.ts	Adds imports for the new ff template functions and wires them into the experimental setup by creating ffChangeSkill and ffCommand instances, adding them to generated lists, and extending help text with /opsx:ff command option.
Data Model src/core/artifact-graph/instruction-loader.ts	Extends ChangeStatus interface with new applyRequires: string[] field. The formatChangeStatus() function now computes this field from schema.apply.requires (or defaults to all artifact IDs) and includes it in the returned status object.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: add slash commands to artifact-experimental-setup #442 — Adds OPSX slash-command templates and integrates them into artifact-workflow.ts; this PR extends that work with the ff command variant.
• feat: enhance artifact instructions with inline guidance and XML output #422 — Modifies instruction-loader.ts and artifact-workflow.ts; this PR extends the ChangeStatus interface with applyRequires, aligning with related instruction changes.
• feat: add Agent Skills for experimental artifact workflow #424 — Modifies both skill-templates.ts and artifact-workflow.ts to add experimental agent skill templates; overlaps with the template and workflow wiring patterns in this PR.

Poem

🐰 Fast-forward, swift and true,
New templates hoppin' through,
Artifacts skip and bound,
With applyRequires 'round,
The ff path blazes anew! 🚀

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: introducing a new /opsx:ff command for fast-forward artifact creation, which aligns with the primary objectives and file modifications across all changed files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/core/artifact-graph/instruction-loader.ts (1)

257-259: Consider caching the schema in ChangeContext to avoid redundant resolution.

resolveSchema is called here, but loadChangeContext already calls it internally (line 168). The schema isn't exposed in ChangeContext, forcing this duplicate resolution. While likely low-cost for an in-memory lookup, you could consider extending ChangeContext to include the resolved schema if this pattern repeats elsewhere.

The fallback logic (schema.apply?.requires ?? schema.artifacts.map(a => a.id)) is correct—defaulting to all artifact IDs when no explicit apply.requires is configured.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d737057 and 15f8fe1.

📒 Files selected for processing (3)

• src/commands/artifact-workflow.ts
• src/core/artifact-graph/instruction-loader.ts
• src/core/templates/skill-templates.ts

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`

Applied to files:

• src/core/templates/skill-templates.ts

🧬 Code graph analysis (2)

src/core/artifact-graph/instruction-loader.ts (1)

src/core/artifact-graph/index.ts (1)

• resolveSchema (22-22)

src/commands/artifact-workflow.ts (1)

src/core/templates/skill-templates.ts (3)

• getFfChangeSkillTemplate (367-456)
• getOpsxNewCommandTemplate (473-542)
• getOpsxFfCommandTemplate (822-913)

🔇 Additional comments (7)

src/core/artifact-graph/instruction-loader.ts (1)

102-103: LGTM! Well-documented interface extension.

The applyRequires field is clearly documented and provides the necessary data for the fast-forward workflow to determine when to stop creating artifacts.

src/core/templates/skill-templates.ts (2)

363-456: FF skill skips schema selection—verify this is intentional.

The /opsx:new command (line 506-508) prompts the user to select a schema and passes --schema to openspec new change. However, getFfChangeSkillTemplate (line 388) uses openspec new change "<name>" without --schema, defaulting to spec-driven.

If this is intentional for speed (fast-forward should minimize prompts), consider documenting this behavior in the template description. Otherwise, you may want to add schema selection or accept a schema parameter:

 2. **Create the change directory**
    \`\`\`bash
-   openspec new change "<name>"
+   openspec new change "<name>" --schema "spec-driven"
    \`\`\`
-   This creates a scaffolded change at \`openspec/changes/<name>/\`.
+   This creates a scaffolded change at \`openspec/changes/<name>/\` using the default spec-driven schema.

---

819-912: LGTM! Slash command template is consistent with the skill template.

The /opsx:ff command template mirrors the skill template logic and provides clear instructions for the fast-forward workflow. The guardrails and artifact creation guidelines are well-defined.

One minor note: line 910 says "ask if user wants to continue it or create a new one" while the skill template (line 453) says "suggest continuing that change instead"—the command version is slightly more interactive, which is appropriate for a slash command.

src/commands/artifact-workflow.ts (4)

31-31: LGTM! Import statement properly extended.

The new template functions are correctly imported alongside the existing ones.

---

799-812: LGTM! FF skill and command properly integrated.

The fast-forward skill and command templates are correctly instantiated and added to their respective arrays, following the established patterns for newChangeSkill, continueChangeSkill, and applyChangeSkill.

---

836-840: LGTM! Command file naming is consistent.

The ff.md filename follows the pattern of other commands (new.md, continue.md, apply.md).

---

896-896: LGTM! Help text properly documents the new command.

The /opsx:ff command is added to the usage instructions with a clear description matching the PR objectives.

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.