Repository navigation
Questions about general workflow of this Openspec SDD #694
Description
Activity
Task completed.
I'll analyze this issue and the codebase to provide a helpful response. Let me gather relevant information.
Powered by 1Code
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 insrc/core/artifact-graph/graph.ts:118-134(getNextArtifactsmethod) — 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) inschemas/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:verifycommand 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.shin the current codebase. If you want to reference external skills for a specific change, here are your options:- In
openspec/config.yamlundercontext:— 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. Seesrc/core/project-config.tsfor the config schema. - In the design document — If the skill is relevant to how you're implementing a specific change, referencing it in
design.mdmakes sense since that's where implementation approach decisions go (per the schema instruction atschemas/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 yourtasks.mdand works through pending tasks. It operates independently of whether design/specs have changed. The apply logic is insrc/commands/workflow/instructions.ts:307-400(generateApplyInstructions).Here's the recommended approach if you're not satisfied with generated code:
- Revert the code changes you don't like (git checkout, undo, etc.)
- 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). - Run
/opsx:applyagain — it will pick up the remaining unchecked tasks and regenerate the code for those items.
You do not need to touch
design.mdor 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.mdwith 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.
Reacted by zchtcl- Manual edit: Open the artifact file (e.g.,
- added a commit that references this issue
on Jul 7, 2026 - added a commit that references this issue
on Jul 11, 2026 Welcome to OpenSpec, and thanks for the clear questions. All three have answers now, so closing.
-
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. -
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.mdfor that. -
Regenerating only the code without touching design. Yes.
/opsx:applyreads whatever the artifacts currently say each run, so if you leavedesign.mdalone and re-run apply (or just tell the agent what to redo), it rebuilds against the existing plan. No design edit required.
-
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!