proposal: Skills-only migration - consolidate to skills-based architecture #544
Conversation
…ture This proposal outlines the migration from the dual old/new system to a skills-only architecture where: - Skills are the source of truth for AI instructions - Commands become lightweight pointers to skills - Smart init detects editors and OpenSpec state - New cleanup command for removing old artifacts - Informative update experience for existing users Includes: - proposal.md: Why and what changes - design.md: Technical decisions and migration plan - specs/: Detailed requirements for 5 capabilities - tasks.md: Implementation checklist (50+ tasks)
📝 WalkthroughWalkthroughAdds design, specs, and task plans to migrate OpenSpec to a SkillDefinition-based generation model, plus multi-editor support via an adapter pattern (Claude Code, Cursor, Windsurf, Cline) and migration tooling (update/cleanup) with cross-platform path requirements. Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 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 |
Greptile SummaryThis proposal consolidates OpenSpec from dual old/new systems to a skills-only architecture where skills are the source of truth and commands are lightweight pointers. Key Changes:
Strengths:
Areas to Validate:
Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant Init as openspec init
participant Update as openspec update
participant Cleanup as openspec cleanup
participant FS as File System
Note over User,FS: New User Flow
User->>Init: openspec init
Init->>FS: Detect editors (.claude/, .cursor/, etc)
Init->>FS: Detect OpenSpec state (AGENTS.md, skills)
Init->>User: Show detection results
User->>Init: Select editors
Init->>FS: Generate .claude/skills/openspec-*/SKILL.md (9 skills)
Init->>FS: Generate .claude/commands/opsx/*.md (9 pointer commands)
Init->>FS: Generate openspec/config.yaml
Init->>User: Setup complete
Note over User,FS: Existing User Migration Flow
User->>Update: openspec update
Update->>FS: Detect old system (AGENTS.md, .claude/agents/)
Update->>FS: Create .claude/skills/openspec-*/SKILL.md (9 skills)
Update->>FS: Create .claude/commands/opsx/*.md (9 pointer commands)
Update->>User: Show upgrade message + cleanup hint
Note right of Update: Old files preserved
User->>Cleanup: openspec cleanup
Cleanup->>FS: Check new skills exist
alt New skills not found
Cleanup->>User: Error: Run openspec update first
else New skills exist
Cleanup->>User: List files to remove
User->>Cleanup: Confirm deletion
Cleanup->>FS: Remove CLAUDE.md
Cleanup->>FS: Remove openspec/AGENTS.md
Cleanup->>FS: Remove .claude/agents/
Cleanup->>FS: Remove .claude/commands/openspec/
Cleanup->>User: Cleanup complete
end
Note over User,FS: Skill Usage Flow
User->>FS: /opsx:new (pointer command)
FS->>FS: Reference openspec-new-change skill
FS->>User: Execute skill instructions
|
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@openspec/changes/skills-only-migration/design.md`:
- Around line 24-27: Update the compound adjective in the "Old System (via
`openspec init`):" bullet for "openspec/AGENTS.md" by replacing "Monolithic ~200
line instruction file" with "Monolithic ~200-line instruction file" so the
phrase is hyphenated correctly.
- Around line 137-150: The fenced output block starting with "Output:" currently
uses plain triple backticks; update that opening fence to include a language tag
(e.g., change ``` to ```text) so markdownlint passes and rendering is correct;
locate the fenced block that contains the "🎉 OpenSpec has a new skills-based
workflow!" output and add the language tag to its opening backticks.
In `@openspec/changes/skills-only-migration/specs/skill-generation/spec.md`:
- Around line 20-31: Under the "## MODIFIED Requirements" section include the
original pre-change requirement block verbatim above the edited version so the
spec delta retains traceability; specifically copy the full original Requirement
block that preceded "Requirement: Skill generation uses unified SkillDefinition
pattern" and then keep your modified block below it, ensuring the
SkillDefinition interface fields (`id`, `name`, `shortcut`, `description`,
`instructions`) remain in the edited version and that the original block is
unaltered and placed immediately before the modified block.
🧹 Nitpick comments (5)
openspec/changes/skills-only-migration/tasks.md (1)
22-29: Consider adding line number references to file paths.File references like
src/core/templates/skill-definitions.tsandartifact-workflow.tscould be more precise with line numbers where applicable (e.g.,skill-definitions.ts:42).Based on coding guidelines, file references should use the format
file.ts:42for clarity. While this may not be necessary for all references in a task planning document, it could help when referencing specific existing code that needs modification.openspec/changes/skills-only-migration/specs/init/spec.md (1)
20-89: MODIFIED requirements could be clearer about what changed.The spec correctly uses
## MODIFIED Requirementsand shows the new behavior. However, for better clarity during review, consider indicating what aspects are changing from the original behavior. For example, you could add a brief note at the start of each modified requirement explaining what's different (e.g., "Changed from: Previously generated AGENTS.md; now generates skills-only").Based on coding guidelines, MODIFIED requirements should help reviewers understand what's being changed. While the new behavior is clearly specified, explicitly highlighting the delta would improve reviewability.
openspec/changes/skills-only-migration/specs/update/spec.md (2)
20-76: MODIFIED requirements could be clearer about changes.Similar to init/spec.md, these MODIFIED requirements show the new behavior clearly but could benefit from explicitly indicating what's changing from the original behavior.
Consider adding a brief note at the beginning of each modified requirement to highlight the key changes (e.g., "Changed from: Previously update only refreshed existing files; now creates new skills for old-system projects").
46-49: Minor: Hyphenate compound adjective.The phrase "already up to date" should be "already up-to-date" when used as a compound adjective.
Style improvement
-#### Scenario: No changes needed output -- **WHEN** user runs `openspec update` and skills are already up to date +#### Scenario: No changes needed output +- **WHEN** user runs `openspec update` and skills are already up-to-dateopenspec/changes/skills-only-migration/specs/skill-generation/spec.md (1)
81-86: Add cross-platform path behavior to this path-based requirement.This requirement references concrete paths but doesn’t explicitly state cross-platform handling. Please add a THEN/AND clause clarifying
path.join()usage or equivalent behavior for Windows/Unix.As per coding guidelines, ...
| **Old System (via `openspec init`):** | ||
| - `CLAUDE.md` - Root stub pointing to AGENTS.md | ||
| - `openspec/AGENTS.md` - Monolithic ~200 line instruction file | ||
| - `.claude/agents/change.md`, `.claude/agents/spec.md` - Subagent definitions |
There was a problem hiding this comment.
Hyphenate compound adjective.
Use “~200-line” for correct grammar.
🧰 Tools
🪛 LanguageTool
[grammar] ~26-~26: Use a hyphen to join words.
Context: ...- openspec/AGENTS.md - Monolithic ~200 line instruction file - `.claude/agents/...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In `@openspec/changes/skills-only-migration/design.md` around lines 24 - 27,
Update the compound adjective in the "Old System (via `openspec init`):" bullet
for "openspec/AGENTS.md" by replacing "Monolithic ~200 line instruction file"
with "Monolithic ~200-line instruction file" so the phrase is hyphenated
correctly.
| Output: | ||
| ``` | ||
| 🎉 OpenSpec has a new skills-based workflow! | ||
|
|
||
| Created: | ||
| ✓ .claude/skills/openspec-*/ (9 skills) | ||
| ✓ .claude/commands/opsx/* (9 shortcut commands) | ||
|
|
||
| These replace the old system. You can now use: | ||
| • Natural language: "I want to start a new change" | ||
| • Shortcuts: /opsx:new, /opsx:apply, /opsx:archive | ||
|
|
||
| Old files are still present. Run `openspec cleanup` when ready. | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced block.
Specify a language (e.g., text) to satisfy markdownlint and improve rendering.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
138-138: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@openspec/changes/skills-only-migration/design.md` around lines 137 - 150, The
fenced output block starting with "Output:" currently uses plain triple
backticks; update that opening fence to include a language tag (e.g., change ```
to ```text) so markdownlint passes and rendering is correct; locate the fenced
block that contains the "🎉 OpenSpec has a new skills-based workflow!" output
and add the language tag to its opening backticks.
| ## MODIFIED Requirements | ||
|
|
||
| ### Requirement: Skill generation uses unified SkillDefinition pattern | ||
| The system SHALL use a single `SkillDefinition[]` array as the source of truth for all skill and command generation. This replaces the 18 separate template functions. | ||
|
|
||
| The SkillDefinition interface SHALL include: | ||
| - `id`: string - Unique identifier (e.g., "new-change") | ||
| - `name`: string - Full skill name for folder (e.g., "openspec-new-change") | ||
| - `shortcut`: string - Command path (e.g., "opsx/new") | ||
| - `description`: string - Used in frontmatter for both skill and command | ||
| - `instructions`: string - Full instruction content (single source of truth) | ||
|
|
There was a problem hiding this comment.
Include the prior requirement block under MODIFIED.
Spec delta format requires the full existing requirement block to be copied under ## MODIFIED Requirements and then edited to reflect changes. Please add the original block before the edited version to preserve traceability.
As per coding guidelines, ...
🤖 Prompt for AI Agents
In `@openspec/changes/skills-only-migration/specs/skill-generation/spec.md` around
lines 20 - 31, Under the "## MODIFIED Requirements" section include the original
pre-change requirement block verbatim above the edited version so the spec delta
retains traceability; specifically copy the full original Requirement block that
preceded "Requirement: Skill generation uses unified SkillDefinition pattern"
and then keep your modified block below it, ensuring the SkillDefinition
interface fields (`id`, `name`, `shortcut`, `description`, `instructions`)
remain in the edited version and that the original block is unaltered and placed
immediately before the modified block.
Split the large skills-only-migration proposal into three manageable parts: 1. add-skill-foundation: SkillDefinition pattern + Claude Code init - Unified SkillDefinition[] array replaces 18 template functions - Skills become single source of truth - Pointer commands reference skills (~5 lines vs ~70 lines) - New projects get skills-only setup 2. add-skill-migration: Update + Cleanup commands - Informative update with upgrade messaging - New cleanup command with --yes and --dry-run - Remove artifact-experimental-setup command - Depends on Part 1 3. add-multi-editor-support: Detection + adapters - Smart init with editor detection - Adapters for Cursor, Windsurf, Cline - Pre-selection of detected editors - Can run parallel with Part 2 after Part 1
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@openspec/changes/add-multi-editor-support/design.md`:
- Around line 101-104: The sentence under "**Cline:**" that reads "- Standard
markdown format" should use the proper noun capitalization by changing
"markdown" to "Markdown"; update the text in the design.md entry (the line
containing "Standard markdown format") to read "Standard Markdown format" so the
noun is capitalized correctly.
- Around line 111-136: The fenced code block in design.md around the sample
output from "$ openspec init" lacks a language tag and triggers markdownlint;
update the triple-backtick opening fence to include a language like "text"
(i.e., change ``` to ```text) for the block that starts with "$ openspec init"
so the example output is properly labeled and lint-cleaned.
In `@openspec/changes/add-multi-editor-support/proposal.md`:
- Around line 21-45: Update the proposal sections ("What Changes",
"Capabilities", "Impact", "Dependencies") to include direct file and spec
references for traceability: insert concrete source-file references and spec
links next to each listed change/capability (for example add entries like
`path/to/file.ts:LINE` and `specs/.../spec.md` adjacent to the Smart init
detection item and the editor adapter bullets), ensure the `smart-init`
capability mentions the initialization entrypoint and config files it touches
and ensure the `skill-generation` modification points to the adapter
implementations, and add a short mapping table under "Dependencies" that lists
the required Part 1 artifacts and their spec files so reviewers can trace
proposals to implementation.
In `@openspec/changes/add-skill-foundation/design.md`:
- Around line 81-84: Add explicit test scenarios and acceptance criteria for the
pointer command pattern: enumerate concrete test cases (e.g., "User sends
`/opsx:new` → Claude Code must resolve and invoke openspec-new-change skill",
"pointer contains minimal context and Claude Code follows the skill reference",
and negative cases where Claude Code ignores the pointer), define pass/fail
acceptance criteria (e.g., Claude Code must call the referenced skill within N
seconds with X% success rate and correct payload mapping), describe test types
and harnesses to run them (unit tests that mock Claude Code responses,
integration tests against a live Claude Code instance, and end-to-end tests
exercising the pointer lifecycle), and specify a clear fallback implementation
to implement if tests fail (e.g., include a minimal in-pointer context, retry
logic, or server-side resolver that maps ambiguous pointers to a default skill)
referencing the pointer command pattern, Claude Code, skill references,
openspec-new-change, and /opsx:new so reviewers can locate the relevant design
sections to update.
In `@openspec/changes/add-skill-foundation/tasks.md`:
- Around line 20-49: Update tasks.md to annotate each checklist entry with a
direct code/spec reference using the unique symbols from the diff so reviewers
can find the target quickly: for section 1 reference the SkillDefinition
interface and the SKILLS array (where SKILLS should be defined), and call out
the generators generateSkillFile(), generatePointerCommand(), and
generateAllSkills() as the targets to implement and migrate from the deprecated
template functions in skill-templates (mark those with `@deprecated`); for
build/workflow changes reference the artifact-workflow integration point that
must invoke generateAllSkills(); for init changes reference the init flow
entrypoints that must instead call the skills generator and respect the --yes
flag; and for testing reference the unit/integration tests to create for
SkillDefinition, SKILLS, generateSkillFile(), generatePointerCommand() and the
init integration test so each checklist item includes the symbol to locate the
exact file to modify.
In `@openspec/changes/add-skill-migration/specs/update/spec.md`:
- Around line 40-52: The fenced code block showing the output should include a
language identifier for proper rendering; update the opening fence (the triple
backticks before "OpenSpec has a new skills-based workflow!") to include a
language token such as "text" so it reads ```text, ensuring the block containing
the lines about skills, created paths, shortcuts, and cleanup renders correctly.
🧹 Nitpick comments (2)
openspec/changes/add-multi-editor-support/specs/smart-init/spec.md (1)
22-43: Consider adding cross-platform detection scenario.While directory detection generally works across platforms, an explicit scenario covering path handling on Windows vs Unix-like systems would strengthen the spec, especially since the context emphasizes cross-platform requirements.
Optional: Add cross-platform detection scenario
#### Scenario: Editor detection works across platforms - **WHEN** user runs `openspec init` on Windows, macOS, or Linux - **THEN** system correctly detects editor directories regardless of platform - **AND** system uses path.join() for all directory checksopenspec/changes/add-skill-migration/specs/update/spec.md (1)
62-82: Add cross-platform path scenarios.The spec includes cross-platform context and rules but lacks explicit scenarios testing path operations on Windows vs Unix-like systems, unlike the init spec (lines 65-73 in init/spec.md). Since update creates files at specific paths, it should validate cross-platform behavior.
Suggested scenarios to add
### Requirement: Update uses cross-platform paths The system SHALL use path.join() for all file path operations during update. #### Scenario: Update on Windows - **WHEN** user runs `openspec update` on Windows - **THEN** system creates all directories with correct paths - **AND** all files are accessible and valid #### Scenario: Update on Unix-like systems - **WHEN** user runs `openspec update` on macOS or Linux - **THEN** system creates all directories with correct paths - **AND** all files are accessible and validAs per coding guidelines: "Requirements involving paths must specify cross-platform behavior"
| **Cline:** | ||
| - Rules: `.cline/rules/openspec-*.md` | ||
| - Standard markdown format | ||
|
|
There was a problem hiding this comment.
Capitalize “Markdown”.
Use the proper noun capitalization in that sentence.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~103-~103: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ....cline/rules/openspec-*.md - Standard markdown format Rationale: Each editor has ...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
In `@openspec/changes/add-multi-editor-support/design.md` around lines 101 - 104,
The sentence under "**Cline:**" that reads "- Standard markdown format" should
use the proper noun capitalization by changing "markdown" to "Markdown"; update
the text in the design.md entry (the line containing "Standard markdown format")
to read "Standard Markdown format" so the noun is capitalized correctly.
| ``` | ||
| $ openspec init | ||
|
|
||
| Detecting project configuration... | ||
|
|
||
| Found: | ||
| Editors: Claude Code, Cursor | ||
| OpenSpec: Old system (AGENTS.md exists) | ||
|
|
||
| Recommendation: Migrate to new skills-based system | ||
|
|
||
| Select editors to configure: (detected editors pre-selected) | ||
| [x] Claude Code | ||
| [x] Cursor | ||
| [ ] Windsurf | ||
| [ ] Cline | ||
|
|
||
| Generating files for Claude Code... | ||
| Created .claude/skills/openspec-*/ (9 skills) | ||
| Created .claude/commands/opsx/* (9 commands) | ||
|
|
||
| Generating files for Cursor... | ||
| Created .cursor/rules/openspec-*.mdc (9 rules) | ||
|
|
||
| Done! Run `openspec cleanup` to remove old artifacts. | ||
| ``` |
There was a problem hiding this comment.
Add a fenced code language tag.
The block should specify a language (e.g., text) to satisfy markdownlint.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
111-111: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@openspec/changes/add-multi-editor-support/design.md` around lines 111 - 136,
The fenced code block in design.md around the sample output from "$ openspec
init" lacks a language tag and triggers markdownlint; update the triple-backtick
opening fence to include a language like "text" (i.e., change ``` to ```text)
for the block that starts with "$ openspec init" so the example output is
properly labeled and lint-cleaned.
| ## What Changes | ||
|
|
||
| - **Smart init detection**: `openspec init` detects existing editor configs and OpenSpec state | ||
| - **Editor adapters**: Unified generation for Claude Code, Cursor, Windsurf, and Cline | ||
| - **Pre-selection**: Detected editors are pre-selected in the init wizard | ||
| - **State awareness**: Init recommends actions based on detected OpenSpec state (uninitialized, old system, new system, mixed) | ||
|
|
||
| ## Capabilities | ||
|
|
||
| ### New Capabilities | ||
| - `smart-init`: Enhanced initialization with editor detection and state-aware recommendations | ||
|
|
||
| ### Modified Capabilities | ||
| - `skill-generation`: Multi-editor generation with adapter pattern | ||
|
|
||
| ## Impact | ||
|
|
||
| - **Init flow**: Significant enhancement with detection and smart defaults | ||
| - **New editor formats**: Support for Cursor, Windsurf, Cline rule formats | ||
| - **User experience**: Better onboarding with pre-selected options | ||
| - **Future extensibility**: Adapter pattern allows adding more editors | ||
|
|
||
| ## Dependencies | ||
|
|
||
| - Requires Part 1 (add-skill-foundation) to be completed first |
There was a problem hiding this comment.
Add direct file/spec references for traceability.
Please add references like path/to/file.ts:42 and specs/.../spec.md where relevant to align with proposal formatting rules. As per coding guidelines, include direct file references for proposals.
🤖 Prompt for AI Agents
In `@openspec/changes/add-multi-editor-support/proposal.md` around lines 21 - 45,
Update the proposal sections ("What Changes", "Capabilities", "Impact",
"Dependencies") to include direct file and spec references for traceability:
insert concrete source-file references and spec links next to each listed
change/capability (for example add entries like `path/to/file.ts:LINE` and
`specs/.../spec.md` adjacent to the Smart init detection item and the editor
adapter bullets), ensure the `smart-init` capability mentions the initialization
entrypoint and config files it touches and ensure the `skill-generation`
modification points to the adapter implementations, and add a short mapping
table under "Dependencies" that lists the required Part 1 artifacts and their
spec files so reviewers can trace proposals to implementation.
| **Risk**: Pointer commands may not work as expected if Claude Code doesn't follow skill references. | ||
|
|
||
| **Mitigation**: Test with Claude Code. Fallback: include minimal context in pointer if needed. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Strengthen testing plan for pointer command pattern.
The risk mitigation mentions "Test with Claude Code" but doesn't specify acceptance criteria or testing approach. Since the entire architecture depends on Claude Code following skill references, this should have explicit test scenarios.
Consider adding to the design:
- Specific test cases (e.g., "User invokes
/opsx:new→ Claude Code loads openspec-new-change skill") - Acceptance criteria for the pointer pattern
- Fallback implementation details if testing reveals issues
Based on the risk level, this should be validated before merging Part 1.
🤖 Prompt for AI Agents
In `@openspec/changes/add-skill-foundation/design.md` around lines 81 - 84, Add
explicit test scenarios and acceptance criteria for the pointer command pattern:
enumerate concrete test cases (e.g., "User sends `/opsx:new` → Claude Code must
resolve and invoke openspec-new-change skill", "pointer contains minimal context
and Claude Code follows the skill reference", and negative cases where Claude
Code ignores the pointer), define pass/fail acceptance criteria (e.g., Claude
Code must call the referenced skill within N seconds with X% success rate and
correct payload mapping), describe test types and harnesses to run them (unit
tests that mock Claude Code responses, integration tests against a live Claude
Code instance, and end-to-end tests exercising the pointer lifecycle), and
specify a clear fallback implementation to implement if tests fail (e.g.,
include a minimal in-pointer context, retry logic, or server-side resolver that
maps ambiguous pointers to a default skill) referencing the pointer command
pattern, Claude Code, skill references, openspec-new-change, and /opsx:new so
reviewers can locate the relevant design sections to update.
| ## 1. SkillDefinition Pattern | ||
|
|
||
| - [ ] 1.1 Create `SkillDefinition` interface in `src/core/templates/skill-definitions.ts` | ||
| - [ ] 1.2 Define `SKILLS` array with all 9 skill definitions (id, name, shortcut, description, instructions) | ||
| - [ ] 1.3 Migrate instruction content from existing template functions to SKILLS array | ||
| - [ ] 1.4 Create `generateSkillFile()` function that writes SKILL.md from definition | ||
| - [ ] 1.5 Create `generatePointerCommand()` function that writes minimal command referencing skill | ||
| - [ ] 1.6 Create `generateAllSkills()` function that iterates SKILLS and generates both files | ||
| - [ ] 1.7 Deprecate old 18 template functions in `skill-templates.ts` (mark with @deprecated) | ||
| - [ ] 1.8 Update `artifact-workflow.ts` to use new unified generator | ||
|
|
||
| ## 2. Init Command Updates (Claude Code Only) | ||
|
|
||
| - [ ] 2.1 Update init to generate skills-only setup for new projects | ||
| - [ ] 2.2 Remove generation of CLAUDE.md stub file for new projects | ||
| - [ ] 2.3 Remove generation of AGENTS.md for new projects | ||
| - [ ] 2.4 Remove generation of .claude/agents/ for new projects | ||
| - [ ] 2.5 Remove generation of .claude/commands/openspec/ for new projects | ||
| - [ ] 2.6 Integrate skill generation into init flow (skills + pointer commands) | ||
| - [ ] 2.7 Ensure --yes flag works for non-interactive init | ||
| - [ ] 2.8 Verify cross-platform path handling (use path.join throughout) | ||
|
|
||
| ## 3. Testing | ||
|
|
||
| - [ ] 3.1 Add unit tests for SkillDefinition interface and SKILLS array | ||
| - [ ] 3.2 Add unit tests for generateSkillFile() function | ||
| - [ ] 3.3 Add unit tests for generatePointerCommand() function | ||
| - [ ] 3.4 Add integration test for init on fresh project (verify no old artifacts) | ||
| - [ ] 3.5 Verify Windows CI passes (cross-platform path handling) | ||
| - [ ] 3.6 Manual testing of init → verify skills work in Claude Code |
There was a problem hiding this comment.
Add direct file/spec references in task items.
Please annotate tasks with references like path/to/file.ts:42 or specs/.../spec.md to align with tasks formatting rules. As per coding guidelines, tasks.md should include direct file references.
🤖 Prompt for AI Agents
In `@openspec/changes/add-skill-foundation/tasks.md` around lines 20 - 49, Update
tasks.md to annotate each checklist entry with a direct code/spec reference
using the unique symbols from the diff so reviewers can find the target quickly:
for section 1 reference the SkillDefinition interface and the SKILLS array
(where SKILLS should be defined), and call out the generators
generateSkillFile(), generatePointerCommand(), and generateAllSkills() as the
targets to implement and migrate from the deprecated template functions in
skill-templates (mark those with `@deprecated`); for build/workflow changes
reference the artifact-workflow integration point that must invoke
generateAllSkills(); for init changes reference the init flow entrypoints that
must instead call the skills generator and respect the --yes flag; and for
testing reference the unit/integration tests to create for SkillDefinition,
SKILLS, generateSkillFile(), generatePointerCommand() and the init integration
test so each checklist item includes the symbol to locate the exact file to
modify.
| ``` | ||
| OpenSpec has a new skills-based workflow! | ||
|
|
||
| Created: | ||
| .claude/skills/openspec-*/ (9 skills) | ||
| .claude/commands/opsx/* (9 shortcut commands) | ||
|
|
||
| These replace the old system. You can now use: | ||
| Natural language: "I want to start a new change" | ||
| Shortcuts: /opsx:new, /opsx:apply, /opsx:archive | ||
|
|
||
| Old files are still present. Run `openspec cleanup` when ready. | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language identifier to code block.
The fenced code block showing the output format should specify a language identifier for proper rendering.
Fix: Add language identifier
-```
+```text
OpenSpec has a new skills-based workflow!As per static analysis hints.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
40-40: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@openspec/changes/add-skill-migration/specs/update/spec.md` around lines 40 -
52, The fenced code block showing the output should include a language
identifier for proper rendering; update the opening fence (the triple backticks
before "OpenSpec has a new skills-based workflow!") to include a language token
such as "text" so it reads ```text, ensuring the block containing the lines
about skills, created paths, shortcuts, and cleanup renders correctly.
…roposals Removed the original skills-only-migration proposal since all content has been distributed to the three focused proposals. Gaps fixed in add-skill-foundation (Part 1): - Added "Init handles already-initialized projects gracefully" requirement - Added scenarios for init on old system and new system projects - Added CI/non-TTY environment scenario - Added tasks for existing project detection and handling - Added integration tests for existing project scenarios Gaps fixed in add-skill-migration (Part 2): - Added documentation section with 4 tasks: - Migration guide for existing users - Cleanup command documentation - CLI help text updates - Deprecation notice for artifact-experimental-setup Gaps fixed in add-multi-editor-support (Part 3): - Added "Detect mixed state" scenario (both old and new artifacts) - Added test tasks for mixed state handling
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@openspec/changes/add-multi-editor-support/specs/smart-init/spec.md`:
- Around line 22-43: Add a new "Scenario: Detect editor configurations on
Windows paths" section under "Requirement: Init detects existing editor
configurations" that describes running `openspec init` in a project where editor
config directories exist using Windows-style paths (e.g., backslashes, drive
letters) and notes that detection should work with path.resolve/path.join
semantics; reference the command `openspec init`, the listed editor dirs
(`.claude/`, `.cursor/`, `.windsurf/`, `.cline/`), and state expected outcomes:
detection of editors, appropriate pre-selection, and that behavior matches POSIX
detection semantics on Windows.
♻️ Duplicate comments (1)
openspec/changes/add-skill-foundation/tasks.md (1)
20-54: Add direct file/spec references to each task item.Checklist entries should reference targets like
src/.../file.ts:42orspecs/.../spec.mdso implementers can locate the change points quickly. As per coding guidelines.
| ### Requirement: Init detects existing editor configurations | ||
| The system SHALL scan for existing editor configuration directories to inform setup recommendations. Detection targets: | ||
| - `.claude/` - Claude Code | ||
| - `.cursor/` - Cursor | ||
| - `.windsurf/` - Windsurf | ||
| - `.cline/` - Cline | ||
|
|
||
| #### Scenario: Detect Claude Code configuration | ||
| - **WHEN** user runs `openspec init` in a project with `.claude/` directory | ||
| - **THEN** system detects Claude Code as a configured editor | ||
| - **AND** system pre-selects Claude Code in the editor selection | ||
|
|
||
| #### Scenario: Detect multiple editor configurations | ||
| - **WHEN** user runs `openspec init` in a project with both `.claude/` and `.cursor/` directories | ||
| - **THEN** system detects both Claude Code and Cursor as configured editors | ||
| - **AND** system pre-selects both in the editor selection | ||
|
|
||
| #### Scenario: No editor configurations detected | ||
| - **WHEN** user runs `openspec init` in a project with no editor config directories | ||
| - **THEN** system shows all available editors without pre-selection | ||
| - **AND** system informs user that no existing editor configs were detected | ||
|
|
There was a problem hiding this comment.
Add a Windows path scenario for editor config detection.
These requirements deal with filesystem paths/directories but don’t include a Windows-specific scenario or cross-platform behavior callout. Please add a #### Scenario: that covers Windows path handling (e.g., detection on Windows with path.join/path.resolve semantics). As per coding guidelines.
🤖 Prompt for AI Agents
In `@openspec/changes/add-multi-editor-support/specs/smart-init/spec.md` around
lines 22 - 43, Add a new "Scenario: Detect editor configurations on Windows
paths" section under "Requirement: Init detects existing editor configurations"
that describes running `openspec init` in a project where editor config
directories exist using Windows-style paths (e.g., backslashes, drive letters)
and notes that detection should work with path.resolve/path.join semantics;
reference the command `openspec init`, the listed editor dirs (`.claude/`,
`.cursor/`, `.windsurf/`, `.cline/`), and state expected outcomes: detection of
editors, appropriate pre-selection, and that behavior matches POSIX detection
semantics on Windows.
Two-part approach using smart `update` instead of new commands.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@openspec/changes/skills-only-migration.napkin.md`:
- Around line 22-45: Update the fenced code block in
openspec/changes/skills-only-migration.napkin.md by changing the opening fence
from ``` to ```bash (or ```text) so the block has a language hint and satisfies
markdownlint MD040; locate the large example block that starts with "$ openspec
update" and add the language token after the initial backticks.
| ``` | ||
| $ openspec update | ||
|
|
||
| # Detects state and acts accordingly: | ||
|
|
||
| # If nothing exists: | ||
| No openspec setup found. Run 'openspec init' first. | ||
|
|
||
| # If already modern: | ||
| Updating skills... | ||
| ✓ 12 skills up to date | ||
| ✓ Editor configs refreshed | ||
|
|
||
| # If legacy detected: | ||
| Legacy setup detected. | ||
|
|
||
| This will: | ||
| • Create skills/ (12 skills) | ||
| • Create editor configs | ||
| • Backup existing to .openspec/backup/ | ||
| • Remove AGENTS.md and old templates | ||
|
|
||
| Proceed? [Y/n] | ||
| ``` |
There was a problem hiding this comment.
Add a fenced code language for lint compliance.
Markdownlint flags the code block without a language. Add bash (or text) to avoid MD040.
✅ Proposed fix
-```
+```bash
$ openspec update
@@
Proceed? [Y/n]
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
22-22: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@openspec/changes/skills-only-migration.napkin.md` around lines 22 - 45,
Update the fenced code block in openspec/changes/skills-only-migration.napkin.md
by changing the opening fence from ``` to ```bash (or ```text) so the block has
a language hint and satisfies markdownlint MD040; locate the large example block
that starts with "$ openspec update" and add the language token after the
initial backticks.
Summary
This proposal outlines the migration from the current dual old/new OpenSpec system to a skills-only architecture. Based on an extensive exploration session, we made 9 key decisions:
Artifacts
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.