feat(cli): merge init and experimental commands #564
Conversation
This change merges `openspec init` and `openspec experimental` into a single command that uses the skill-based workflow as the default. Key changes: - BREAKING: init generates skills and /opsx:* commands instead of config files - BREAKING: Config files (CLAUDE.md, .cursorrules, etc.) no longer generated - BREAKING: Old slash commands (/openspec:proposal, etc.) no longer generated - BREAKING: openspec/AGENTS.md and project.md no longer generated - Add legacy detection and cleanup with Y/N confirmation - Keep experimental as hidden alias for backward compatibility Artifacts: - proposal.md: Motivation and scope - design.md: Architecture decisions and edge case handling - specs/legacy-cleanup/spec.md: New capability for legacy artifact cleanup - specs/cli-init/spec.md: Modified init spec with skill-based workflow - tasks.md: 37 implementation tasks across 7 groups
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughMerges experimental init behavior into Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
Greptile SummaryThis change proposal merges Key Changes:
Strengths:
Attention Needed:
Confidence Score: 4/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant CLI as openspec init
participant Legacy as Legacy Cleanup
participant Welcome as Welcome Screen
participant MultiSelect as Tool Selector
participant Skills as Skill Generator
participant Commands as Command Generator
participant FS as File System
User->>CLI: Run openspec init
CLI->>Legacy: Detect legacy artifacts
Legacy->>FS: Check for config files (CLAUDE.md, etc.)
Legacy->>FS: Check for old slash commands (/openspec:*)
Legacy->>FS: Check for AGENTS.md, project.md
alt Legacy artifacts found
Legacy-->>CLI: Legacy detected
CLI->>User: Display detected files
CLI->>User: Prompt "Upgrade and clean up? [Y/n]"
alt User confirms (Y)
User-->>CLI: Yes
CLI->>Legacy: Clean up artifacts
Legacy->>FS: Remove OpenSpec marker blocks
Legacy->>FS: Delete legacy directories
Legacy->>FS: Delete legacy files
Legacy-->>CLI: Cleanup complete
CLI->>User: Display cleanup summary
else User declines (N)
User-->>CLI: No
CLI->>User: Abort with cleanup instructions
end
end
CLI->>Welcome: Show animated welcome screen
Welcome-->>User: Display OpenSpec logo animation
CLI->>MultiSelect: Show tool selection
MultiSelect->>FS: Check for existing tool configs
MultiSelect-->>User: Show tools (configured marked ✓)
User->>MultiSelect: Select tools (Claude, Cursor, etc.)
MultiSelect-->>CLI: Selected tools
CLI->>FS: Create openspec/ structure
FS-->>CLI: Directories created
CLI->>FS: Create openspec/config.yaml
FS-->>CLI: Config created
loop For each selected tool
CLI->>Skills: Generate 9 skills
Skills->>FS: Create .<tool>/skills/openspec-*/SKILL.md
FS-->>Skills: Skills created
CLI->>Commands: Generate 9 slash commands
Commands->>FS: Create .<tool>/commands/opsx/*.md
FS-->>Commands: Commands created
end
CLI->>User: Display success summary
CLI->>User: Show next steps (/opsx:new, /opsx:continue)
CLI->>User: Remind to restart IDE
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| 1. **What happens to `openspec update`?** - Currently updates config files and AGENTS.md. Needs to be updated to refresh skills/commands instead. | ||
|
|
||
| 2. **Should we keep `openspec schemas` and other experimental subcommands?** - These are useful for the workflow. Probably keep them but remove "[Experimental]" label. |
There was a problem hiding this comment.
style: Resolve this open question before starting implementation. The update command currently refreshes config files and AGENTS.md, which this proposal removes. Tasks 5.1-5.3 address the implementation, but deciding the approach now will prevent rework and ensure the architecture is sound.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: openspec/changes/merge-init-experimental/design.md
Line: 156:158
Comment:
**style:** Resolve this open question before starting implementation. The `update` command currently refreshes config files and `AGENTS.md`, which this proposal removes. Tasks 5.1-5.3 address the implementation, but deciding the approach now will prevent rework and ensure the architecture is sound.
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.…ting Update merge-init-experimental change artifacts to preserve openspec/project.md during legacy cleanup instead of auto-deleting it. Users will see a migration hint directing them to move content to config.yaml's context field. Changes: - design.md: Add Decision 6 documenting rationale and migration path - spec.md: Add project.md migration hint requirement and scenarios - tasks.md: Add task 1.7 for migration hint output This avoids losing user-written project documentation while guiding them to the new config.yaml approach.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@openspec/changes/merge-init-experimental/specs/legacy-cleanup/spec.md`:
- Around line 117-121: Add a language identifier to the fenced code blocks in
the spec so they pass MD040: update the block beginning with the triple
backticks that contains "Manual migration needed:" to use ```text (or ```md)
instead of plain ```, and make the same change for the other fenced example
mentioned (lines around the block containing "Also applies to: 138-143") so both
fenced blocks explicitly declare their language.
- Around line 9-20: The scenario uses bullet points with bolded WHEN/THEN
instead of the required plain WHEN/THEN lines under the "#### Scenario:" header;
replace the bulleted entries like "- **WHEN** running `openspec init` on an
existing project" and "- **THEN** the system SHALL check for config files..."
plus the listed config filenames with non-bulleted lines reading "WHEN running
`openspec init` on an existing project" and "THEN the system SHALL check for
config files with OpenSpec markers: `CLAUDE.md`, `.cursorrules`,
`.windsurfrules`, `.clinerules`, `.kilocode_rules`,
`.github/copilot-instructions.md`, `.amazonq/instructions.md`, `CODEBUDDY.md`,
`IFLOW.md`, and other legacy ToolRegistry files" placed directly beneath the
"#### Scenario:" header to match the spec conventions.
🧹 Nitpick comments (1)
openspec/changes/merge-init-experimental/design.md (1)
59-88: Consider reordering decision numbers for readability.Decision 6 appears before Decisions 4–5. Reordering or renumbering would improve scanability.
| - **WHEN** running `openspec init` on an existing project | ||
| - **THEN** the system SHALL check for config files with OpenSpec markers: | ||
| - `CLAUDE.md` | ||
| - `.cursorrules` | ||
| - `.windsurfrules` | ||
| - `.clinerules` | ||
| - `.kilocode_rules` | ||
| - `.github/copilot-instructions.md` | ||
| - `.amazonq/instructions.md` | ||
| - `CODEBUDDY.md` | ||
| - `IFLOW.md` | ||
| - And all other tool config files from the legacy ToolRegistry |
There was a problem hiding this comment.
Align scenario formatting with spec conventions (no bullets/bold).
Spec files require plain WHEN/THEN lines under #### Scenario:; the current bullet+bold style is out of spec. Please normalize all scenarios to the required format. As per coding guidelines, ...
✅ Example format (apply consistently)
-#### Scenario: Detecting legacy config files
-
-- **WHEN** running `openspec init` on an existing project
-- **THEN** the system SHALL check for config files with OpenSpec markers:
+#### Scenario: Detecting legacy config files
+WHEN running `openspec init` on an existing project
+THEN the system SHALL check for config files with OpenSpec markers:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **WHEN** running `openspec init` on an existing project | |
| - **THEN** the system SHALL check for config files with OpenSpec markers: | |
| - `CLAUDE.md` | |
| - `.cursorrules` | |
| - `.windsurfrules` | |
| - `.clinerules` | |
| - `.kilocode_rules` | |
| - `.github/copilot-instructions.md` | |
| - `.amazonq/instructions.md` | |
| - `CODEBUDDY.md` | |
| - `IFLOW.md` | |
| - And all other tool config files from the legacy ToolRegistry | |
| #### Scenario: Detecting legacy config files | |
| WHEN running `openspec init` on an existing project | |
| THEN the system SHALL check for config files with OpenSpec markers: | |
| - `CLAUDE.md` | |
| - `.cursorrules` | |
| - `.windsurfrules` | |
| - `.clinerules` | |
| - `.kilocode_rules` | |
| - `.github/copilot-instructions.md` | |
| - `.amazonq/instructions.md` | |
| - `CODEBUDDY.md` | |
| - `IFLOW.md` | |
| - And all other tool config files from the legacy ToolRegistry |
🤖 Prompt for AI Agents
In `@openspec/changes/merge-init-experimental/specs/legacy-cleanup/spec.md` around
lines 9 - 20, The scenario uses bullet points with bolded WHEN/THEN instead of
the required plain WHEN/THEN lines under the "#### Scenario:" header; replace
the bulleted entries like "- **WHEN** running `openspec init` on an existing
project" and "- **THEN** the system SHALL check for config files..." plus the
listed config filenames with non-bulleted lines reading "WHEN running `openspec
init` on an existing project" and "THEN the system SHALL check for config files
with OpenSpec markers: `CLAUDE.md`, `.cursorrules`, `.windsurfrules`,
`.clinerules`, `.kilocode_rules`, `.github/copilot-instructions.md`,
`.amazonq/instructions.md`, `CODEBUDDY.md`, `IFLOW.md`, and other legacy
ToolRegistry files" placed directly beneath the "#### Scenario:" header to match
the spec conventions.
| ``` | ||
| Manual migration needed: | ||
| → openspec/project.md still exists | ||
| Move useful content to config.yaml's "context:" field, then delete | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced blocks.
Use text (or md) for the example blocks to satisfy MD040.
✅ Example fix
- ```
+ ```text
Manual migration needed:
→ openspec/project.md still exists
Move useful content to config.yaml's "context:" field, then delete</details>
Also applies to: 138-143
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @openspec/changes/merge-init-experimental/specs/legacy-cleanup/spec.md around
lines 117 - 121, Add a language identifier to the fenced code blocks in the spec
so they pass MD040: update the block beginning with the triple backticks that
contains "Manual migration needed:" to use text (or md) instead of plain
around the block containing "Also applies to: 138-143") so both fenced blocks
explicitly declare their language.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@openspec/changes/merge-init-experimental/design.md`:
- Around line 106-134: The fenced code block in design.md is missing a language
identifier; update the triple-backtick fence that contains the openspec/ tree to
use a plain text specifier (e.g., change ``` to ```text or ```plaintext) so the
block is recognized as plaintext and the markdownlint warning is resolved;
locate the block around the openspec/ tree in
openspec/changes/merge-init-experimental/design.md and modify the opening fence
accordingly.
🧹 Nitpick comments (3)
openspec/changes/merge-init-experimental/design.md (3)
59-59: Consider renumbering decisions sequentially.Decision 6 appears before Decisions 4 and 5. While the current placement groups related legacy-handling decisions together (3 and 6), sequential numbering (1-6) would improve document navigation and readability.
136-142: Consider adding a clarification note for project.md.Line 140 states
openspec/project.mdis no longer created, while Decision 6 (lines 59-80) describes preserving existing project.md files during migration. These are consistent (fresh init vs. migration), but a brief note cross-referencing Decision 6 would prevent confusion.Example clarification
### What init no longer creates - `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc. (config files) - `openspec/AGENTS.md` -- `openspec/project.md` +- `openspec/project.md` (not created in fresh init; existing files preserved per Decision 6) - Root `AGENTS.md` stub
93-101: Consider cross-referencing the risks table with resolved questions.Line 100 mentions reviewing the
openspec updatecommand as mitigation, which is now comprehensively addressed in Open Question 1 (lines 178-190). Adding a reference would improve document navigation.Example enhancement
| Risk | Mitigation | |------|------------| | Users with custom `/openspec:*` commands lose them | Document in release notes; old commands are in git history | | Mixed-content detection might be imperfect | Conservative approach: if unsure, preserve the file and warn | | Users confused by missing config files | Clear messaging in init output about what changed | -| `openspec update` might break | Review and update `update` command to work with new structure | +| `openspec update` might break | Review and update `update` command to work with new structure (see Open Question 1) |
| ``` | ||
| openspec/ | ||
| ├── config.yaml # Schema settings (from experimental) | ||
| ├── specs/ # Empty, for user's specs | ||
| └── changes/ # Empty, for user's changes | ||
| └── archive/ | ||
|
|
||
| .<tool>/skills/ # 9 skills per selected tool | ||
| ├── openspec-explore/SKILL.md | ||
| ├── openspec-new-change/SKILL.md | ||
| ├── openspec-continue-change/SKILL.md | ||
| ├── openspec-apply-change/SKILL.md | ||
| ├── openspec-ff-change/SKILL.md | ||
| ├── openspec-verify-change/SKILL.md | ||
| ├── openspec-sync-specs/SKILL.md | ||
| ├── openspec-archive-change/SKILL.md | ||
| └── openspec-bulk-archive-change/SKILL.md | ||
|
|
||
| .<tool>/commands/opsx/ # 9 slash commands per selected tool | ||
| ├── explore.md | ||
| ├── new.md | ||
| ├── continue.md | ||
| ├── apply.md | ||
| ├── ff.md | ||
| ├── verify.md | ||
| ├── sync.md | ||
| ├── archive.md | ||
| └── bulk-archive.md | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The fenced code block lacks a language identifier. Add text or plaintext to resolve the markdownlint warning.
📝 Proposed fix
-```
+```text
openspec/
├── config.yaml # Schema settings (from experimental)
├── specs/ # Empty, for user's specs🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@openspec/changes/merge-init-experimental/design.md` around lines 106 - 134,
The fenced code block in design.md is missing a language identifier; update the
triple-backtick fence that contains the openspec/ tree to use a plain text
specifier (e.g., change ``` to ```text or ```plaintext) so the block is
recognized as plaintext and the markdownlint warning is resolved; locate the
block around the openspec/ tree in
openspec/changes/merge-init-experimental/design.md and modify the opening fence
accordingly.
Summary
openspec initandopenspec experimentalinto a single commandBreaking Changes
openspec initnow generates skills and/opsx:*commands instead of config filesCLAUDE.md,.cursorrules, etc.) are no longer generated/openspec:proposal,/openspec:apply,/openspec:archive) are no longer generatedopenspec/AGENTS.mdandopenspec/project.mdare no longer generatedArtifacts
proposal.mddesign.mdspecs/legacy-cleanup/spec.mdspecs/cli-init/spec.mdtasks.mdTest plan
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.