Support Rebuilding Downstream Artifacts from Modified Intermediate Files

[zzing1874]

Problem Statement

In the current OpenSpec workflow, once a proposal has been applied (via opsx-apply or similar), there is no built-in command to regenerate downstream artifacts (e.g., design.md, tasks.yaml, spec.yaml, or code) after modifying an upstream file like proposal.md or design.md.

For example:

1. I run opsx-new → generate proposal.md
2. I run opsx-continue → generates design.md → tasks.yaml → spec.yaml → code
3. I realize the generated implementation is incorrect or incomplete
4. I edit proposal.md (or design.md) to refine requirements or design
5. There is no command like opsx-rebuild --from=proposal to re-trigger the pipeline from that point onward

As a result, users are forced to:

• Manually craft prompts for their AI assistant to "reprocess from X file"
• Or delete downstream files and re-run opsx-continue (which may not be reliable or idempotent)
• Or write custom scripts to orchestrate regeneration

This breaks the promise of a declarative, spec-driven workflow, as the toolchain does not support iterative refinement of intermediate artifacts.

Expected Behavior

OpenSpec should provide a command (e.g., opsx-regen, opsx-rebuild, or opsx-ff) that allows users to:

# Regenerate everything starting from proposal.md
openspec regen --from proposal

# Or from design.md
openspec regen --from design

This command would:

• Re-parse the specified upstream file (proposal.md, design.md, etc.)
• Re-generate all dependent downstream artifacts in order
• Preserve user intent and avoid manual prompt engineering
• Integrate cleanly with the existing opsx workflow

Why This Matters

Iterative refinement of specs/designs is extremely common during real-world development. The inability to safely and automatically propagate changes from upstream documents undermines the core value proposition of Spec-Driven Development (SDD): “Edit the spec, not the code.”

Without this capability, teams are incentivized to either:

• Edit code directly (breaking SDD discipline), or
• Resort to error-prone manual AI prompting

Suggested Implementation

• Add a new subcommand (e.g., opsx-regen or enhance opsx-ff)
• Accept a --from flag indicating the starting artifact (proposal, design, tasks)
• Re-execute the generation pipeline from that stage forward
• Optionally back up or diff overwritten files for safety

Related Context

• Current commands like opsx-continue only resume from the last unexecuted step, not from a modified earlier step.
• Users currently work around this by hand-crafting AI prompts referencing specific files — which is fragile and non-scalable.

---

Thank you for considering this enhancement! This would significantly improve the usability and robustness of OpenSpec for iterative, AI-assisted development.

[1code-async]

Task completed.

The comment has been posted on issue #705. Here's a summary of what the analysis found:

Key findings:

1. Existing in-repo proposal — There's already an active change at openspec/changes/add-artifact-regeneration-support/proposal.md that addresses this exact problem with a detailed design covering staleness detection and regeneration capability.

2. 6 related open issues — Issues Clarify command (update existing artifacts before continue) #673, How to update specifications during the apply phase? #684, Questions about general workflow of this Openspec SDD #694, Best workflow to fix mistakes in a completed change? #618, Bug Report: spec-driven schema dependency order #695, and Agent does not ask for /ospx-continue #663 all describe overlapping pain points around the same fundamental gap: no built-in mechanism for iterative refinement of intermediate artifacts.

3. Implementation path — The existing ArtifactGraph infrastructure (getBuildOrder(), getNextArtifacts(), detectCompleted()) provides a solid foundation. The main gap is in state.ts where completion is determined solely by file existence with no modification time tracking, making staleness detection impossible today.

4. Recommendation — Consolidate requirements from this issue and the related ones into the existing change proposal rather than treating them as separate efforts.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Triage: Codebase Analysis

Existing Work

There is already an active change in the repo that addresses this exact problem:

📁 openspec/changes/add-artifact-regeneration-support/proposal.md

This proposal covers:

• Part 1: Staleness Detection — track dependency modification times and warn users when downstream artifacts are stale relative to their upstream dependencies
• Part 2: Regeneration Capability — add the ability to regenerate specific artifacts (three options explored: --regenerate flag on continue, a separate /opsx:regenerate command, or interactive prompts during /opsx:apply)
• Three technical approaches for tracking staleness: metadata file (.openspec-meta.json), YAML frontmatter in generated artifacts, or git-based mtime comparison

The proposal explicitly notes the same gap described in this issue: "The documentation claims you can 'update artifacts mid-flight and continue' but there's no mechanism that actually supports this."

Related Open Issues

This issue overlaps significantly with several existing issues:

Issue	Title	Overlap
#673	Clarify command (update existing artifacts before continue)	Requests /opsx-clarify to update artifacts mid-workflow without auto-continuing
#684	How to update specifications during the apply phase?	Same problem — incorrect generated code, no way to update specs mid-apply
#694	Questions about general workflow of this Openspec SDD	Directly asks "which opsx command regenerates a document after the flow has progressed?"
#618	Best workflow to fix mistakes in a completed change?	Realized a requirement was wrong post-apply, no clear path to fix
#695	Bug: spec-driven schema dependency order	Related — design only requires proposal (not specs), which affects the regeneration dependency chain

Relevant Code

Artifact dependency graph — The pipeline is defined in schemas/spec-driven/schema.yaml:

proposal (no deps) → specs (requires: proposal)
                    → design (requires: proposal)
                      → tasks (requires: specs, design)
                        → apply (requires: tasks)

Key implementation files:

• src/core/artifact-graph/graph.ts — ArtifactGraph class with getBuildOrder() (topological sort via Kahn's algorithm), getNextArtifacts(), getBlocked(). This is the foundation any regeneration command would build on.
• src/core/artifact-graph/state.ts:16-31 — detectCompleted() determines artifact completion purely by file existence on disk. There is no modification time tracking, which means there's currently no way to detect staleness.
• src/core/artifact-graph/types.ts — Core types (Artifact, CompletedSet, BlockedArtifacts)
• src/core/templates/skill-templates.ts — Skill templates for all /opsx:* commands. A new regeneration command would need a template added here.
• src/cli/index.ts — CLI command definitions (Commander.js). New subcommand would be registered here.

Implementation Notes

The --from flag proposed in this issue maps well to the existing graph infrastructure. A possible approach:

1. Given --from=proposal, use ArtifactGraph.getBuildOrder() to get the topological order
2. Find all artifacts at or after proposal in the build order
3. Delete (or back up) those downstream files
4. detectCompleted() will then naturally show them as incomplete
5. getNextArtifacts() will return them as ready (in dependency order)
6. The existing /opsx:continue or /opsx:ff flow can then regenerate them

The main gap is staleness detection — state.ts currently only checks fs.existsSync() with no timestamp tracking. The existing proposal's Option A (.openspec-meta.json metadata file) or Option C (git-based) would need to be implemented first.

Suggestion

This issue is a near-duplicate of the work already planned in openspec/changes/add-artifact-regeneration-support/. Consider consolidating the requirements from this issue (#705) and the related issues (#673, #684, #694, #618) into that existing change to capture all the use cases in one place. The --from flag idea from this issue is a useful addition to the existing proposal's options.