feat(workflow): Add openspec-refine slash command for feedback loop. - #372
Closed
cylixlee wants to merge 4 commits into
Closed
feat(workflow): Add openspec-refine slash command for feedback loop.#372cylixlee wants to merge 4 commits into
openspec-refine slash command for feedback loop.#372cylixlee wants to merge 4 commits into
Conversation
…cally and `openspec-refine` works well.
Contributor
WalkthroughThis PR introduces a new "refine" slash command workflow to OpenSpec, enabling users to refine approved change proposals without code edits. The change extends existing CLI initialization and update specifications, adds refine command support across 20+ AI development tools, and updates documentation and templates to guide refinement workflows with re-approval gating and strict validation. Changes
Sequence DiagramsequenceDiagram
participant User
participant CLI as OpenSpec CLI
participant Artifacts as Change Artifacts
participant Agent as AI Agent
User->>CLI: run apply
CLI->>Artifacts: apply changes to code
Artifacts-->>User: changes applied
User->>User: review changes, request refinement
User->>CLI: run refine <change-id>
CLI->>Agent: provide refine guidance (no code edits)
Agent->>Artifacts: refine proposal/design/spec deltas only
Artifacts-->>CLI: refined artifacts
CLI->>User: request re-approval (strict validation)
User->>CLI: approve & run apply again
CLI->>Artifacts: apply refined changes
Artifacts-->>User: changes applied
alt Scope expanded
Agent-->>User: recommend new change PR
else Out of scope
Agent-->>User: halt and suggest new change
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (32)
README.md(6 hunks)openspec/changes/archive/2025-12-19-add-refine-command/proposal.md(1 hunks)openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.md(1 hunks)openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.md(1 hunks)openspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.md(1 hunks)openspec/changes/archive/2025-12-19-add-refine-command/tasks.md(1 hunks)openspec/specs/cli-init/spec.md(1 hunks)openspec/specs/cli-update/spec.md(1 hunks)openspec/specs/docs-agent-instructions/spec.md(1 hunks)src/core/configurators/slash/amazon-q.ts(3 hunks)src/core/configurators/slash/antigravity.ts(1 hunks)src/core/configurators/slash/auggie.ts(2 hunks)src/core/configurators/slash/base.ts(1 hunks)src/core/configurators/slash/claude.ts(2 hunks)src/core/configurators/slash/cline.ts(2 hunks)src/core/configurators/slash/codebuddy.ts(2 hunks)src/core/configurators/slash/codex.ts(2 hunks)src/core/configurators/slash/costrict.ts(3 hunks)src/core/configurators/slash/crush.ts(3 hunks)src/core/configurators/slash/cursor.ts(2 hunks)src/core/configurators/slash/factory.ts(2 hunks)src/core/configurators/slash/gemini.ts(1 hunks)src/core/configurators/slash/github-copilot.ts(2 hunks)src/core/configurators/slash/iflow.ts(2 hunks)src/core/configurators/slash/kilocode.ts(1 hunks)src/core/configurators/slash/opencode.ts(2 hunks)src/core/configurators/slash/qoder.ts(5 hunks)src/core/configurators/slash/qwen.ts(3 hunks)src/core/configurators/slash/roocode.ts(2 hunks)src/core/configurators/slash/windsurf.ts(2 hunks)src/core/templates/agents-template.ts(1 hunks)src/core/templates/slash-command-templates.ts(3 hunks)
🧰 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/archive/2025-12-19-add-refine-command/proposal.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/tasks.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.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/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/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/docs-agent-instructions/spec.mdopenspec/specs/cli-update/spec.mdopenspec/specs/cli-init/spec.md
🧠 Learnings (21)
📓 Common learnings
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: Run `openspec validate [change-id] --strict` before requesting approval
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: 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/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/archive/2025-12-19-add-refine-command/proposal.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdsrc/core/configurators/slash/gemini.tssrc/core/templates/slash-command-templates.tssrc/core/configurators/slash/iflow.tssrc/core/configurators/slash/amazon-q.tsopenspec/changes/archive/2025-12-19-add-refine-command/tasks.mdopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdsrc/core/configurators/slash/github-copilot.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tsopenspec/specs/cli-update/spec.mdsrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdopenspec/specs/cli-init/spec.mdsrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/templates/agents-template.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/opencode.tssrc/core/configurators/slash/cursor.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/archive/2025-12-19-add-refine-command/proposal.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdsrc/core/templates/slash-command-templates.tssrc/core/configurators/slash/iflow.tssrc/core/configurators/slash/amazon-q.tsopenspec/changes/archive/2025-12-19-add-refine-command/tasks.mdopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdsrc/core/configurators/slash/github-copilot.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tsopenspec/specs/cli-update/spec.mdsrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdsrc/core/configurators/slash/codex.tsopenspec/specs/cli-init/spec.mdsrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/templates/agents-template.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/opencode.tssrc/core/configurators/slash/cursor.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/archive/2025-12-19-add-refine-command/proposal.mdsrc/core/configurators/slash/iflow.tssrc/core/configurators/slash/amazon-q.tsopenspec/changes/archive/2025-12-19-add-refine-command/tasks.mdsrc/core/configurators/slash/github-copilot.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tssrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdsrc/core/configurators/slash/codex.tssrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/templates/agents-template.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/opencode.tssrc/core/configurators/slash/cursor.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|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/archive/2025-12-19-add-refine-command/proposal.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdsrc/core/configurators/slash/iflow.tssrc/core/configurators/slash/amazon-q.tsopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdsrc/core/configurators/slash/github-copilot.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tsopenspec/specs/cli-update/spec.mdsrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdopenspec/specs/cli-init/spec.mdsrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/cursor.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/*/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/archive/2025-12-19-add-refine-command/proposal.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdsrc/core/templates/slash-command-templates.tssrc/core/configurators/slash/amazon-q.tsopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdsrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tsopenspec/specs/cli-update/spec.mdsrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdopenspec/specs/cli-init/spec.mdsrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/templates/agents-template.tssrc/core/configurators/slash/factory.tsREADME.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/archive/2025-12-19-add-refine-command/proposal.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdsrc/core/templates/slash-command-templates.tssrc/core/configurators/slash/amazon-q.tsopenspec/changes/archive/2025-12-19-add-refine-command/tasks.mdopenspec/specs/docs-agent-instructions/spec.mdsrc/core/configurators/slash/costrict.tsopenspec/specs/cli-update/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdopenspec/specs/cli-init/spec.mdsrc/core/configurators/slash/qoder.tsREADME.mdsrc/core/configurators/slash/opencode.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/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdsrc/core/configurators/slash/iflow.tsopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdsrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tsopenspec/specs/cli-update/spec.mdsrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdopenspec/specs/cli-init/spec.mdsrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/cursor.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 : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdopenspec/specs/cli-update/spec.mdsrc/core/configurators/slash/codebuddy.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdsrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.ts
📚 Learning: 2025-11-17T12:07:21.701Z
Learnt from: ydai-hub
Repo: Fission-AI/OpenSpec PR: 268
File: src/core/configurators/iflow.ts:14-21
Timestamp: 2025-11-17T12:07:21.701Z
Learning: In the OpenSpec repository, `TemplateManager.getClaudeTemplate()` returns a generic template that works for iFlow and other CLI tools, not just Claude-specific content. It's acceptable to use this template across different tool configurators.
Applied to files:
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdopenspec/specs/cli-init/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 : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.mdopenspec/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdopenspec/specs/cli-update/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.mdopenspec/specs/cli-init/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: Use kebab-case, verb-led change IDs: `add-`, `update-`, `remove-`, `refactor-`
Applied to files:
src/core/templates/slash-command-templates.tssrc/core/configurators/slash/amazon-q.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tssrc/core/configurators/slash/codex.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/factory.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:
src/core/configurators/slash/iflow.tssrc/core/configurators/slash/amazon-q.tsopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdsrc/core/configurators/slash/github-copilot.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tssrc/core/configurators/slash/codebuddy.tssrc/core/configurators/slash/codex.tssrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/opencode.tssrc/core/configurators/slash/cursor.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/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
src/core/configurators/slash/iflow.tsopenspec/specs/docs-agent-instructions/spec.mdsrc/core/configurators/slash/github-copilot.tssrc/core/configurators/slash/auggie.tssrc/core/configurators/slash/costrict.tssrc/core/configurators/slash/codebuddy.tssrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tssrc/core/templates/agents-template.tssrc/core/configurators/slash/factory.tsREADME.mdsrc/core/configurators/slash/cursor.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: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
src/core/configurators/slash/iflow.tssrc/core/configurators/slash/codebuddy.tssrc/core/configurators/slash/crush.tssrc/core/configurators/slash/qoder.tssrc/core/configurators/slash/claude.tsREADME.mdsrc/core/configurators/slash/cursor.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: Search existing work using `openspec spec list --long`, `openspec list` for enumerating changes; use `rg` only for full-text search
Applied to files:
src/core/configurators/slash/iflow.tsREADME.mdsrc/core/configurators/slash/cursor.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: 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/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdopenspec/specs/cli-update/spec.mdopenspec/specs/cli-init/spec.mdREADME.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/specs/docs-agent-instructions/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.mdopenspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/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: Use `file.ts:42` format for code location references and `specs/auth/spec.md` format for spec references
Applied to files:
src/core/configurators/slash/costrict.tssrc/core/configurators/slash/qoder.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 `#### Scenario: Name` format (4 hashtags) for scenario headers, not bullets or bold text
Applied to files:
openspec/specs/cli-update/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: Do not start implementation until proposal is approved
Applied to files:
src/core/templates/agents-template.ts
🧬 Code graph analysis (5)
src/core/configurators/slash/gemini.ts (1)
src/core/templates/slash-command-templates.ts (1)
SlashCommandId(1-1)
src/core/templates/slash-command-templates.ts (1)
src/core/templates/index.ts (1)
SlashCommandId(50-50)
src/core/configurators/slash/base.ts (1)
src/core/templates/slash-command-templates.ts (1)
SlashCommandId(1-1)
src/core/configurators/slash/qwen.ts (1)
src/core/templates/slash-command-templates.ts (1)
SlashCommandId(1-1)
src/core/configurators/slash/qoder.ts (1)
src/core/templates/slash-command-templates.ts (1)
SlashCommandId(1-1)
🪛 LanguageTool
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.md
[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...during initialization - THEN create .github/prompts/openspec-proposal.prompt.md, `...
(GITHUB)
[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...b/prompts/openspec-proposal.prompt.md, .github/prompts/openspec-apply.prompt.md, .gi...
(GITHUB)
[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...thub/prompts/openspec-apply.prompt.md, .github/prompts/openspec-refine.prompt.md`, and...
(GITHUB)
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.md
[uncategorized] ~65-~65: The official name of this software platform is spelled with a capital “H”.
Context: ... commands for GitHub Copilot - WHEN .github/prompts/ contains `openspec-proposal.p...
(GITHUB)
openspec/specs/cli-update/spec.md
[uncategorized] ~115-~115: The official name of this software platform is spelled with a capital “H”.
Context: ... commands for GitHub Copilot - WHEN .github/prompts/ contains `openspec-proposal.p...
(GITHUB)
openspec/specs/cli-init/spec.md
[uncategorized] ~240-~240: The official name of this software platform is spelled with a capital “H”.
Context: ...during initialization - THEN create .github/prompts/openspec-proposal.prompt.md, `...
(GITHUB)
[uncategorized] ~240-~240: The official name of this software platform is spelled with a capital “H”.
Context: ...b/prompts/openspec-proposal.prompt.md, .github/prompts/openspec-apply.prompt.md, .gi...
(GITHUB)
[uncategorized] ~240-~240: The official name of this software platform is spelled with a capital “H”.
Context: ...thub/prompts/openspec-apply.prompt.md, .github/prompts/openspec-refine.prompt.md`, and...
(GITHUB)
README.md
[uncategorized] ~108-~108: The official name of this software platform is spelled with a capital “H”.
Context: .../openspec-refine, /openspec-archive (.github/prompts/`) ...
(GITHUB)
🪛 markdownlint-cli2 (0.18.1)
openspec/changes/archive/2025-12-19-add-refine-command/proposal.md
5-5: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
11-11: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
17-17: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
23-23: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (48)
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-update/spec.md (1)
1-85: Spec structure and formatting comply with guidelines.The requirement properly uses
## MODIFIED Requirementsheader, includes 14 comprehensive scenarios with correct#### Scenario: Nameformat (4 hashtags), and employs normative "SHALL" language per coding guidelines. All scenarios consistently address the core concern: refreshing existing slash command files without creating new ones, and specify tool-specific implementation details (TOML markers, YAML preservation, frontmatter handling, etc.).The compound requirement (lines 1–3) addresses both updating slash commands across all tools and ensuring OpenCode archive accepts change ID arguments. This dual concern is properly scoped: the first part applies broadly across all tool scenarios, while the second is appropriately isolated to the OpenCode scenario (lines 39–43). The inclusion of
refine.mdacross all scenarios aligns with the PR objective of adding /openspec-refine support.src/core/templates/agents-template.ts (1)
59-66: LGTM! Clear refine workflow boundaries defined.The Stage 2.5 documentation clearly articulates the refine workflow's scope and constraints. The explicit "No code edits" directive and re-approval gate align well with the PR's goal of preventing agents from deviating during refinement iterations.
openspec/changes/archive/2025-12-19-add-refine-command/specs/docs-agent-instructions/spec.md (1)
1-12: LGTM! Specification follows OpenSpec conventions.The requirement correctly uses
## ADDED Requirementsfor a new orthogonal capability, includes a properly formatted#### Scenario:, and uses normative SHALL language. The scenario comprehensively covers all aspects of refine workflow guidance that must appear in generated instructions.Based on coding guidelines for spec delta files.
openspec/changes/archive/2025-12-19-add-refine-command/tasks.md (1)
1-15: LGTM! Task checklist follows conventions.The task structure follows the required format with numbered sections and checkbox items. All implementation steps are complete and include the mandatory validation step with
--strictflag.Based on learnings for tasks.md structure.
openspec/changes/archive/2025-12-19-add-refine-command/specs/cli-init/spec.md (1)
1-97: LGTM! Comprehensive slash command expansion following guidelines.The requirement correctly uses
## MODIFIED Requirementsand includes the full requirement block with all scenarios as required. Each scenario properly documents refine.md generation alongside existing commands, maintaining tool-specific formatting requirements (YAML frontmatter, TOML structure, OpenSpec markers, etc.).Note: The static analysis hints about
.githubcapitalization are false positives—this is the correct directory name per GitHub conventions for storing workflows and prompts.Based on coding guidelines for MODIFIED Requirements in spec delta files.
src/core/configurators/slash/windsurf.ts (1)
4-28: LGTM! Consistent refine command integration.The refine entry correctly extends both the file path mapping and frontmatter descriptions. The description "Refine an approved OpenSpec change without editing code" clearly communicates the command's purpose and matches the pattern used across other configurators.
src/core/configurators/slash/antigravity.ts (1)
4-29: LGTM! Refine command properly integrated.The additions correctly extend the Antigravity configurator with the refine command, following the same pattern as proposal/apply/archive. The description is consistent with other configurators.
src/core/configurators/slash/codebuddy.ts (1)
4-36: LGTM! Complete refine command integration with proper frontmatter.The refine command addition follows CodeBuddy's established YAML frontmatter pattern with name, description, category, and tags. The frontmatter structure is consistent with other commands, and the trailing delimiter on line 23 aligns the apply block formatting with the new refine entry.
src/core/configurators/slash/kilocode.ts (1)
4-9: LGTM! The refine path mapping follows the established pattern and is correctly typed. TheSlashCommandIdtype union includes'refine', ensuring compile-time safety for the FILE_PATHS mapping.src/core/configurators/slash/costrict.ts (2)
7-7: LGTM: Refine command path added.The refine path mapping is correctly added and follows the existing pattern for other commands.
20-23: LGTM: Refine frontmatter added.The frontmatter block for the refine command is well-structured with appropriate description and argument-hint, consistent with other commands in this configurator.
src/core/configurators/slash/opencode.ts (2)
9-9: LGTM: Refine command path added.The refine path mapping follows the established pattern for OpenCode commands.
30-37: LGTM: Comprehensive refine frontmatter added.The frontmatter provides clear instructions with the UserRequest template, maintaining consistency with the apply command's structure while appropriately describing the refinement workflow.
src/core/configurators/slash/claude.ts (2)
7-7: LGTM: Refine command path added.The refine path mapping is correctly placed in the FILE_PATHS record.
24-29: LGTM: Refine frontmatter added with proper metadata.The frontmatter includes all required fields (name, description, category, tags) consistent with Claude's command structure.
src/core/configurators/slash/base.ts (1)
11-11: LGTM: Core change enables refine command across all configurators.The addition of 'refine' to ALL_COMMANDS properly extends the slash command framework. This change is type-safe and consistent with the SlashCommandId type expansion.
src/core/configurators/slash/roocode.ts (2)
7-7: LGTM: Refine command path added.The refine path mapping is correctly added to NEW_FILE_PATHS.
23-23: LGTM: Refine description added.The description is concise and consistent with the command's purpose across all configurators.
src/core/configurators/slash/github-copilot.ts (2)
7-7: LGTM: Refine command path added.The refine path mapping follows GitHub Copilot's prompt file naming convention.
22-26: LGTM: Refine frontmatter added.The frontmatter structure with description and $ARGUMENTS placeholder is consistent with other GitHub Copilot commands.
src/core/configurators/slash/amazon-q.ts (2)
7-7: LGTM: Refine command path added.The refine path mapping is correctly added to Amazon Q's prompts directory structure.
30-38: LGTM: Detailed refine frontmatter added.The frontmatter provides comprehensive guidance for the refine workflow with clear instructions and the UserRequest template, maintaining consistency with Amazon Q's command structure.
src/core/configurators/slash/auggie.ts (2)
7-7: LGTM: Refine command path added.The refine path mapping is correctly added to Auggie's commands directory.
20-23: LGTM: Refine frontmatter added.The frontmatter includes appropriate description and argument-hint fields, consistent with Auggie's command structure.
src/core/configurators/slash/cline.ts (1)
7-7: LGTM: Refine command integration is clean and consistent.The refine command path and description follow the established pattern for Cline slash commands. The description clearly communicates that refinement happens without code edits.
Also applies to: 23-23
src/core/configurators/slash/qoder.ts (2)
16-17: LGTM: Well-documented refine command addition.The refine command is properly integrated with comprehensive inline documentation and YAML frontmatter. The tags and categorization align with the existing command structure.
Also applies to: 41-46
59-59: Good practice: Documentation kept in sync.The class and method documentation has been updated to reflect the new four-command workflow, maintaining consistency across the codebase.
Also applies to: 74-74, 87-87
src/core/configurators/slash/factory.ts (1)
7-7: LGTM: Refine command with appropriate argument hints.The refine command is properly integrated with Factory's slash command system. The argument-hint "change-id and refinement notes" appropriately guides users on the expected input format.
Also applies to: 20-23
src/core/configurators/slash/gemini.ts (1)
7-7: LGTM: Refine command properly configured for Gemini's TOML format.The refine command is correctly integrated using Gemini's TOML-based slash command structure. The file path and description are consistent with the other commands.
Also applies to: 14-14
src/core/configurators/slash/cursor.ts (1)
7-7: LGTM: Refine command properly integrated with Cursor's frontmatter format.The refine command follows Cursor's established pattern with proper name, id, category, and description fields. The slash command format (/openspec-refine) is consistent with the other commands.
Also applies to: 24-29
openspec/specs/docs-agent-instructions/spec.md (1)
39-50: LGTM: Normative requirement with clear refine workflow guidance.The new requirement uses proper normative language (SHALL) and provides comprehensive guidance for the refine workflow. The scenario clearly specifies:
- Refinement is limited to proposal artifacts (no code edits)
- Re-approval is mandatory before proceeding
- Scope expansions should trigger a new change proposal
- Strict validation is required post-refinement
This aligns well with the PR objectives and maintains consistency with OpenSpec conventions.
As per coding guidelines, the requirement correctly uses SHALL for normative specifications.
src/core/templates/slash-command-templates.ts (3)
1-1: LGTM: Type definition extended to support refine command.The SlashCommandId type now correctly includes 'refine' alongside the existing proposal, apply, and archive commands.
37-55: LGTM: Comprehensive refine workflow with strong guardrails.The refine command implementation includes:
Strong guardrails (lines 37-38):
- Explicit prohibition on code edits during refine
- Scope expansion prevention with recommendation to create new changes
- User-driven refinement requirements
Robust change ID resolution (lines 40-45):
- Multiple fallback strategies for determining the change ID
- Handles various input formats (explicit blocks, slash command args, conversation context)
- Appropriate validation via
openspec listClear workflow (lines 46-52):
- Updates limited to proposal artifacts (proposal, design, tasks, spec deltas)
- Maintains spec format requirements (#### Scenario: entries)
- Mandatory strict validation before completion
- Explicit re-approval gate before any apply work continues
The implementation effectively prevents agents from deviating into uncontrolled refinements while maintaining flexibility in how users invoke the command.
74-74: LGTM: Refine command body properly wired into the template system.The refine command is correctly composed from guardrails, steps, and references, following the same pattern as the other commands.
src/core/configurators/slash/qwen.ts (2)
18-18: LGTM: Refine command properly configured for Qwen's TOML format.The refine command is correctly integrated with the appropriate TOML file path and consistent description. The implementation follows Qwen's established slash command patterns.
Also applies to: 25-25
36-37: Good practice: Documentation reflects the complete command set.The class documentation has been updated to enumerate all four slash commands, including the new /openspec-refine command, maintaining clarity for future maintainers.
src/core/configurators/slash/codex.ts (2)
12-12: LGTM: Refine command path added correctly.The refine entry follows the established naming convention and is consistent with other command paths.
40-45: LGTM: Frontmatter block is well-structured.The frontmatter correctly includes description, argument-hint, and the $ARGUMENTS placeholder, matching the pattern used by other commands.
openspec/changes/archive/2025-12-19-add-refine-command/proposal.md (1)
1-31: LGTM: Proposal structure follows guidelines.The proposal correctly includes Why (motivation), What Changes (with detailed From/To/Reason/Impact breakdown), and Impact sections as required by the coding guidelines.
src/core/configurators/slash/iflow.ts (2)
7-7: LGTM: Refine command path added correctly.The refine entry follows the iflow naming convention and is consistent with other command paths.
24-29: LGTM: Frontmatter block is complete.The frontmatter correctly includes all required fields (name, id, category, description) and follows the iflow pattern.
src/core/configurators/slash/crush.ts (2)
7-7: LGTM: Refine command path added correctly.The refine entry follows the crush naming convention and is consistent with other command paths.
24-29: LGTM: Frontmatter block is complete.The frontmatter correctly includes all required fields (name, description, category, tags) and follows the crush pattern with appropriate tags.
openspec/specs/cli-update/spec.md (1)
56-56: LGTM: Refine command integration is consistent across all tools.All tool scenarios correctly include
refine.mdin their respective file lists, maintaining consistency with the existingproposal.md,apply.md, andarchive.mdpattern. The spec follows the required SHALL/MUST normative language.Also applies to: 61-61, 66-66, 72-72, 78-78, 83-83, 90-90, 96-96, 102-102, 108-108, 115-115, 121-122, 127-127
openspec/specs/cli-init/spec.md (1)
177-177: LGTM: Refine command initialization is consistent across all tools.All tool scenarios correctly include
refine.mdin their file generation steps, maintaining consistency with the existing three-file pattern (proposal, apply, archive). The spec follows the required SHALL/MUST normative language and proper scenario format.Also applies to: 183-183, 189-189, 196-196, 203-203, 209-209, 216-216, 222-222, 228-228, 234-234, 240-240, 248-251, 255-255, 263-263
README.md (3)
63-83: LGTM: Workflow diagram clearly illustrates the refine loop.The updated workflow diagram effectively shows how the refine loop connects the implementation stage back to the Review & Align stage, making the iterative refinement process clear to users.
94-116: LGTM: Tool table comprehensively documents refine command support.The table consistently includes the refine command for all supported tools with correct path specifications and command syntax. The documentation is thorough and follows the established pattern.
207-215: LGTM: Getting Started section effectively demonstrates refine workflow.The updated example clearly shows how to use the refine command in both natural language and slash command forms, with practical context about when to refine proposal artifacts.
| Teams often need to adjust an approved change after an apply pass produces unexpected results. Today that forces either a brand-new proposal or ad-hoc instructions outside the OpenSpec workflow. A dedicated refine command keeps adjustments inside the workflow while enforcing re-approval and leaving code changes to apply. | ||
|
|
||
| ## What Changes | ||
| **Slash command templates** |
Contributor
There was a problem hiding this comment.
Use markdown headings instead of bold text for subsections.
The subsection titles "Slash command templates", "Init scaffolding", "Update behavior", and "Agent instructions" are using bold emphasis rather than proper markdown headings. This affects document structure and readability.
🔎 Proposed fix
## What Changes
-**Slash command templates**
+### Slash command templates
- From: Only `proposal`, `apply`, and `archive` shared templates exist.
- To: Add a `refine` shared template that updates proposal/design/tasks/spec deltas only, runs strict validation, and stops for re-approval.
- Reason: Provide a first-class refinement loop without mixing in code changes.
- Impact: New `openspec-refine` command body and template entry.
-**Init scaffolding**
+### Init scaffolding
- From: `openspec init` scaffolds proposal/apply/archive command files.
- To: Scaffold refine command files alongside the existing three for every supported tool.
- Reason: Make refine available wherever slash commands are generated.
- Impact: One additional command file per tool.
-**Update behavior**
+### Update behavior
- From: `openspec update` refreshes only proposal/apply/archive command files.
- To: Refresh refine files when they already exist, without creating missing ones.
- Reason: Keep refine guidance current while preserving update semantics.
- Impact: Update covers refine templates too.
-**Agent instructions**
+### Agent instructions
- From: The workflow guidance focuses on proposal → apply → archive only.
- To: Add refine guidance for post-apply adjustments, including no code changes, re-approval gating, and out-of-scope handling.
- Reason: Keep the documented workflow aligned with the new command.
- Impact: Updated `openspec/AGENTS.md` content.Also applies to: 11-11, 17-17, 23-23
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
5-5: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In openspec/changes/archive/2025-12-19-add-refine-command/proposal.md around
lines 5, 11, 17, and 23, replace the subsection titles currently formatted with
bold emphasis (e.g., **Slash command templates**, **Init scaffolding**, **Update
behavior**, **Agent instructions**) with proper markdown headings (use an
appropriate level such as "##" or "###") so they become real document headings;
update each instance so the heading syntax is used and remove the surrounding
bold markup to improve document structure and readability.
Author
|
Hi @TabishB, do you think we should convert this PR to draft if you're cautious about adding new slash commands? |
Contributor
|
@cylixlee Hey I think the slash command here makes sense in general. I think the only concern is how effectively do the agents know what needs to get updated? For example if I create a full proposal including tasks.md and I ask the agent to refine it, does it update the tasks as well? I'm working on a better way to do this, but happy to get this added in the meanwhile. Feel free to dm me on discord if you want to see the alternative solution that I'm working on. |
Author
|
Great! I'll be waiting for your approach and leave that burden to you then 😄. BTW, what about creating milestones to claim the upcoming features that will be included in the next version? Thus may reduce unnecessary issues and PRs. |
clay-good
added a commit
to clay-good/OpenSpec
that referenced
this pull request
Jun 29, 2026
…sign After a comprehensive sweep of open issues, PRs, and discussions, grounded the proposal in the complete adjacent landscape and answered the open design questions the cluster raises: - Fission-AI#783 (Cross-artifact quality review before apply) is now a primary Closes: it IS audit mode. Answer its open "new skill vs. extend validate" question via the determinism split — deterministic checks (drift/completeness/coverage) are CLI/validate-shaped; the semantic cross-artifact review is the skill. Added a skill spec scenario for the Fission-AI#783 patterns (scope contradiction, spec gap, duplication). - Discussion Fission-AI#1206 ("refine proposal now?") + prior-art PR Fission-AI#372: official answer is /opsx:update. - New design Decision 8 (command family): delineate /opsx:update from /opsx:clarify (Fission-AI#702, within-artifact), /opsx:review (Fission-AI#1251, plan-vs-code), and verify; /opsx:update consolidates update+regen+refine into one action, addressing skill-sprawl (Fission-AI#1263, Fission-AI#783). - Reuse, don't reinvent: audit's empty/incomplete check reuses Fission-AI#1098's artifactOutputComplete (same outputs.ts the digest helper lives in); capability coverage reuses Fission-AI#1277's validateChangeCapabilityCoverage. - New open questions: surface deterministic coherence in `validate` for a CI gate (Fission-AI#783-B, Fission-AI#829); naming reconciliation with Fission-AI#783's /opsx:refine. - Confirmed add-update-command* branches are the `openspec update` tool-file refresh (not artifact update) — no collision. Validates clean under --strict; 10 deltas; all relative links resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
clay-good
added a commit
to clay-good/OpenSpec
that referenced
this pull request
Jul 7, 2026
…ssion-AI#1278) * docs(openspec): propose add-update-workflow — graph-driven /opsx:update + cohesive audit Dogfooded OpenSpec proposal for the missing first-class "update" action: a /opsx:update workflow that propagates an edit to one artifact across its downstream dependents (targeted mode) or audits a whole change for stale/ incoherent artifacts (audit mode) — driven by the schema's artifact graph, never hardcoded filenames, editing planning artifacts only (never code). - artifact-graph: expose reverse-dependency queries (getDependents/getDownstream) + a requires-edge mtime staleness signal (the engine already builds the dependents map at graph.ts:98 and discards it). - cli-artifact-workflow: surface requires/dependents/stale on `openspec status --json` and add a `--impact <artifact>` downstream-revisit-order selector. - opsx-update-skill: the user-facing /opsx:update command (targeted + audit). Supersedes the proposal-only stub add-artifact-regeneration-support. Addresses the cluster Fission-AI#1188/Fission-AI#705/Fission-AI#673/Fission-AI#247 (closes), Fission-AI#694/Fission-AI#684/Fission-AI#618 (answers), and is graph-driven to avoid the Fission-AI#777/Fission-AI#666 hardcoded-artifact-pattern bug class. Validates clean under `openspec validate --strict`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): make add-update-workflow deterministic & grounded (Tabish review) Reframe per the steer "more deterministic and grounded in reality": - Deterministic spine: the CLI computes the impact set (which downstream artifacts to revisit, in build order, with paths) as a pure function of schema edges + filesystem. The agent only rewrites prose. Grounded in real APIs already present: getUnlockedArtifacts (direct dependents), getBuildOrder (order), resolveArtifactOutputs (paths); reverse map built at graph.ts:82-87. - Replace fragile mtime staleness with a newline-normalized SHA-256 content digest (reproducible cross-platform). Drift = upstream digest vs recorded baseline; no baseline => "unknown", never a false positive. mtime and pure-git rejected with rationale; digest ledger is a separable, optional layer. - Explicit determinism boundary decision (CLI decides files/order/drift; agent rewrites). Skill MUST source the file list/order from `openspec status --impact`, never compute it. - Corrected all code citations to verified lines (graph.ts:82-87, instruction-loader.ts:366/429, status.ts); noted Fission-AI#1277's coverage helpers are not in this branch's base (coordinate, don't reuse). - Specs updated: artifact-graph Content Digest requirement; cli status digest + deterministic impact ordering; skill determinism + baseline-aware audit. tasks add digest/determinism/cross-platform tests + optional ledger section. Still validates clean under `openspec validate add-update-workflow --strict`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): harden add-update-workflow determinism; drop direct name refs - Digest ledger tracks DIRECT upstream digests; document that transitive drift emerges hop-by-hop as downstream is reconciled (no transitive bookkeeping). - Ground audit's no-baseline structural facts on signals available in this branch (missing/empty output, blocked/incomplete); capability-coverage is an add-on only when Fission-AI#1277's validateChangeCapabilityCoverage is present. - Add the "update revises only existing downstream; defer not-yet-created ones to /opsx:continue" rule across proposal/design/specs/tasks; impact entries now carry existence/status. - Note artifact-level (not file-level) granularity and that getDownstream terminates by the schema's acyclic guarantee. - Remove direct personal references from the docs. Validates clean under `openspec validate add-update-workflow --strict`; 10 deltas. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): full issue/PR/discussion coverage + command-family design After a comprehensive sweep of open issues, PRs, and discussions, grounded the proposal in the complete adjacent landscape and answered the open design questions the cluster raises: - Fission-AI#783 (Cross-artifact quality review before apply) is now a primary Closes: it IS audit mode. Answer its open "new skill vs. extend validate" question via the determinism split — deterministic checks (drift/completeness/coverage) are CLI/validate-shaped; the semantic cross-artifact review is the skill. Added a skill spec scenario for the Fission-AI#783 patterns (scope contradiction, spec gap, duplication). - Discussion Fission-AI#1206 ("refine proposal now?") + prior-art PR Fission-AI#372: official answer is /opsx:update. - New design Decision 8 (command family): delineate /opsx:update from /opsx:clarify (Fission-AI#702, within-artifact), /opsx:review (Fission-AI#1251, plan-vs-code), and verify; /opsx:update consolidates update+regen+refine into one action, addressing skill-sprawl (Fission-AI#1263, Fission-AI#783). - Reuse, don't reinvent: audit's empty/incomplete check reuses Fission-AI#1098's artifactOutputComplete (same outputs.ts the digest helper lives in); capability coverage reuses Fission-AI#1277's validateChangeCapabilityCoverage. - New open questions: surface deterministic coherence in `validate` for a CI gate (Fission-AI#783-B, Fission-AI#829); naming reconciliation with Fission-AI#783's /opsx:refine. - Confirmed add-update-command* branches are the `openspec update` tool-file refresh (not artifact update) — no collision. Validates clean under --strict; 10 deltas; all relative links resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): resolve open questions to committed decisions; drift in scope Per review steer, every open question is now a committed happy-path decision so build-out has no dangling forks, and the deterministic drift baseline is pulled into scope (it is what makes audit-mode drift deterministic vs. agent-guessed): - Digest ledger IN SCOPE (design Decision 3): per-artifact DIRECT upstream digests in ChangeMetadataSchema, written by a deterministic `openspec status --record`; pre-existing changes (no baseline) degrade to drift `unknown` + structural checks. Generating-flow auto-recording stays optional (graceful). - cli-artifact-workflow spec: folded drift into the digest requirement (record baseline / drift vs baseline / unknown-without-baseline) — stays at 10 deltas. - opsx-update-skill spec: skill records baseline via `--record` after each confirmed edit, so audits clear once reconciled. - Replaced "## Open Questions" with "## Decisions resolved": ledger in scope; targeted entry baseline-aware; apply stays standalone (points to update on drift); cross-change (Fission-AI#247), continue/ff de-hardcoding (Fission-AI#777), and validate CI-gate (Fission-AI#783-B/Fission-AI#829) are named follow-ups, not deferrals of the core feature; /opsx:update kept as the umbrella name. - Migration Plan + Capabilities + Impact + tasks updated; status JSON gains `drift`, CLI gains `--record`. Re-synced with upstream main (0 behind). Validates clean under --strict; 10 deltas; all links resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): harden add-update-workflow — close cross-OS, read-only, edge gaps Stress-tested every claim against live source and fixed the soft spots: - Cross-OS digest determinism (real bug): resolveArtifactOutputs (outputs.ts:34) sorts ABSOLUTE paths via .sort(), which differs by OS — so a multi-file glob artifact (specs/**/*.md) would hash differently on Windows vs POSIX. Digest now specified to order files by change-relative forward-slash path and hash relpath+content. Added spec scenarios (cross-platform glob stability; rename changes digest) and a cross-OS test task. - Read-only status invariant: moved baseline recording OFF `openspec status` (a read command silently mutating the drift reference is a footgun) to a dedicated `openspec reconcile` write verb. Updated spec, skill, design, impact, capabilities, tasks; reconciled the "no new verb" claims. - Edge case: missing upstream at record time is stored as an explicit `absent` marker so later creating it registers as drift (spec scenario added). - Edge case: coherent change yields no edits (clean-path scenario). - Grounding fixes: continue-change hardcoded block is duplicated (skill 103-112 + command 225-234) — both must be fixed in the Fission-AI#777 follow-up; verified no content-hash util exists. - Fixed two stale claims the layered edits left: the Impact digest bullet (concatenation→relative-path) and the naming-boundary line. Validates clean under --strict; 10 deltas (4+3+3), 44 scenarios; all links resolve; re-synced with upstream main (0 behind); issue/PR/discussion sweep re-run, no new items. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): pin data contracts + digest forward-compat; delineate Fission-AI#880 Grounded the surface so an implementer builds it without guessing, and added proportionate forward-compatibility: - New design "Data contracts" section with exact shapes: extended ArtifactStatus (requires/dependents/digest/drift/driftFrom — additive to the real interface at instruction-loader.ts:120), the --impact response, and the `.openspec.yaml` baselines ledger. All additive; nothing existing changes type. - Digest scheme tag (`sha256-relpath-v1:`) + forward-compat: drift compares only same-scheme digests; an unrecognized/older scheme reports `unknown` rather than silently mis-comparing — re-reconcile restores it. Added a cli spec scenario and tasks for it. - Grounded the ledger write: there is no central change-metadata writer today (change-metadata/index.ts only re-exports schema), so reconcile does a safe read-modify-write of .openspec.yaml mirroring the store's parse/serialize/writeStoreMetadataState pattern (foundation.ts). - Coverage: re-swept; folded Fission-AI#880 (/opsx:validate code-vs-living-specs) into the plan-vs-code delineation alongside Fission-AI#1251/Fission-AI#1073. Main unchanged (546224e); all citations still valid. Validates clean under --strict; 10 deltas; links resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): simplify add-update-workflow to a thin /opsx:update skill Rework per @TabishB review (PR Fission-AI#1278): the proposal over-built. Drop the deterministic-spine machinery and lean on the existing status command. - Cut the reverse-dependency graph API (getDependents/getDownstream), SHA-256 content digests, the .openspec.yaml baseline ledger, the `openspec reconcile` write op, the drift report, and `status --impact`. Removes the artifact-graph and cli-artifact-workflow spec deltas. - Reframe propagation as bidirectional coherence (editing design can require revising proposal), not downstream-only. - Center the feature on one thin skill over the existing `openspec status` / `openspec list`; design now sketches the actual minimal skill instruction body ("written by hand"). - v1 adds no new CLI/graph/schema code: just update-change.ts + wiring. Validates clean: `openspec validate add-update-workflow --strict`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(update-workflow): pin the status path contract to existingOutputPaths Address @alfred-openspec's review: the skill's write target was described loosely as "resolved paths." Make it precise across proposal/design/spec/tasks: - `openspec status --json` already returns everything the skill needs, in the top-level `artifactPaths` map — `resolvedOutputPath` and `existingOutputPaths` per artifact. No new CLI field is required. - The skill edits `existingOutputPaths` (the concrete, glob-expanded files) and never writes to `resolvedOutputPath`, which for a glob artifact like `specs/**/*.md` remains the glob pattern rather than a real file. - Add spec scenarios for editing a glob artifact's concrete files and for deferring a brand-new file under a glob artifact to `/opsx:continue`. - Tighten the cross-platform scenario and add a template test (3.4) asserting the write target is `existingOutputPaths`, not a glob `resolvedOutputPath`. Validates clean under `openspec validate add-update-workflow --strict`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(update-workflow): address review — default profile, next-step guidance, change-scoped naming - Register /opsx:update in the default core profile, not expanded-only (maintainer call on the PR) - Add next-step guidance: after updating, recommend /opsx:continue, /opsx:apply (esp. when the change was already implemented), or /opsx:archive — guidance only, never acted on - Pin naming scope: skill openspec-update-change, change proposals only; generalizing update to other graph types is an explicit non-goal Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(skills): implement the /opsx:update skill (openspec-update-change) Implements the approved add-update-workflow change: one thin skill over the existing status/list commands, in the default core profile. - new update-change.ts template (skill + command), registered across init, profiles, skill-generation, tool-detection, profile-sync-drift - update joins CORE_WORKFLOWS and ALL_WORKFLOWS - docs: opsx.md command row + usage note, commands.md reference section, supported-tools.md skill list - retire the superseded add-artifact-regeneration-support stub - template tests pin the guardrails (schema-driven ids, planning-only, existingOutputPaths write contract, next-step guidance); parity hashes regenerated; profile/init/update/config tests cover the new core set - tasks.md checked off; validate --strict passes Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
HerbertGao
added a commit
to HerbertGao/OpenSpec-cn
that referenced
this pull request
Jul 11, 2026
* fix(resolution): converge validate, view, and archive onto canonical resolution (#1182, #1202, #1156) (#1280)
* docs(openspec): propose resolution/validation parity bug bundle (#1182, #1202, #1156)
Planning artifacts only (proposal/design/spec deltas/tasks) for a focused
bug-fix bundle. Three read/validate paths silently diverge from the canonical
logic a sibling command already gets right:
- #1182 validate ignores workspace planning homes that status/instructions resolve
- #1202 view counts only changes/<name>/tasks.md, ignoring the schema tasks glob
- #1156 the SHALL/MUST body-keyword hint fires for deltas but not main specs
Fix converges each divergent path onto the canonical one; parity is asserted by
test. No new surface, no behavior change to the already-correct paths. Validates
--strict.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): bulletproof the parity bundle after adversarial source review
Hardened all three bugs after tracing each path to source with parallel
verification agents. Material corrections:
- #1182: reframed from "workspace planning home resolution" (planning homes are
repo-only; the feature is now 'stores', and validate already accepts --store)
to the real, reproducible-at-HEAD mechanism: validate's proposal.md membership
gate (getActiveChangeIds) vs status/instructions' directory-existence rule
(validateChangeExists). Pulled nested specs/<area>/<cap> delta discovery and
bulk --all into scope; noted show.ts sibling.
- #1202: widened from view-only to the shared helper's real blast radius — also
the archive incomplete-task gate (silently archives unfinished glob-tasks
changes: data safety) and a 2nd hardcoded copy in change.ts. Pinned apply.tracks
as the source, change-dir scope containment, and the no-schema fallback. Added
cli-archive delta for the gate.
- #1156: the main-spec parser discards the requirement header before Zod runs, so
the hint can't be "lifted" — fix needs header recovery (reuse requirement-blocks)
+ Zod de-dup, and the main-spec message can't be byte-identical to the delta's
(no ADDED prefix). Pinned the actionable sentence + single-emission + regression
scenarios across all main-spec surfaces.
4 deltas (cli-validate x2, cli-view, cli-archive). Validates --strict.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): deep-harden the parity bundle with empirical reproduction
Round 2 of bulletproofing: 3 parallel agents reproduced every bug against the
built (pre-fix) CLI and traced fix sites. This pass corrected two substantive
errors in my own prior spec and closed several gaps.
#1202 (two corrections to the prior draft):
- apply.tracks is a FILENAME that selects the tracked artifact, NOT a glob; the
glob is that artifact's `generates`. status resolves via
resolveArtifactOutputs(changeDir, artifact.generates). Fixed all wording.
- "view/archive counts equal status" is FALSE: status checks file EXISTENCE, not
checkboxes (proven: status calls a 3/5 change isComplete:true). Deleted the two
count-parity scenarios; reframed as resolution-mechanism parity (same files).
- Added schema-resolution-failure fallback (resolveSchema throws; helper must
catch or view/list/archive crash). Added projectRoot param + 6-site wiring.
- Empirically PROVEN data-safety bug: archive moved a 3/5 unfinished change into
changes/archive/.
#1182:
- Found a THIRD getActiveChangeIds site (interactive selector, validate.ts:97).
- Proven: --all with a lone proposal-less change exits 0 silently. Added
exit-code scenarios. Trimmed over-scope: getSpecIds spec-side is NOT a bug;
no store-specific scenario needed; noun-form scoped out.
#1156:
- Refine-relaxation regression resolved: deltas don't use the Zod refine
(validate imperatively), so REMOVE it (not relax) once applySpecRules owns both
header-only and no-keyword cases. Added RENAMED (out-of-scope), lowercase, and
the new no-body-line-valid-today scenarios; pinned exact message + prefix.
Still 4 deltas; validates --strict; empirical evidence section added to design.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix: converge validate/view/archive onto canonical resolution (#1182, #1202, #1156)
Implements the resolution/validation parity bug bundle planned in
openspec/changes/fix-validate-view-resolution-parity. Each fix points a
divergent read/validate path at the canonical implementation a sibling
command already gets right, with parity tests guarding against re-forking.
#1182 — validate resolves changes like status. validate now resolves a
change by directory existence (shared getAvailableChanges) instead of
requiring proposal.md, at all three sites (targeted, bulk, interactive
selector). A scaffolded/still-authoring change is validated rather than
reported Unknown item; a resolved-but-invalid change exits non-zero.
show.ts and the deprecated noun-form change validate are scoped out.
#1182b — validateChangeDeltaSpecs recurses the nested multi-area layout
(specs/<area>/<capability>/spec.md) via a new findDeltaSpecFiles walker,
so a resolved multi-area change validates its deltas instead of reporting
"No delta sections found".
#1202 — getTaskProgressForChange resolves task progress through the
tracked-tasks artifact's generates glob (the same resolveArtifactOutputs
status uses), aggregating checkboxes across every matched tasks.md scoped
to the change dir, with a never-throw fallback to a single top-level
tasks.md. Updates all four callers (view/list/archive x2) for the new
projectRoot arg and folds the second copy in change.ts onto the helper.
Fixes view's Draft misclassification and the archive incomplete-task
gate that let an unfinished glob-tasks change archive (data safety).
#1156 — the SHALL/MUST body-keyword hint applies to main specs.
applySpecRules recovers the requirement header via extractRequirementsSection
and emits the targeted hint (header-only) or generic message (no keyword),
exactly once; the Zod refine is removed (deltas never used it). The
actionable sentence is byte-identical to the change-delta path.
Adds parity/regression tests (Decision 7): validate<->status resolution
incl. exit code, view/archive resolve the same files as status, and the
main-spec<->delta actionable-sentence parity. Full suite green (1791
passed; only the pre-existing, environment-specific zsh-installer
failures remain). Change validates --strict; all 36 repo specs pass
--specs --strict with no new false positives.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: add cloudflare documentation deployment website (#1285)
* docs(website): add Fumadocs documentation site for Cloudflare Pages
Add a self-contained marketing + documentation site under website/, built
with Fumadocs (Next.js) and configured as a static export so it deploys
directly to Cloudflare Pages with no server runtime.
What's included:
- A marketing landing page (hero, the two-folder model, the four core
ideas, the explore→propose→apply→archive loop, and the "why").
- 13 documentation pages rewritten for clarity and delight: introduction,
installation, getting started, how commands work, core concepts, the
workflow, explore first, existing projects, editing a change,
customization, FAQ, and a reference section (slash commands, CLI,
supported tools).
- Static client-side search (Orama), per-page Open Graph images, and
llms.txt / llms-full.txt routes — fitting for an AI-native tool.
- website/README.md with one-table Cloudflare Pages deploy settings
(root: website, build: npm run build, output: out).
Content is faithful to the docs/ overhaul from #1237, restated in a
simpler, friendlier voice. Verified with a clean `next build` (48 static
pages, no warnings).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): sharpen the sell, add a Stores guide
Completes the documentation work begun in #1237 by tightening the
Fumadocs site toward the quality bar of the stores user-guide:
- Intro now opens problem-first ("the requirements lived only in chat"),
adds an honest "How it compares" table (Spec Kit / Kiro / nothing), and
frames the tradeoff in a "When the ceremony isn't worth it" callout.
- New Stores guide (beta) distilled from docs/stores-beta/user-guide.md:
the problem, the annotated shape, a five-minute walkthrough with real
command output, a role-based story, the root-resolution order, and an
honest-limitations section. Linked from Existing Projects.
Verified with a clean `next build` (51 static pages, no warnings).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): make the value tangible — landing sections + Examples page
Continue the #1237 docs completion with a stronger product story:
- Landing page now reads like a real product site:
- "Works with the tools you already use" strip (15 named assistants + more)
- "What a change actually looks like" — three real artifacts
(proposal.md, a spec delta, tasks.md) so the workflow is concrete
- "The honest middle" comparison block (Spec Kit / Kiro / no specs)
- Robust hero gradient via color-mix instead of v3 theme() syntax
- New Examples & Recipes page: seven copy-pasteable, narrated walkthroughs
(small feature, bug fix, explore-first, parallel changes, no-behavior
refactor with --skip-specs, step-by-step, onboard). Linked from the intro
and getting-started.
Verified: clean `next build` (54 static pages, no warnings); Tailwind
opacity/color-mix utilities confirmed in the generated CSS; all internal
links resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): add favicon, sitemap, and robots for a complete public site
- Branded SVG favicon (app/icon.svg) in the OpenSpec indigo.
- Static sitemap.xml covering the home page and every doc, built from the
content source and NEXT_PUBLIC_SITE_URL.
- robots.txt allowing all and pointing at the sitemap.
All three are emitted by the static export. Clean `next build`, 57 pages.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: lead with stores as "why teams adopt OpenSpec"; complete docs coverage
Final pass completing the #1237 documentation work.
Reposition stores (beta) as the team adoption story, consistently:
- README.md gains a prominent "Why teams adopt OpenSpec" section right
after the demo (cross-repo features, shared requirements, plan before
code), leading with stores.
- Landing page gains a matching "Why teams adopt OpenSpec" section.
- Docs intro gains a teams card + callout pointing at stores.
- Stores page expanded with full References and Worksets technical
examples (the cross-team requirements story, workset create/open).
Incorporate the remaining source-doc knowledge so the site is complete:
- New pages: Glossary, Troubleshooting, Multi-Language, and an
Agents & Automation reference (the machine-readable --json surfaces and
workflow primitives that make OpenSpec AI-native).
- The Workflow page now covers ff-vs-continue, a three-dimension verify
example, and the update-vs-start-fresh decision guide.
- Nav restructured with a Help section; reference section gains Agents.
Build hardening: `build` now runs `fumadocs-mdx && next build` so the
content source is always regenerated. Clean build: 69 static pages, no
warnings; all internal links verified.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): fix docs GitHub source links + address review nits
- page.tsx: prefix ViewOptionsPopover githubUrl with website/ so the
"view/edit source" links resolve to website/content/docs/... instead
of 404-ing on every deployed docs page (Alfred blocker).
- installation.mdx: note that `yarn global add` is Classic Yarn only and
point Yarn Berry users at `yarn dlx` / npm / pnpm.
- index.mdx: label the comparison table's first column ("Option").
- (home)/page.tsx: use the shared docsRoute constant for all /docs links
instead of hardcoded paths.
Verified with `npm run build` in website/ — 69 static pages, and the
built getting-started page links to blob/main/website/content/docs/...
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): mirror docs/*.md into the site + auto-deploy on a cadence
Make the repository's docs/*.md the single source of truth for the docs
site instead of maintaining a parallel set of hand-written MDX pages that
silently drift.
- scripts/sync-docs.mjs mirrors ../docs into content/docs/ on every build:
derives title/description, injects Fumadocs frontmatter (+ githubSource),
rewrites internal *.md links to /docs routes, and emits meta.json. Pages
are written as .md so <placeholders>/{braces} in the docs stay literal
and never break the MDX build.
- docs.sync.config.mjs is the one manifest deciding which docs publish and
their slug/section/icon. content/docs/ is now generated + git-ignored;
the curated .mdx pages are removed. The marketing landing page stays
hand-authored.
- build/dev/types:check run sync:docs first, so the site is always current.
- .github/workflows/deploy-docs.yml rebuilds and deploys to Cloudflare
Pages via Wrangler on push to docs/**|website/**, daily on a schedule,
on demand, and as a build-only check on PRs. Needs CLOUDFLARE_API_TOKEN
+ CLOUDFLARE_ACCOUNT_ID secrets and the DOCS_SITE_URL variable.
- source.config.ts carries githubSource so "edit this page" opens the real
docs/*.md; website/README.md documents the pipeline.
Verified: clean build, 23 pages generated, 78 static pages, no warnings;
all internal doc links resolve; MDX-hazard docs (cli, customization) build.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(website): fall back to default site URL when NEXT_PUBLIC_SITE_URL is empty
The deploy workflow passes NEXT_PUBLIC_SITE_URL from the DOCS_SITE_URL repo
variable, which resolves to an empty string when unset. `?? fallback` does
not catch '' (only null/undefined), so `metadataBase: new URL('')` crashed
`next build` with ERR_INVALID_URL while collecting page data. Use `||` so an
empty value also falls back. Verified: `NEXT_PUBLIC_SITE_URL='' npm run build`
now generates all 78 static pages.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: add reviewing, writing-specs, and team-workflow guides
Fill the biggest gaps a new user hits, in the plain-language voice of the
stores user guide:
- reviewing-changes.md: the two-minute human review of an AI-drafted plan
before /opsx:apply — what to open, in what order, and the red flags per
artifact — plus the /opsx:verify pass after code.
- writing-specs.md: what a strong requirement and scenario are made of,
choosing ADDED/MODIFIED/REMOVED, and right-sizing a change.
- team-workflow.md: how a change maps onto a branch and a pull request,
reviewing spec deltas in a PR, when to archive, and parallel changes —
framed as convention, since OpenSpec never touches git.
Wire them into the docs map (README), the site nav (docs.sync.config.mjs),
and light "next steps" cross-links from getting-started, editing-changes,
and workflows. Verified: site builds clean, 26 pages, all internal links
resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(website): add one-time deploy setup checklist + landing-page note
Spell out the three maintainer steps that activate auto-deploy (create the
openspec-docs Pages project, add CLOUDFLARE_API_TOKEN/ACCOUNT_ID secrets,
merge to main), and note that the pipeline mirrors docs on build regardless.
Also flag that openspec.dev is a separate Astro landing page and whether to
keep/port this Fumadocs landing page is a maintainer decision.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(website): address review feedback on docs-site PR
Maintainer review (TabishB) + Alfred blocker:
- deploy-docs.yml: guard the Cloudflare deploy on `github.ref ==
refs/heads/main`. A `workflow_dispatch` on a feature branch previously
passed the guard and, since wrangler hardcodes `--branch=main` (a
production deploy), would overwrite the live docs site. Non-main
dispatches are now build-only. Also resolves Alfred's deploy-path blocker.
- package.json: drop the direct `cnfast` dependency and delete the dead
`lib/cn.ts` (nothing imports it; a class-merge helper isn't used).
- package.json: declare `zod` (^4.4.3) — it was a phantom dep only
resolving via fumadocs-mdx's hoisted copy. Refresh the lockfile.
- docs page: omit the on-page <DocsDescription>. The frontmatter
description is derived from the first body paragraph, so it rendered
the intro twice on every page. Kept in generateMetadata for SEO/OG.
- team-workflow.md: `openspec store create` does an initial commit, so
scope "never commits" to the user's project and reframe the store
clause as "never clones or syncs on its own."
- README.md: bump stale "20+ AI assistants" to "30+" to match the site.
Verified: npm run types:check + npm run build pass, 26 docs synced,
intro paragraph now renders once per page.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore(website): use pnpm to match the rest of the repo
Per maintainer review (TabishB): the root repo is pnpm (ci.yml runs
`pnpm install --frozen-lockfile` against a v9 `pnpm-lock.yaml`), but
`website/` had introduced npm + a `package-lock.json`. Standardize on
one package manager:
- Replace website/package-lock.json with website/pnpm-lock.yaml
(lockfileVersion 9.0, generated with pnpm v9 to match root).
- deploy-docs.yml: add pnpm/action-setup@v4 (version 9, before
setup-node, as in ci.yml), switch setup-node to `cache: pnpm` /
`cache-dependency-path: website/pnpm-lock.yaml`, and
`npm ci` → `pnpm install --frozen-lockfile`, `npm run build` →
`pnpm run build`.
- package.json scripts + README: `npm run ...` → `pnpm run ...`.
website/ stays a standalone package (no pnpm-workspace.yaml), as before.
Verified: `pnpm install --frozen-lockfile`, `pnpm run build`, and
`pnpm run types:check` all pass — 26 docs synced, 87/87 static pages.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: temporarily disable docs deploy
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
Co-authored-by: TabishB <tabishbidiwale@gmail.com>
* Fix `archive` exit code on validation failure (#1311)
* Fix archive exit code on validation failure
In human (non-JSON) mode, openspec archive returned exit code 0 when
validation failed and nothing was archived. The three blocking paths
in ArchiveCommand.run() printed an error message but returned null
silently, leaving process.exitCode at 0. Scripts and CI could not
distinguish a blocked archive from a successful one.
The --json path was already correct (it throws ArchiveBlockedError,
caught by printJsonFailure which sets exitCode = 1). This was an
asymmetry between the two modes for the same failure.
Set process.exitCode = 1 at the three human-mode abort points before
returning null:
- delta-spec validation failure
- spec rebuild failure
- rebuilt-spec validation failure
Legitimate user cancellations (selecting no change, declining a
confirmation prompt) remain exit 0 by design.
Aligns archive with the same exit-code guarantee already approved for
apply instructions in #1250. References #498.
* Add regression test for rebuilt-spec validation exit code
Cover the third archive blocking path (spot 3): buildUpdatedSpec
succeeds but Validator.validateSpecContent rejects the rebuilt
content. Spy on validateSpecContent (same pattern as the existing
--no-validate test) to force the rebuilt spec invalid while the rest
of the flow runs for real, since this branch is otherwise defensive
and nearly unreachable — spot 1 already enforces the same
SHALL/MUST/scenario rules on the delta.
Asserts process.exitCode === 1, the failure is logged, the main spec
is left unchanged, and no archive is created.
* feat(skills): propose /opsx:update planning-artifact update skill (#1278)
* docs(openspec): propose add-update-workflow — graph-driven /opsx:update + cohesive audit
Dogfooded OpenSpec proposal for the missing first-class "update" action:
a /opsx:update workflow that propagates an edit to one artifact across its
downstream dependents (targeted mode) or audits a whole change for stale/
incoherent artifacts (audit mode) — driven by the schema's artifact graph,
never hardcoded filenames, editing planning artifacts only (never code).
- artifact-graph: expose reverse-dependency queries (getDependents/getDownstream)
+ a requires-edge mtime staleness signal (the engine already builds the
dependents map at graph.ts:98 and discards it).
- cli-artifact-workflow: surface requires/dependents/stale on `openspec status
--json` and add a `--impact <artifact>` downstream-revisit-order selector.
- opsx-update-skill: the user-facing /opsx:update command (targeted + audit).
Supersedes the proposal-only stub add-artifact-regeneration-support. Addresses
the cluster #1188/#705/#673/#247 (closes), #694/#684/#618 (answers), and is
graph-driven to avoid the #777/#666 hardcoded-artifact-pattern bug class.
Validates clean under `openspec validate --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): make add-update-workflow deterministic & grounded (Tabish review)
Reframe per the steer "more deterministic and grounded in reality":
- Deterministic spine: the CLI computes the impact set (which downstream
artifacts to revisit, in build order, with paths) as a pure function of
schema edges + filesystem. The agent only rewrites prose. Grounded in real
APIs already present: getUnlockedArtifacts (direct dependents), getBuildOrder
(order), resolveArtifactOutputs (paths); reverse map built at graph.ts:82-87.
- Replace fragile mtime staleness with a newline-normalized SHA-256 content
digest (reproducible cross-platform). Drift = upstream digest vs recorded
baseline; no baseline => "unknown", never a false positive. mtime and pure-git
rejected with rationale; digest ledger is a separable, optional layer.
- Explicit determinism boundary decision (CLI decides files/order/drift; agent
rewrites). Skill MUST source the file list/order from `openspec status
--impact`, never compute it.
- Corrected all code citations to verified lines (graph.ts:82-87,
instruction-loader.ts:366/429, status.ts); noted #1277's coverage helpers are
not in this branch's base (coordinate, don't reuse).
- Specs updated: artifact-graph Content Digest requirement; cli status digest +
deterministic impact ordering; skill determinism + baseline-aware audit.
tasks add digest/determinism/cross-platform tests + optional ledger section.
Still validates clean under `openspec validate add-update-workflow --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): harden add-update-workflow determinism; drop direct name refs
- Digest ledger tracks DIRECT upstream digests; document that transitive drift
emerges hop-by-hop as downstream is reconciled (no transitive bookkeeping).
- Ground audit's no-baseline structural facts on signals available in this
branch (missing/empty output, blocked/incomplete); capability-coverage is an
add-on only when #1277's validateChangeCapabilityCoverage is present.
- Add the "update revises only existing downstream; defer not-yet-created ones
to /opsx:continue" rule across proposal/design/specs/tasks; impact entries now
carry existence/status.
- Note artifact-level (not file-level) granularity and that getDownstream
terminates by the schema's acyclic guarantee.
- Remove direct personal references from the docs.
Validates clean under `openspec validate add-update-workflow --strict`; 10 deltas.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): full issue/PR/discussion coverage + command-family design
After a comprehensive sweep of open issues, PRs, and discussions, grounded the
proposal in the complete adjacent landscape and answered the open design
questions the cluster raises:
- #783 (Cross-artifact quality review before apply) is now a primary Closes:
it IS audit mode. Answer its open "new skill vs. extend validate" question via
the determinism split — deterministic checks (drift/completeness/coverage) are
CLI/validate-shaped; the semantic cross-artifact review is the skill. Added a
skill spec scenario for the #783 patterns (scope contradiction, spec gap,
duplication).
- Discussion #1206 ("refine proposal now?") + prior-art PR #372: official answer
is /opsx:update.
- New design Decision 8 (command family): delineate /opsx:update from
/opsx:clarify (#702, within-artifact), /opsx:review (#1251, plan-vs-code), and
verify; /opsx:update consolidates update+regen+refine into one action,
addressing skill-sprawl (#1263, #783).
- Reuse, don't reinvent: audit's empty/incomplete check reuses #1098's
artifactOutputComplete (same outputs.ts the digest helper lives in); capability
coverage reuses #1277's validateChangeCapabilityCoverage.
- New open questions: surface deterministic coherence in `validate` for a CI gate
(#783-B, #829); naming reconciliation with #783's /opsx:refine.
- Confirmed add-update-command* branches are the `openspec update` tool-file
refresh (not artifact update) — no collision.
Validates clean under --strict; 10 deltas; all relative links resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): resolve open questions to committed decisions; drift in scope
Per review steer, every open question is now a committed happy-path decision so
build-out has no dangling forks, and the deterministic drift baseline is pulled
into scope (it is what makes audit-mode drift deterministic vs. agent-guessed):
- Digest ledger IN SCOPE (design Decision 3): per-artifact DIRECT upstream
digests in ChangeMetadataSchema, written by a deterministic `openspec status
--record`; pre-existing changes (no baseline) degrade to drift `unknown` +
structural checks. Generating-flow auto-recording stays optional (graceful).
- cli-artifact-workflow spec: folded drift into the digest requirement (record
baseline / drift vs baseline / unknown-without-baseline) — stays at 10 deltas.
- opsx-update-skill spec: skill records baseline via `--record` after each
confirmed edit, so audits clear once reconciled.
- Replaced "## Open Questions" with "## Decisions resolved": ledger in scope;
targeted entry baseline-aware; apply stays standalone (points to update on
drift); cross-change (#247), continue/ff de-hardcoding (#777), and validate
CI-gate (#783-B/#829) are named follow-ups, not deferrals of the core feature;
/opsx:update kept as the umbrella name.
- Migration Plan + Capabilities + Impact + tasks updated; status JSON gains
`drift`, CLI gains `--record`. Re-synced with upstream main (0 behind).
Validates clean under --strict; 10 deltas; all links resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): harden add-update-workflow — close cross-OS, read-only, edge gaps
Stress-tested every claim against live source and fixed the soft spots:
- Cross-OS digest determinism (real bug): resolveArtifactOutputs (outputs.ts:34)
sorts ABSOLUTE paths via .sort(), which differs by OS — so a multi-file glob
artifact (specs/**/*.md) would hash differently on Windows vs POSIX. Digest now
specified to order files by change-relative forward-slash path and hash
relpath+content. Added spec scenarios (cross-platform glob stability; rename
changes digest) and a cross-OS test task.
- Read-only status invariant: moved baseline recording OFF `openspec status`
(a read command silently mutating the drift reference is a footgun) to a
dedicated `openspec reconcile` write verb. Updated spec, skill, design, impact,
capabilities, tasks; reconciled the "no new verb" claims.
- Edge case: missing upstream at record time is stored as an explicit `absent`
marker so later creating it registers as drift (spec scenario added).
- Edge case: coherent change yields no edits (clean-path scenario).
- Grounding fixes: continue-change hardcoded block is duplicated (skill 103-112 +
command 225-234) — both must be fixed in the #777 follow-up; verified no
content-hash util exists.
- Fixed two stale claims the layered edits left: the Impact digest bullet
(concatenation→relative-path) and the naming-boundary line.
Validates clean under --strict; 10 deltas (4+3+3), 44 scenarios; all links
resolve; re-synced with upstream main (0 behind); issue/PR/discussion sweep
re-run, no new items.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): pin data contracts + digest forward-compat; delineate #880
Grounded the surface so an implementer builds it without guessing, and added
proportionate forward-compatibility:
- New design "Data contracts" section with exact shapes: extended ArtifactStatus
(requires/dependents/digest/drift/driftFrom — additive to the real interface at
instruction-loader.ts:120), the --impact response, and the `.openspec.yaml`
baselines ledger. All additive; nothing existing changes type.
- Digest scheme tag (`sha256-relpath-v1:`) + forward-compat: drift compares only
same-scheme digests; an unrecognized/older scheme reports `unknown` rather than
silently mis-comparing — re-reconcile restores it. Added a cli spec scenario
and tasks for it.
- Grounded the ledger write: there is no central change-metadata writer today
(change-metadata/index.ts only re-exports schema), so reconcile does a safe
read-modify-write of .openspec.yaml mirroring the store's
parse/serialize/writeStoreMetadataState pattern (foundation.ts).
- Coverage: re-swept; folded #880 (/opsx:validate code-vs-living-specs) into the
plan-vs-code delineation alongside #1251/#1073. Main unchanged (546224e); all
citations still valid.
Validates clean under --strict; 10 deltas; links resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): simplify add-update-workflow to a thin /opsx:update skill
Rework per @TabishB review (PR #1278): the proposal over-built. Drop the
deterministic-spine machinery and lean on the existing status command.
- Cut the reverse-dependency graph API (getDependents/getDownstream),
SHA-256 content digests, the .openspec.yaml baseline ledger, the
`openspec reconcile` write op, the drift report, and `status --impact`.
Removes the artifact-graph and cli-artifact-workflow spec deltas.
- Reframe propagation as bidirectional coherence (editing design can
require revising proposal), not downstream-only.
- Center the feature on one thin skill over the existing
`openspec status` / `openspec list`; design now sketches the actual
minimal skill instruction body ("written by hand").
- v1 adds no new CLI/graph/schema code: just update-change.ts + wiring.
Validates clean: `openspec validate add-update-workflow --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(update-workflow): pin the status path contract to existingOutputPaths
Address @alfred-openspec's review: the skill's write target was described
loosely as "resolved paths." Make it precise across proposal/design/spec/tasks:
- `openspec status --json` already returns everything the skill needs, in the
top-level `artifactPaths` map — `resolvedOutputPath` and `existingOutputPaths`
per artifact. No new CLI field is required.
- The skill edits `existingOutputPaths` (the concrete, glob-expanded files) and
never writes to `resolvedOutputPath`, which for a glob artifact like
`specs/**/*.md` remains the glob pattern rather than a real file.
- Add spec scenarios for editing a glob artifact's concrete files and for
deferring a brand-new file under a glob artifact to `/opsx:continue`.
- Tighten the cross-platform scenario and add a template test (3.4) asserting
the write target is `existingOutputPaths`, not a glob `resolvedOutputPath`.
Validates clean under `openspec validate add-update-workflow --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(update-workflow): address review — default profile, next-step guidance, change-scoped naming
- Register /opsx:update in the default core profile, not expanded-only
(maintainer call on the PR)
- Add next-step guidance: after updating, recommend /opsx:continue,
/opsx:apply (esp. when the change was already implemented), or
/opsx:archive — guidance only, never acted on
- Pin naming scope: skill openspec-update-change, change proposals only;
generalizing update to other graph types is an explicit non-goal
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(skills): implement the /opsx:update skill (openspec-update-change)
Implements the approved add-update-workflow change: one thin skill over
the existing status/list commands, in the default core profile.
- new update-change.ts template (skill + command), registered across
init, profiles, skill-generation, tool-detection, profile-sync-drift
- update joins CORE_WORKFLOWS and ALL_WORKFLOWS
- docs: opsx.md command row + usage note, commands.md reference section,
supported-tools.md skill list
- retire the superseded add-artifact-regeneration-support stub
- template tests pin the guardrails (schema-driven ids, planning-only,
existingOutputPaths write contract, next-step guidance); parity hashes
regenerated; profile/init/update/config tests cover the new core set
- tasks.md checked off; validate --strict passes
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor: unify requirement reader and surface #498 (#1281)
* docs(openspec): propose spec parser reading fidelity (fixes #361, #498, #312)
The requirement-parsing layer silently misreads valid Markdown:
- #361: requirement-body extraction returns only the first non-blank line,
so a SHALL/MUST that wraps onto line 2 fails `validate --strict`.
- #498: `validate` (delta-block parser) and `archive` (full-spec parser)
recognize requirements by different rules, so a stray `###` header passes
validate but becomes a phantom requirement that blocks archive.
- #312 (residual): the requirement-body loop breaks on any `#` line without
consulting the code-fence mask, truncating bodies that contain fenced
code with `#` comments.
Proposal: one shared, multi-line, fence-aware requirement-body extractor used
by both the validator and the markdown parser; recognize only
`### Requirement:`-prefixed level-3 headers; guarantee validate/archive parity.
Adds regression + parity tests. #559 investigated and deferred (ambiguous root
cause — see design.md).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): bulletproof parser-fidelity proposal with empirical evidence
Hardened the proposal after reproducing every claim against main with the
bundled CLI and correcting two inaccuracies:
- #498 reframed: archive does NOT hard-fail. validate passes; archive emits
NON-BLOCKING phantom "Proposal warnings in proposal.md" because
validateChange/parseRequirements counts every level-3 header as a
requirement, while the delta-block parser (validate) and specs-apply
(rebuild) only recognize canonical `### Requirement:`. It is a consistency
bug, not data loss. Verified the rebuilt spec is clean.
- #312 reframed: the original repro is already fixed by codeFenceLineMask
(requirement count verified correct). The residual is a regression hazard:
the body loop is fence-unaware, harmless only while first-line-only, so the
multi-line fix must be fence-aware from the start.
Also: unify recognition on the canonical REQUIREMENT_HEADER_REGEX
(/^###\s*Requirement:\s*(.+)$/i, case-insensitive); surfaced a third latent
inconsistency (Zod substring includes('SHALL') vs delta word-boundary
\b(SHALL|MUST)\b) and added a single-predicate requirement; verified zero
non-Requirement level-3 headers in repo specs (CI-safe); added edge-case
scenarios (multi-line spec+delta paths, fenced scenario-looking lines,
REMOVED/RENAMED unaffected, display vs detection); replaced broken relative
links with plain paths. Proposal passes `openspec validate --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): deepen parser-fidelity proposal — add #418, upgrade #312, tier the risk
Second adversarial bulletproofing pass (reproduced everything against main):
- Add #418 (metadata-before-description): live on the spec path
(req.text = "**ID**: ...") but ALREADY fixed on the delta path. The
asymmetry is direct evidence for unifying the two extractors.
- Upgrade #312 from "regression hazard" to LIVE bug: a fenced code block
before the prose line makes req.text = "```bash" on both paths today
(distinct from the already-fixed section-count manifestation).
- Tier the fixes by risk after auditing the existing test contract
(markdown-parser.test.ts, 15 tests green on main):
Tier 1 (false-negative fixes #361/#418/#312): only widens what is read;
updates one test (:331, which asserts the first-line bug). Fence tests
(:106/:139) preserved because skip-and-join keeps SHALL-first bodies.
Tier 2 (recognition tightening #498): canonical ### Requirement: only;
a deliberate behavior change that updates bare-header tests (:258/:310)
and needs a migration note. Flagged for maintainer decision, with a
conservative opt-in-lint alternative documented.
- Surface the four-column extractor divergence table (capture / metadata /
recognition / predicate) and an explicit "Behavior changes and test impact"
section with exact test line refs.
Proposal passes `openspec validate --strict`. Does not claim #1156 (PR #1280).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(openspec): third pass — reject recognition tightening, add fenced-scenario bug, #498→safe INFO
Third deep pass found the prior Tier 2 (recognition tightening to
`### Requirement:`) was the WRONG fix and over-scoped:
- Bare `### <statement>` headers are a SUPPORTED, tested requirement format:
test/core/validation.test.ts asserts a bare-header spec is valid, and bare
headers appear across json-converter/archive/spec tests and tmp-init
fixtures. Tightening would break a large test surface and silently drop
requirements from real specs. REJECTED, with evidence documented.
- Replace the #498 fix with a SAFE INFO note in validate <change> that surfaces
non-`### Requirement:` headers in delta sections. INFO never fails validation
(strict: valid = no errors && no warnings), so nothing newly fails.
- New bug found and folded in: countScenarios is fence-unaware, so a `####
Scenario:` inside a fenced block is counted as real — a malformed delta passes
validate <change> while validate <spec> correctly fails. Same fence family.
- Proved the archive WRITE path is independent of the reader: specs-apply
rebuilds from raw `### Requirement:` blocks (extractRequirementsSection +
RequirementBlock.raw), never parseSpec/req.text → Part A cannot change
archived content.
Net effect: recognition is unchanged, so the proposal now updates exactly ONE
existing test (:331, the first-line assertion) instead of breaking bare-header
tests. Consolidated to a single cli-validate delta (dropped cli-archive and
openspec-conventions deltas). Dropped the no-space-header hypothesis (no
divergence). Passes `openspec validate --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(parser): unify the requirement reader, fence/metadata/multi-line aware (#361, #418, #312); surface #498
The requirement reader was implemented twice — MarkdownParser.parseRequirements
(validate <spec>/archive) and Validator.extractRequirementText/countScenarios
(validate <change>) — and the two had drifted. Both now delegate to one shared,
fence-/metadata-/multi-line-aware extraction in parsers/requirement-text.ts so
they cannot diverge again.
Part A — unify the reader:
- Capture the full requirement body up to the first non-fenced `#### Scenario:`,
skipping blank, `**metadata**:`, and fenced-code lines; run SHALL/MUST
detection over the whole body. Fixes a wrapped keyword being dropped (#361),
metadata before the description failing validate <spec> (#418), and a fenced
block before the prose line becoming the requirement text (#312).
- Count only non-fenced `#### ` headers, so a `#### Scenario:` inside a fenced
example no longer counts as a real scenario in validate <change> (parity with
validate <spec>).
- One whole-word `\b(SHALL|MUST)\b` predicate (containsShallOrMust) shared by the
validator and base.schema, replacing the substring/word-boundary split.
- Extract buildCodeFenceMask into the shared module; MarkdownParser and
ChangeParser import it (single fence implementation).
Part B — surface #498 safely:
- validate <change> emits an INFO note when an ADDED/MODIFIED Requirements
section contains a non-`### Requirement:` level-3 header (one the delta reader
silently skips). INFO never changes the valid result, including under --strict,
so nothing newly fails. Recognition is unchanged: bare `### <statement>`
headers remain a supported requirement format.
Write path is unaffected: specs-apply rebuilds from raw `### Requirement:`
blocks, never req.text, so archived content cannot change. Displayed text in JSON
output and delta descriptions now reflects the full body.
Tests: markdown-parser.test.ts:331 updated to expect the full body; regression
tests added for #361/#418/#312, the fenced scenario, the #498 INFO note, a
single-line guard, and CRLF. Changeset added (patch). tasks.md completed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(parser): add cross-reader predicate + metadata-only guards (design edge cases)
Exhaustive verification of the unified reader surfaced two design "edge cases
for tests" not yet covered by committed unit tests:
- Cross-reader predicate agreement: a SHALL substring inside a word ("MARSHALL")
is rejected identically by validate <change> and validate <spec> — proving the
one shared whole-word predicate, and guarding against a regression to the old
substring check.
- Metadata-only body still fails validation (no requirement text) on the delta
path.
Behavior unchanged; tests only. Full end-to-end parity across all four spec
requirements confirmed against the real Validator; no spurious INFO note fires on
any existing repo change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(parser): address review — metadata-only bodies, header-bounded extraction, reader-derived INFO
- Skip **metadata**: lines only when other body text remains; a body written
entirely as metadata (e.g. `**Constraint**: The system MUST ...`) is kept as
the requirement text instead of being emptied (was a regression vs main).
- Move the empty-body rule into the shared reader: both paths fall back to the
header title, so the same block cannot pass one path and fail the other.
- End body extraction at any non-fenced markdown header, restoring old-reader
parity: a stray `### Background` divider's notes no longer satisfy the
SHALL/MUST check.
- Replace the standalone fence-aware INFO scanner with skipped-header
collection inside parseDeltaSpec, so the note reflects exactly what the
reader skipped (same section boundaries, no whole-file fence mask).
- Special-case the nameless `### Requirement:` INFO message; document that the
any-#### scenario match is deliberate spec-path parity; un-export
REQUIREMENT_HEADER_REGEX; move the import up top.
- Soften the changeset claim and list the known remaining divergences in
design.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(openspec): record the no-space ###Requirement: divergence as a known leftover
Jun's edge (reproduced): the delta/write reader's REQUIREMENT_HEADER_REGEX
accepts `###Requirement:` with no space, but MarkdownParser.parseSections
requires whitespace (per GFM) — so a no-space requirement validates as a
change with zero INFO, syncs as-is, then fails validate <spec>. Pre-existing
on main and out of scope here (tightening the shared regex would change
write-path recognition); documented under known remaining divergences with
the follow-up options, folded together with the bullet from the merge
resolution. Corrects c63913b's 'no divergence' note.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: TabishB <tabishbidiwale@gmail.com>
* feat(skills): auto-approve the openspec CLI in generated skills and commands (#1300)
* feat(skills): auto-approve the openspec CLI in generated skills
Emit `allowed-tools: Bash(openspec:*)` in every generated SKILL.md so
agents that honor the Agent Skills standard run `openspec` commands
without prompting on each call. Scope is limited to the CLI; per the
standard `allowed-tools` pre-approves rather than restricts, so every
other tool a skill uses stays available under the user's normal
permission settings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(commands): auto-approve the openspec CLI in Claude slash commands
Extend the allowed-tools pre-approval to the second surface: Claude Code
/opsx:* slash commands share the skill frontmatter contract, so the
Claude command adapter now emits `allowed-tools: Bash(openspec:*)` too.
The value is single-sourced in `src/core/shared/allowed-tools.ts` (a
leaf module both surfaces import). Other command adapters are unchanged
— no other tool's slash-command format defines a per-command
pre-approval field; on the skills side every tool already gets the
standard field via generateSkillContent and non-implementing tools
ignore the unknown key.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix archive scenario drift for #1246 (#1252)
* fix archive scenario drift for #1246
* fix archive scenario drift for #1246
* remove local openspec change docs
* docs: clarify change name format (#1261)
* chore: remove stale npm lockfile (#1319)
* chore: remove stale npm lockfile
* ci: use package manager metadata for pnpm setup
* chore: scope npm lockfile ignore to root
* feat: add Trae command adapter (#1090)
* feat(tools): add Trae command adapter
- Added Trae command adapter for generating `.trae/commands/opsx-<id>.md` files
- Complete unit tests (9 test cases) and integration tests
- Updated documentation and .gitignore
- Fixed YAML escaping for carriage returns (\r)
Co-Authored-By: Claude Code <noreply@anthropic.com>
* fix: handle empty string in YAML escaping
- Add explicit check for empty string in escapeYamlValue
- Return quoted empty string '""' instead of unquoted empty scalar
- Update test to verify empty string is properly quoted
Co-Authored-By: Claude Code <noreply@anthropic.com>
* fix: address PR review feedback for Trae adapter
- Update docs/commands.md Trae entry to reflect generated opsx-* commands
- Export traeAdapter from adapters/index.ts
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs: align Trae command adapter docs
---------
Co-authored-by: jjxyxsjr <jjxyxsjr@users.noreply.github.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
Co-authored-by: TabishB <tabishbidiwale@gmail.com>
* feat: add Oh My Pi (OMP) tool support (#1276)
* feat: add Oh My Pi (OMP) tool support
Add ToolCommandAdapter for Oh My Pi terminal AI coding agent.
- New adapter: src/core/command-generation/adapters/oh-my-pi.ts
- Commands: .omp/commands/opsx-<id>.md with description frontmatter
- Hyphen transform: /opsx: -> /opsx- (filename = command name)
- Argument injection: **Provided arguments**: $@ after **Input**: heading
- escapeYamlValue applied to description field
- Register in CommandAdapterRegistry and adapters/index.ts
- Add oh-my-pi to AI_TOOLS with skillsDir: '.omp'
- Add to hyphen command transformer whitelist in init.ts and update.ts
- Full test coverage (10 cases) in adapters.test.ts
- Update docs/supported-tools.md with directory reference and tool ID
Closes #713
* fix: address CodeRabbit nitpicks
- Move ohMyPiAdapter import before opencodeAdapter (alphabetical order)
- Break long SHALL sentence and remove redundant 'follows after' in spec
* docs: polish Oh My Pi support
* docs: address Oh My Pi review nits
---------
Co-authored-by: TabishB <tabishbidiwale@gmail.com>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
* chore: remove scheduled docs workflow (#1324)
* Fix Windows CI flake hardening (#1325)
* fix windows ci test flake hardening
* restore required test check status
* ci(release): add beta prerelease workflow (#1327)
* ci(release): add beta prerelease workflow
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: harden beta release workflow
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: TabishB <tabishbidiwale@gmail.com>
* fix empty store registration (#1328)
* i18n: 汉化 spec-structure 结构诊断与 SHALL/MUST 缺失提示（含测试断言）
把本次合并「先走英文」的部分块补回中文：
- spec-structure.ts：delta 标题 / 需求在 ## Requirements 之外 两条诊断
- validator：buildMissingShallOrMustMessage 提示文案
- 同步 validation.test / archive.test 断言与 shallIssues 过滤器回中文
全量 1887 测试通过；tsc / eslint 通过。archive.ts 与 v1.6.0 新功能英文待后续批次。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* i18n: 汉化 archive 与 specs-apply（命令输出 + 错误消息 + 测试断言）
- archive.ts：归档流程全部用户可见文案（校验/任务/spec 更新/确认/结果等 ~38 处）
- specs-apply.ts：delta 应用的结构化错误消息（重复/冲突/重命名/结构无效等 ~16 处）
- 同步 archive.test / store-root-selection 断言到中文
- 保留 ### Requirement: / ADDED·MODIFIED 等格式字面量与骨架 spec 英文
全量 1887 测试通过；tsc / eslint 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* i18n: 汉化 legacy-cleanup / update / 多选提示等提示文案（含测试断言）
- legacy-cleanup.ts：清理结果、project.md 迁移提示等
- update.ts：工具最新提示、--force 提示
- searchable-multi-select.ts：搜索/导航/无匹配 UI 文案
- 同步 legacy-cleanup.test / update.test 断言
全量 1887 通过；tsc / eslint 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* i18n: 汉化 view 仪表盘文案（含测试断言）
OpenSpec 仪表盘标题、草稿/活跃/已完成变更、规范、任务进度、需求计数等；同步 view.test。
全量 1887 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* i18n: 汉化 instructions 模板中的 agent 说明与错误提示
<project_context>/<rules>/<template> 等模板注释、tracks 文件缺失/无任务的错误提示。
全量 1887 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* i18n: 汉化剩余零散提示（校验/元数据/多选/标记/工具选择等）
- validator: skipped-header INFO、delta 章节未解析提示
- change-metadata schema、specs-apply ADDED 已存在、init 技能计数、
file-system 标记状态、workset 工具选择、legacy 迁移提示补漏
- 同步各测试断言（含正则）
全量 1887 通过；tsc / eslint 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: 移除上游 changeset（引用 @fission-ai/openspec，不属于本 fork）
上游 v1.6.0-beta.1 带进来的 5 个 changeset 引用上游包名，本仓库不用 changeset
发布（走 tag + pnpm publish），导致 CI 的 Validate Release Tracking 失败。删除之。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(review): 双语化 spec-structure 结构诊断正则（review F1 major）
review-loop 双评审员一致发现：spec-structure.ts 只汉化了消息、未双语化检测正则，
导致 (A) `## 需求` 段内英文 `### Requirement:` 头被误报为「在 ## Requirements 之外」
并使 archive 抛错，(B) 错位的中文 `### 需求：` 需求静默丢失（#498 诊断对中文作者失效）。
- spec-structure.ts：REQUIREMENTS_SECTION_HEADER / DELTA_HEADER / REQUIREMENT_HEADER 双语化
- validator.ts:151：无名头正则 /^requirement:?$/i → /^(?:requirement|需求)[:：]?$/i（F2）
- chinese-bilingual.test：把「验证 RequirementSchema 接受 必须/禁止」的空断言（base.schema
不再强制关键字，任意非空文本都过）改为经 Validator 的真实识别测试（正+负）（F4）；
新增 findMainSpecStructureIssues 双语回归（混合段 / 错位中文 / 中文 delta 头）
已在编译产物上实证：Case A 无误报、Case B 正确标记。全量 1890 通过；tsc / eslint 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(review): 双语化归档场景漂移保护 + 对齐无空格头正则（review round 2）
Codex 跨模型评审发现两处双语盲区 + 一处测试加强：
- C1 (major, 数据丢失): specs-apply.ts parseScenarioBlocks 只认 ASCII `#### Scenario:`，
中文 `#### 场景：` 场景计为 0，使 #1246「陈旧 MODIFIED 丢场景」保护对中文失效——
MODIFIED 可静默删除已有中文场景。改为 `(?:Scenario|场景)[:：]` 双语；
新增归档回归测试（中文场景被丢弃 → 正确中止、老场景保留）。
- C2 (minor): spec-structure REQUIREMENT_HEADER `###\s+` → `###\s*`，与共享读取器
requirement-blocks（`###\s*`，且测试固定支持无空格头）对齐。
- C3 (minor): 加强 over-match 测试为断言 issues 全空（可捕获误判为 delta-header）；
新增无名中文头（全/半角冒号）不被误标的用例。
已实证：parseScenarioBlocks 现能解析中文场景。全量 1892 通过；tsc / eslint 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(review): 场景漂移保护改为围栏感知 + 收紧名称捕获（review round 3）
Codex 第三轮在 parseScenarioBlocks 上又发现两处边界（均已实证）：
- Codex#1 (major): 未做围栏屏蔽——需求正文中围栏代码块内的 `#### 场景：` 示例
被计为真实场景，MODIFIED 保留真实场景时会误判「丢了示例场景」→ 误中止归档。
改用 buildCodeFenceMask，头匹配与边界扫描都跳过围栏行；新增归档回归（围栏内示例
不计、归档成功）。
- Codex#2 (minor): `#### 场景：<空白>` 会以空名匹配，违反无名不匹配。名称捕获
`(.+)` → `(\S.*?)`，要求至少一个非空白字符。
- 抽出 SCENARIO_HEADER_RE 常量，消除双处重复字面量。
实证：围栏内示例不计、纯空白名不计、EN+ZH 混合仍正确。全量 1893 通过；tsc/eslint 通过。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Clay Good <hi@claygood.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
Co-authored-by: TabishB <tabishbidiwale@gmail.com>
Co-authored-by: Danilo <danilopopeye@users.noreply.github.com>
Co-authored-by: zhangsan582 <1553977725@qq.com>
Co-authored-by: Ercan Erdoğan <ercanerdogan@gmail.com>
Co-authored-by: shin <112563017+jjxyxsjr@users.noreply.github.com>
Co-authored-by: jjxyxsjr <jjxyxsjr@users.noreply.github.com>
Co-authored-by: xianzheTM <ylxianzhe@outlook.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a new slash-command
openspec-refinefor agents, in order to provide guidance for the feedback loop mentioned in README.The workflow is now:
Motivation
There exist some issues about the feedback loop #355, the idea to refine the specs #264, or "rollback apply operation" #302. They all reflect the same occasion: the code implementation generated by calling
/openspec-applyoften deviates from expectations. To correct the code implementation, users have two choices:Obviously both choices are not ideal. To make the feedback loop practical, a new command shall be introduced.
Compatibility
The new command does not break the compatibility. It does not change the file structure and no OpenSpec CLI commands needed. Moreover, it respects the
/openspec-applycommand because/openspec-refinedoes not change the code. Users should call/openspec-applyagain after approving the refined change.Summary by CodeRabbit
Release Notes
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.