Questions about general workflow of this Openspec SDD

[Stevefrdnt]

Hi everyone, I’m new to OpenSpec and have a few questions about using this SDD framework during development:

• The GitHub documentation mentions that the opsx flow generates documents in this order: proposal → design → task. If I need to update or change the content of a document, which opsx command should I use to regenerate it? Also, is it possible to regenerate a document even after the coding phase has started or been completed?

• If I want to use agent skills provided by Vercel’s skills.sh, where should I reference those skills for a specific change? Should it be included in the design document, or somewhere else?

• If I’m not satisfied with the generated code, is it possible to regenerate only the code without modifying the design document? If not, what would be the recommended approach in this situation?

Thanks in advance for your guidance!

[1code-async]

Task completed.

I'll analyze this issue and the codebase to provide a helpful response. Let me gather relevant information.

---

View full conversation

Powered by 1Code

[1code-async]

Hi @Stevefrdnt, welcome to OpenSpec! Here's a breakdown addressing each of your questions, with pointers into the codebase.

---

1. Regenerating / updating documents after they're created

The OPSX workflow is fluid, not phase-locked — you can update any artifact at any time by simply editing the file directly. The artifacts live as Markdown files inside your change directory (openspec/changes/<name>/).

There is no dedicated "regenerate" command. Instead, you have two main approaches:

• Manual edit: Open the artifact file (e.g., proposal.md, design.md, tasks.md) and update it directly. This is the intended approach since these are your source of truth.
• Re-run /opsx:continue: This command checks the artifact dependency graph and creates the next ready artifact that doesn't exist yet. If you delete an artifact file and run /opsx:continue, it will regenerate it. The dependency graph logic is in src/core/artifact-graph/graph.ts:118-134 (getNextArtifacts method) — it checks what's completed via filesystem existence.
• /opsx:ff (fast-forward): Creates all planning artifacts at once (proposal → specs → design → tasks). Same principle applies — it only creates artifacts that don't already exist.

Yes, you can update documents after coding has started or completed. The schema defines the dependency order (proposal → specs/design → tasks → apply) in schemas/spec-driven/schema.yaml, but this is for creation order, not a hard lock. You're free to go back and revise any artifact at any point. The /opsx:verify command can then validate that your implementation still aligns with the updated specs.

Also worth noting: issue #673 ("Clarify command — update existing artifacts before continue") and #684 ("How to update specifications during the apply phase?") discuss related workflows.

---

2. Referencing external agent skills (e.g., Vercel's skills.sh)

OpenSpec's skill system generates tool-specific skill files for 22+ AI tools (Claude Code, Cursor, Windsurf, GitHub Copilot, etc.) — see the adapter implementations in src/core/command-generation/adapters/.

However, there is no built-in integration with Vercel's skills.sh in the current codebase. If you want to reference external skills for a specific change, here are your options:

• In openspec/config.yaml under context: — This field (up to 50KB) is injected into every artifact instruction. You could document your external skill references here so the AI agent is aware of them during all phases. See src/core/project-config.ts for the config schema.
• In the design document — If the skill is relevant to how you're implementing a specific change, referencing it in design.md makes sense since that's where implementation approach decisions go (per the schema instruction at schemas/spec-driven/schema.yaml:89-110).
• In the proposal — If the skill fundamentally affects what you're building, mention it there.

The general principle: put it wherever it provides the most useful context for the AI agent working on that phase.

Issues #611, #689, and #590 have related discussion about skills architecture if you want to follow along.

---

3. Regenerating code without modifying the design document

Yes, this is possible. The apply phase (/opsx:apply) reads your tasks.md and works through pending tasks. It operates independently of whether design/specs have changed. The apply logic is in src/commands/workflow/instructions.ts:307-400 (generateApplyInstructions).

Here's the recommended approach if you're not satisfied with generated code:

1. Revert the code changes you don't like (git checkout, undo, etc.)
2. Uncheck the tasks in tasks.md (change [x] back to [ ]) for the items you want re-done. The apply phase tracks progress via checkbox parsing (instructions.ts:217-238).
3. Run /opsx:apply again — it will pick up the remaining unchecked tasks and regenerate the code for those items.

You do not need to touch design.md or any other planning artifact for this. The design doc only needs updating if you realize the approach itself was wrong (not just the implementation).

If the issue is more fundamental (e.g., the tasks themselves are wrong, not just the code), you may want to update tasks.md with better task descriptions before re-running apply. Issue #618 ("Best workflow to fix mistakes in a completed change?") has a related discussion.

---

Hope this helps you get started! The key mental model is: artifacts are just files, the dependency graph guides creation order, and you always have the freedom to edit/redo any part of the workflow.

[clay-good]

Welcome to OpenSpec, and thanks for the clear questions. All three have answers now, so closing.

1. Regenerating a document after it exists, even mid- or post-coding. Use /opsx:update: it revises a change's existing artifacts and keeps them coherent with each other. It ships in the default profile as of v1.6.0 (feat(skills): propose /opsx:update planning-artifact update skill #1278). You can run it at any point, including after implementation has started. Editing the file by hand works too; nothing is locked. Full guide: Editing & Iterating on a Change.

2. Referencing third-party skills (skills.sh) for a change. OpenSpec does not manage other tools' skills, so there is no OpenSpec file to register them in. You invoke them in your agent chat the way your tool normally exposes skills. Nothing needs to go in design.md for that.

3. Regenerating only the code without touching design. Yes. /opsx:apply reads whatever the artifacts currently say each run, so if you leave design.md alone and re-run apply (or just tell the agent what to redo), it rebuilds against the existing plan. No design edit required.