feat: add /opsx:sync command for syncing delta specs to main specs #450
Conversation
Add a new agent-driven skill that syncs delta specs from a change to main specs without requiring archiving. This enables: - Updating main specs during active development - Intelligent merging (partial updates, adding scenarios) - Idempotent operation (safe to run multiple times) Implementation: - Extract shared specs-apply logic from archive.ts to specs-apply.ts - Add getSyncSpecsSkillTemplate and getOpsxSyncCommandTemplate - Register /opsx:sync in artifact-experimental-setup - Add specs-sync-skill main spec
📝 WalkthroughWalkthroughThis PR decouples spec syncing from archiving by extracting shared spec-application logic from Changes
Sequence DiagramsequenceDiagram
participant Agent
participant Skill as Skill System<br/>(artifact-workflow)
participant FS as Filesystem
participant Validator
Agent->>Skill: /opsx:sync [changeName]
Skill->>FS: findSpecUpdates(changeDir, mainSpecsDir)
FS-->>Skill: SpecUpdate[] (delta specs found)
loop For each SpecUpdate
Skill->>FS: Read delta spec
FS-->>Skill: Delta content
Skill->>Skill: buildUpdatedSpec:<br/>parse, validate ADDED/MODIFIED/REMOVED/RENAMED,<br/>apply in sequence, reconstruct
alt New capability
Skill->>FS: Create skeleton spec
end
opt skipValidation = false
Skill->>Validator: Validate rebuilt spec
Validator-->>Skill: Validation result
end
Skill->>FS: writeUpdatedSpec(updated content)
end
Skill-->>Agent: SpecsApplyOutput<br/>(per-capability summary,<br/>totals: added/modified/<br/>removed/renamed)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
Pre-merge checks✅ Passed checks (3 passed)
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. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @openspec/changes/add-specs-apply-command/tasks.md:
- Around line 17-24: The task docs list a skill named "openspec-specs-apply" and
command "/opsx:specs" but the implemented template functions in
skill-templates.ts register "openspec-sync-specs" and "/opsx:sync"; update one
side for consistency: either rename the implementation (e.g., change
getSpecsApplySkillTemplate()/registered skill name and slash command strings to
"openspec-specs-apply" and "/opsx:specs") or update the tasks.md checklist to
reference "openspec-sync-specs" and "/opsx:sync" so the skill template name and
slash command string in skill-templates.ts match the documentation.
🧹 Nitpick comments (6)
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.md (1)
6-9: Optional: Clarify the default (non-JSON) summary output format.Line 9 states the system "displays a summary of changes made" but doesn't specify the format. You could either reference the format defined in the specs-apply-skill spec (requirement counts for added/modified/removed/renamed) or document the human-readable format inline. The JSON structure is clear, so a parallel description for the default format would improve implementation clarity.
src/core/templates/skill-templates.ts (1)
458-594: Significant code duplication with getOpsxSyncCommandTemplate.The instructions content in this function is nearly identical to the content in
getOpsxSyncCommandTemplate()(lines 1053-1190), with ~130 lines duplicated. Consider extracting the shared instruction content into a helper function or constant to maintain DRY principles.🔎 Suggested refactoring approach
Extract the shared instruction content:
+const SYNC_SPECS_INSTRUCTIONS = `Sync delta specs from a change to main specs. + +This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement). + +**Input**: Optionally specify a change name. If omitted, MUST prompt for available changes. + +... [rest of shared content] +`; export function getSyncSpecsSkillTemplate(): SkillTemplate { return { name: 'openspec-sync-specs', description: 'Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.', - instructions: `Sync delta specs from a change to main specs. - - This is an **agent-driven** operation...` + instructions: SYNC_SPECS_INSTRUCTIONS }; } export function getOpsxSyncCommandTemplate(): CommandTemplate { return { name: 'OPSX: Sync', description: 'Sync delta specs from a change to main specs', category: 'Workflow', tags: ['workflow', 'specs', 'experimental'], - content: `Sync delta specs from a change to main specs...` + content: SYNC_SPECS_INSTRUCTIONS }; }openspec/changes/add-specs-apply-command/proposal.md (1)
1-3: Consider condensing the Why section to 1-2 sentences.According to coding guidelines for
openspec/changes/*/proposal.md, the Why section should be 1-2 sentences. The current version has 3 sentences. Consider merging the first two sentences for better conciseness.🔎 Suggested condensed version
## Why -Spec application is currently bundled with archive - users must run `openspec archive` to apply delta specs to main specs. This couples two distinct concerns (applying specs vs. archiving the change) and forces users to wait until they're "done" to see main specs updated. Users want the flexibility to apply specs earlier in the workflow while iterating. +Spec application is currently bundled with archive, coupling two distinct concerns (applying specs vs. archiving) and forcing users to wait until they're "done" to see main specs updated. Users want the flexibility to apply specs earlier in the workflow while iterating.Based on learnings.
src/core/specs-apply.ts (3)
244-255: Consider preserving original casing in RENAMED header.Line 245 uses the normalized
tovalue for the new header. IfnormalizeRequirementNameonly trims whitespace (per the relevant code snippet), this should be fine. However, if normalization changes casing in the future, this could cause unexpected header formatting.Consider using
r.to(the original value from the plan) instead ofto(the normalized value) for the header text:- const newHeader = `### Requirement: ${to}`; + const newHeader = `### Requirement: ${r.to}`;
445-464: Code duplication withwriteUpdatedSpec.The write and logging logic here (lines 447-457) duplicates what's in
writeUpdatedSpec(lines 347-357). Consider refactoring to usewriteUpdatedSpecwhen not in dry-run mode, or extracting a shared helper that accepts asilentoption.This isn't blocking since the current implementation is correct, but reduces maintainability.
388-396: Error handling may mask underlying issues.The catch block on lines 394-396 throws a generic "Change not found" error regardless of the actual failure reason. Permission errors (EACCES) or other I/O errors would be misreported as "not found."
Consider checking the error code:
🔎 Proposed fix
try { const stat = await fs.stat(changeDir); if (!stat.isDirectory()) { throw new Error(`Change '${changeName}' not found.`); } - } catch { - throw new Error(`Change '${changeName}' not found.`); + } catch (err: any) { + if (err.code === 'ENOENT') { + throw new Error(`Change '${changeName}' not found.`); + } + throw err; }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
openspec/changes/add-specs-apply-command/.openspec.yamlopenspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/specs/specs-sync-skill/spec.mdsrc/commands/artifact-workflow.tssrc/core/archive.tssrc/core/specs-apply.tssrc/core/templates/skill-templates.ts
🧰 Additional context used
📓 Path-based instructions (5)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.md
openspec/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Files:
openspec/specs/specs-sync-skill/spec.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/add-specs-apply-command/proposal.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/add-specs-apply-command/tasks.md
🧠 Learnings (16)
📓 Common learnings
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>/`
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
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/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
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/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
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/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
📚 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/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdsrc/core/archive.tsopenspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/.openspec.yamlsrc/core/specs-apply.ts
📚 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:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdsrc/core/templates/skill-templates.tssrc/core/archive.tsopenspec/changes/add-specs-apply-command/design.mdsrc/commands/artifact-workflow.tsopenspec/changes/add-specs-apply-command/.openspec.yamlsrc/core/specs-apply.ts
📚 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: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdsrc/core/archive.tsopenspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/.openspec.yamlsrc/core/specs-apply.ts
📚 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/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/.openspec.yamlsrc/core/specs-apply.ts
📚 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/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdsrc/core/archive.tsopenspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/.openspec.yamlsrc/core/specs-apply.ts
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/.openspec.yaml
📚 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/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/.openspec.yamlsrc/core/specs-apply.ts
📚 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: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/proposal.md
📚 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/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.md
📚 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/**/specs/**/spec.md : Use `#### Scenario: Name` format (4 hashtags) for scenario headers, not bullets or bold text
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.md
📚 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/specs/**/spec.md : Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Applied to files:
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
📚 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/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/add-specs-apply-command/tasks.md
📚 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: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
openspec/changes/add-specs-apply-command/design.md
📚 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: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
openspec/changes/add-specs-apply-command/.openspec.yaml
🧬 Code graph analysis (3)
src/core/archive.ts (1)
src/core/specs-apply.ts (3)
findSpecUpdates(56-95)buildUpdatedSpec(101-337)writeUpdatedSpec(342-358)
src/commands/artifact-workflow.ts (1)
src/core/templates/skill-templates.ts (2)
getSyncSpecsSkillTemplate(462-594)getOpsxSyncCommandTemplate(1056-1190)
src/core/specs-apply.ts (2)
src/core/parsers/requirement-blocks.ts (4)
parseDeltaSpec(119-142)normalizeRequirementName(15-17)extractRequirementsSection(24-97)RequirementBlock(1-5)src/core/validation/validator.ts (1)
Validator(16-449)
🔇 Additional comments (22)
openspec/changes/add-specs-apply-command/.openspec.yaml (1)
1-2: Config file correctly scaffolded.The spec-driven change metadata is properly set up.
openspec/changes/add-specs-apply-command/specs/cli-artifact-workflow/spec.md (1)
1-29: Spec structure and scenario coverage look excellent.The requirement is well-scoped with comprehensive scenarios covering the CLI interface, success paths, error handling, and alternate modes (JSON, dry-run).
openspec/changes/add-specs-apply-command/specs/specs-apply-skill/spec.md (1)
1-67: Comprehensive skill specification with thorough delta reconciliation coverage.This spec is excellent: three well-scoped requirements, 11 scenarios total covering the primary skill behavior, all delta operation types (ADDED/MODIFIED/REMOVED/RENAMED), idempotent operation, change selection prompting, and output formatting. The scenarios are detailed and implementable.
Strengths:
- Requirement 2 (Delta Reconciliation Logic) exhaustively covers all delta operations including the edge case of ADDED requirements that already exist (lines 30–33), which is important for idempotency.
- Requirement 3 provides clear output expectations for both changed and no-change cases (lines 57–67).
- All scenario headers follow the required
#### Scenario: Nameformat (4 hashtags).openspec/specs/specs-sync-skill/spec.md (3)
8-26: LGTM! Well-defined requirement with comprehensive scenarios.The requirement properly defines the
/opsx:syncskill with clear scenarios covering the basic operation, idempotency, and user interaction. The explicit mention of idempotency (lines 17-20) is particularly important for ensuring reliable behavior.
27-58: LGTM! Comprehensive delta reconciliation logic.The requirement thoroughly covers all delta operation types (ADDED, MODIFIED, REMOVED, RENAMED) with clear scenarios. The handling of the edge case where an ADDED requirement already exists (lines 36-38) is particularly well-thought-out, treating it as an implicit MODIFIED operation.
59-72: LGTM! Clear output requirements.The requirement properly defines the expected output behavior with scenarios for both successful changes and the no-op case. The "No changes needed" scenario (lines 70-72) supports the idempotency requirement from earlier.
openspec/changes/add-specs-apply-command/proposal.md (1)
5-17: LGTM! Clear description of changes.The What Changes section clearly describes the new
/opsx:specsskill, emphasizes idempotency, and provides a helpful workflow diagram. The note that archive continues to work is important for ensuring backward compatibility.src/commands/artifact-workflow.ts (4)
31-31: LGTM! Correct import statement.The import correctly adds the new sync-related template functions following the established pattern for other skill and command templates.
800-807: LGTM! Consistent skill and command instantiation.The sync skill and command are created following the same pattern as the existing skills (newChangeSkill, continueChangeSkill, etc.) and commands.
810-816: LGTM! Proper skill and command registration.The sync skill and command are correctly added to their respective arrays, following the established registration pattern. The skill is registered with the directory name
openspec-sync-specs(line 815), and the command is registered with the filenamesync.md(line 844).Also applies to: 839-845
901-901: LGTM! Help text updated correctly.The new
/opsx:synccommand is properly documented in the usage instructions, maintaining consistency with the other listed commands.openspec/changes/add-specs-apply-command/tasks.md (1)
32-45: LGTM! Clear rationale for agent-driven approach.The design decision section provides valuable context for why the agent-driven approach was chosen over a CLI-driven implementation. The explanation about requirement-level granularity and the benefits of agent-driven partial updates (lines 36-44) effectively justifies the architectural choice.
openspec/changes/add-specs-apply-command/design.md (2)
13-14: Verify naming consistency:/opsx:specsvs/opsx:sync.The design doc references
/opsx:specsskill andopenspec specs applyCLI command, but the PR title and objectives reference/opsx:sync. Please verify which naming is correct and update accordingly for consistency.
1-77: Well-structured design document.The design document clearly articulates the problem, goals, decisions with rationale, and implementation approach. The idempotent design choice and decision to not track state are well-justified.
src/core/archive.ts (2)
6-11: Clean refactoring to use the new specs-apply module.The imports and function calls are correctly updated to use the extracted module. This maintains backward compatibility while enabling reuse of the spec-application logic.
164-164: LGTM - Call sites correctly updated.The function calls to
findSpecUpdates,buildUpdatedSpec, andwriteUpdatedSpeccorrectly match the signatures of the exported functions from the new specs-apply module.Also applies to: 191-191, 216-216
src/core/specs-apply.ts (6)
23-47: Clear and well-structured type definitions.The interfaces
SpecUpdate,ApplyResult, andSpecsApplyOutputprovide clean contracts for the module's public API.
56-95: LGTM - Correctly discovers delta specs.The function properly iterates through change spec directories and builds the list of updates with existence checks.
112-199: Comprehensive validation logic.The duplicate detection and cross-section conflict validation is thorough, covering all expected cases including the RENAMED interplay rules.
342-358: LGTM - Simple write function.The function correctly creates directories and writes the rebuilt spec. The console logging is appropriate for the archive flow that uses this function directly.
363-366: LGTM - Generates appropriate skeleton spec.The skeleton includes the essential sections (Purpose, Requirements) and provides a helpful TBD note referencing the change name.
1-17: Well-organized module with clear documentation.The module header and imports are clean. The extraction of spec-application logic from the archive command is well-executed, enabling standalone use while maintaining backward compatibility.
Update all references: - /opsx:specs → /opsx:sync - specs-apply-skill → specs-sync-skill - Remove cli-artifact-workflow delta spec (no CLI command) - Update proposal, design, and tasks docs
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @openspec/changes/add-specs-apply-command/proposal.md:
- Around line 14-18: The fenced code block containing the flow diagram starting
with '/opsx:new → /opsx:continue → /opsx:apply → archive' is missing a language
identifier; update the opening fence to include a language token (for example
"text" or another appropriate language) so the block becomes ```text (or chosen
language) to enable proper syntax highlighting and validation for that block.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
openspec/changes/add-specs-apply-command/design.mdopenspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/specs/specs-sync-skill/spec.mdopenspec/changes/add-specs-apply-command/tasks.md
✅ Files skipped from review due to trivial changes (1)
- openspec/changes/add-specs-apply-command/specs/specs-sync-skill/spec.md
🧰 Additional context used
📓 Path-based instructions (3)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/add-specs-apply-command/proposal.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/add-specs-apply-command/tasks.md
🧠 Learnings (10)
📓 Common learnings
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>/`
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
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/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
📚 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: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
📚 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:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
📚 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/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
📚 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/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
openspec/changes/add-specs-apply-command/proposal.mdopenspec/changes/add-specs-apply-command/tasks.mdopenspec/changes/add-specs-apply-command/design.md
📚 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/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-specs-apply-command/proposal.md
📚 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/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/add-specs-apply-command/tasks.md
📚 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: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
openspec/changes/add-specs-apply-command/tasks.md
🪛 LanguageTool
openspec/changes/add-specs-apply-command/design.md
[uncategorized] ~13-~13: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...sx:sync` skill for agents to sync specs on demand - Keep operation idempotent (safe to ru...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.18.1)
openspec/changes/add-specs-apply-command/proposal.md
14-14: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
openspec/changes/add-specs-apply-command/proposal.md (1)
1-31: Proposal structure and content look solid.The sections clearly articulate the problem (decoupling specs from archive), solution (/opsx:sync skill), and impact areas. The workflow diagram effectively illustrates when /opsx:sync can be invoked. Naming is consistent with the implementation (specs-sync-skill, openspec-sync-specs, /opsx:sync).
openspec/changes/add-specs-apply-command/tasks.md (1)
1-39: Tasks checklist is well-structured and clear.The sections (Core Implementation, Skill Template, Registration) map well to the implementation scope, with clear checkbox items and descriptive sub-bullets. The Design Decision section adds helpful rationale without inflating the checklist itself. All key tasks are marked complete and correctly reference the implementation details.
openspec/changes/add-specs-apply-command/design.md (3)
1-19: Clear problem statement and well-defined goals/non-goals.The context section effectively frames why decoupling is needed, and the Goals/Non-Goals section appropriately scopes the feature. The non-goals clarify what's deliberately excluded (state tracking, archive changes, partial application), which helps prevent scope creep.
21-71: Design decisions are well-reasoned and appropriately scoped.The four key decisions (logic reuse, no state, agent-driven approach, archive unchanged) address the core architectural concerns and avoid over-engineering. The rationales are sound, and alternatives are clearly rejected. The Risks/Trade-offs section realistically frames what isn't being solved (undo, multi-change coordination) without undermining the design. Decision 3 (agent-driven) is particularly well-justified—delegating to the agent enables flexible partial updates rather than forcing wholesale replacement semantics.
1-76: Consistent alignment with proposal.md and tasks.md.The design rationales directly support the proposal's stated benefits (flexibility, idempotence, agent-driven merging), and the decisions map cleanly to the implementation tasks. Naming is consistent (specs-sync-skill, openspec-sync-specs, /opsx:sync) across all three documents. The design doesn't introduce surprises or contradictions relative to the user-facing proposal.
| ``` | ||
| /opsx:new → /opsx:continue → /opsx:apply → archive | ||
| │ | ||
| └── /opsx:sync (optional, anytime) | ||
| ``` |
There was a problem hiding this comment.
Specify the fenced code block language.
The code block lacks a language identifier, which is required for proper syntax highlighting and validation.
🔎 Proposed fix
-```
+```
/opsx:new → /opsx:continue → /opsx:apply → archive
│
└── /opsx:sync (optional, anytime)
-```
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| /opsx:new → /opsx:continue → /opsx:apply → archive | |
| │ | |
| └── /opsx:sync (optional, anytime) | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
14-14: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @openspec/changes/add-specs-apply-command/proposal.md around lines 14 - 18,
The fenced code block containing the flow diagram starting with '/opsx:new →
/opsx:continue → /opsx:apply → archive' is missing a language identifier; update
the opening fence to include a language token (for example "text" or another
appropriate language) so the block becomes ```text (or chosen language) to
enable proper syntax highlighting and validation for that block.
Summary
/opsx:syncagent-driven skill for syncing delta specs to main specs without archivingarchive.tsto reusablespecs-apply.tsmoduleChanges
getSyncSpecsSkillTemplateandgetOpsxSyncCommandTemplateTest plan
openspec artifact-experimental-setupand verify/opsx:syncis listed/opsx:syncon a change with delta specs/opsx:syncagain to verify idempotent behavior🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.