feat(workflow): Add openspec-refine slash command for feedback loop.
#372
Conversation
…cally and `openspec-refine` works well.
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}
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** |
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.
|
Hi @TabishB, do you think we should convert this PR to draft if you're cautious about adding new slash commands? |
|
@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. |
|
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. |
2 participants
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.