feat: add Claude Code plugin structure (skills + commands + .claude-plugin)#1122
feat: add Claude Code plugin structure (skills + commands + .claude-plugin)#1122CYL090315 wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughThis PR adds comprehensive workflow documentation and AI skill specifications for four core OpenSpec operations: proposing new changes, exploring problems, applying implementations, and archiving completed work. It includes a plugin manifest update and paired command documentation with skill instructions for each workflow. ChangesOpenSpec CLI Workflows
Sequence Diagram(s)Diagrams are not generated for this change because the PR is primarily documentation and workflow specifications without observable multi-component runtime interactions or control-flow changes. The defined workflows are behavioral contracts for AI skill execution rather than code paths requiring flow visualization. Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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: 10
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude-plugin/plugin.json:
- Line 1: The manifest JSON file contains a leading UTF-8 BOM (U+FEFF) before
the opening “{” which can break strict JSON parsers; open the plugin manifest,
remove the hidden BOM character at the very start (or re-save the file as UTF-8
without BOM), and ensure the file now begins directly with “{” so the JSON
parses cleanly.
In `@commands/opsx/apply.md`:
- Around line 88-98: The unlabeled fenced code blocks under the "Implementing:
<change-name> (schema: <schema-name>)" example (and the other example blocks
later) are causing MD040 warnings; fix by adding a language specifier to each
triple-backtick fence (e.g., ```text or ```output or ```console) for the example
output blocks, updating the fences shown in the example snippet and the similar
examples at the other occurrences so all fenced blocks include an explicit
language.
- Around line 44-45: In commands/opsx/apply.md update the guidance for state:
"blocked" to stop referencing the non-existent `/opsx:continue` command; locate
the "blocked" message branch and replace `/opsx:continue` with an actual
command/flow exposed by this PR (or, if no direct resume command exists, point
users to a valid alternative such as `/opsx help` or the documented resume flow
name used elsewhere in the codebase) and update the message text to reflect that
real command/flow.
In `@commands/opsx/archive.md`:
- Around line 92-101: The fenced code blocks under the "## Archive Complete"
section (and the other similar blocks at the ranges called out) are unlabeled
and trigger MD040; add the language tag "text" to each triple-backtick fence
(e.g., change ``` to ```text) for the blocks containing the Archive Complete
content, the blocks at 105-114, 118-132, and 136-148 so the markdown linter
recognizes them as plain text.
In `@commands/opsx/explore.md`:
- Around line 57-72: The fenced ASCII diagram block is unlabeled and triggers
MD040; update the opening fence from ``` to a language tag such as ```text (or
```ascii) so the block becomes labeled and lint-safe; locate the ASCII diagram
fenced block in the explore.md content and replace the unlabeled triple-backtick
with a tagged fence.
In `@commands/opsx/propose.md`:
- Around line 62-66: The documentation uses `outputPath` but the instruction
JSON contract expects `resolvedOutputPath`; update the markdown to replace
`outputPath` with `resolvedOutputPath` everywhere in this command's docs and
examples so the artifact write-path matches the workflow contract, and verify
any surrounding references to `template`, `context`, `rules`, and `dependencies`
remain consistent with the contract.
In `@skills/openspec-apply-change/SKILL.md`:
- Around line 92-102: The unlabeled fenced code blocks in the SKILL.md example
sections (for example under the header "## Implementing: <change-name> (schema:
<schema-name>)" and the other examples at ranges noted) must be labeled with a
language to satisfy markdownlint MD040; update each triple-backtick block (e.g.,
the example blocks showing task progress "Working on task ...",
"[...implementation happening...]", "✓ Task complete") to use a plain text label
by changing ``` to ```text so they are explicitly marked as text.
In `@skills/openspec-archive-change/SKILL.md`:
- Around line 96-105: The fenced code block under the "## Archive Complete"
section in SKILL.md is missing a language tag (causing markdownlint MD040);
update the opening fence for that block (the triple backticks immediately before
"## Archive Complete") to include a language identifier such as text (e.g.,
change ``` to ```text) so the block becomes a plain-text fenced block and
satisfies MD040.
In `@skills/openspec-explore/SKILL.md`:
- Around line 54-69: The markdown contains unlabeled fenced code blocks (ASCII
diagrams) that trigger MD040; update each block (e.g., the ASCII diagram
starting with "┌─────────────────────────────────────────┐" and similar fenced
sections around lines 149-169, 172-200, 203-217, 220-247, 261-274) to use a
language label of text by changing ``` to ```text so linting no longer flags
them; apply this consistently to every unlabeled fenced example in SKILL.md.
In `@skills/openspec-propose/SKILL.md`:
- Around line 66-70: Update the instruction field name in the skill docs:
replace any occurrence of `outputPath` with `resolvedOutputPath` (e.g., the list
entry that currently reads "`outputPath`: Where to write the artifact") so the
docs match the real instructions payload; keep the explanatory text (e.g.,
"Where to write the artifact") and leave the rest of the items (`dependencies`,
`template`, `context`, `rules`) unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 39f4e108-4abd-4e1f-a4db-2aff4166571c
📒 Files selected for processing (9)
.claude-plugin/plugin.jsoncommands/opsx/apply.mdcommands/opsx/archive.mdcommands/opsx/explore.mdcommands/opsx/propose.mdskills/openspec-apply-change/SKILL.mdskills/openspec-archive-change/SKILL.mdskills/openspec-explore/SKILL.mdskills/openspec-propose/SKILL.md
| @@ -0,0 +1,11 @@ | |||
| { | |||
There was a problem hiding this comment.
Remove BOM from manifest to avoid parser failures.
Line 1 includes a UTF-8 BOM character before {, which can cause strict JSON consumers to fail loading the plugin manifest.
Suggested fix
-{
+{📝 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.
| { | |
| { |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude-plugin/plugin.json at line 1, The manifest JSON file contains a
leading UTF-8 BOM (U+FEFF) before the opening “{” which can break strict JSON
parsers; open the plugin manifest, remove the hidden BOM character at the very
start (or re-save the file as UTF-8 without BOM), and ensure the file now begins
directly with “{” so the JSON parses cleanly.
| - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` | ||
| - If `state: "all_done"`: congratulate, suggest archive |
There was a problem hiding this comment.
Replace /opsx:continue with an available command/flow.
This command isn’t part of the command set introduced in this PR, so the guidance can send users to a dead end.
Suggested fix
- - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+ - If `state: "blocked"` (missing artifacts): show message and suggest creating/completing required artifacts via `/opsx:propose` (or direct OpenSpec artifact workflow)📝 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.
| - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` | |
| - If `state: "all_done"`: congratulate, suggest archive | |
| - If `state: "blocked"` (missing artifacts): show message and suggest creating/completing required artifacts via `/opsx:propose` (or direct OpenSpec artifact workflow) | |
| - If `state: "all_done"`: congratulate, suggest archive |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/opsx/apply.md` around lines 44 - 45, In commands/opsx/apply.md
update the guidance for state: "blocked" to stop referencing the non-existent
`/opsx:continue` command; locate the "blocked" message branch and replace
`/opsx:continue` with an actual command/flow exposed by this PR (or, if no
direct resume command exists, point users to a valid alternative such as `/opsx
help` or the documented resume flow name used elsewhere in the codebase) and
update the message text to reflect that real command/flow.
| ``` | ||
| ## Implementing: <change-name> (schema: <schema-name>) | ||
|
|
||
| Working on task 3/7: <task description> | ||
| [...implementation happening...] | ||
| ✓ Task complete | ||
|
|
||
| Working on task 4/7: <task description> | ||
| [...implementation happening...] | ||
| ✓ Task complete | ||
| ``` |
There was a problem hiding this comment.
Add language specifiers to output example fences.
These unlabeled fenced blocks trigger MD040 markdownlint warnings.
Also applies to: 102-115, 119-135
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 88-88: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/opsx/apply.md` around lines 88 - 98, The unlabeled fenced code
blocks under the "Implementing: <change-name> (schema: <schema-name>)" example
(and the other example blocks later) are causing MD040 warnings; fix by adding a
language specifier to each triple-backtick fence (e.g., ```text or ```output or
```console) for the example output blocks, updating the fences shown in the
example snippet and the similar examples at the other occurrences so all fenced
blocks include an explicit language.
| ``` | ||
| ## Archive Complete | ||
|
|
||
| **Change:** <change-name> | ||
| **Schema:** <schema-name> | ||
| **Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/ | ||
| **Specs:** ✓ Synced to main specs | ||
|
|
||
| All artifacts complete. All tasks complete. | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced output blocks.
These unlabeled fences trigger MD040 and should be marked as text.
Also applies to: 105-114, 118-132, 136-148
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 92-92: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/opsx/archive.md` around lines 92 - 101, The fenced code blocks under
the "## Archive Complete" section (and the other similar blocks at the ranges
called out) are unlabeled and trigger MD040; add the language tag "text" to each
triple-backtick fence (e.g., change ``` to ```text) for the blocks containing
the Archive Complete content, the blocks at 105-114, 118-132, and 136-148 so the
markdown linter recognizes them as plain text.
| ``` | ||
| ┌─────────────────────────────────────────┐ | ||
| │ Use ASCII diagrams liberally │ | ||
| ├─────────────────────────────────────────┤ | ||
| │ │ | ||
| │ ┌────────┐ ┌────────┐ │ | ||
| │ │ State │────────▶│ State │ │ | ||
| │ │ A │ │ B │ │ | ||
| │ └────────┘ └────────┘ │ | ||
| │ │ | ||
| │ System diagrams, state machines, │ | ||
| │ data flows, architecture sketches, │ | ||
| │ dependency graphs, comparison tables │ | ||
| │ │ | ||
| └─────────────────────────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to fenced code block to satisfy markdown linting.
The unlabeled fence triggers MD040.
Suggested fix
-```
+```text
...
-```
+```📝 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.
| ``` | |
| ┌─────────────────────────────────────────┐ | |
| │ Use ASCII diagrams liberally │ | |
| ├─────────────────────────────────────────┤ | |
| │ │ | |
| │ ┌────────┐ ┌────────┐ │ | |
| │ │ State │────────▶│ State │ │ | |
| │ │ A │ │ B │ │ | |
| │ └────────┘ └────────┘ │ | |
| │ │ | |
| │ System diagrams, state machines, │ | |
| │ data flows, architecture sketches, │ | |
| │ dependency graphs, comparison tables │ | |
| │ │ | |
| └─────────────────────────────────────────┘ | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 57-57: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/opsx/explore.md` around lines 57 - 72, The fenced ASCII diagram
block is unlabeled and triggers MD040; update the opening fence from ``` to a
language tag such as ```text (or ```ascii) so the block becomes labeled and
lint-safe; locate the ASCII diagram fenced block in the explore.md content and
replace the unlabeled triple-backtick with a tagged fence.
| - `outputPath`: Where to write the artifact | ||
| - `dependencies`: Completed artifacts to read for context | ||
| - Read any completed dependency files for context | ||
| - Create the artifact file using `template` as the structure | ||
| - Apply `context` and `rules` as constraints - but do NOT copy them into the file |
There was a problem hiding this comment.
Use resolvedOutputPath instead of outputPath to match instruction JSON contract.
The documented field name is inconsistent with the workflow contract and can break artifact write-path resolution for this command.
Suggested fix
- - `outputPath`: Where to write the artifact
+ - `resolvedOutputPath`: Where to write the artifact📝 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.
| - `outputPath`: Where to write the artifact | |
| - `dependencies`: Completed artifacts to read for context | |
| - Read any completed dependency files for context | |
| - Create the artifact file using `template` as the structure | |
| - Apply `context` and `rules` as constraints - but do NOT copy them into the file | |
| - `resolvedOutputPath`: Where to write the artifact | |
| - `dependencies`: Completed artifacts to read for context | |
| - Read any completed dependency files for context | |
| - Create the artifact file using `template` as the structure | |
| - Apply `context` and `rules` as constraints - but do NOT copy them into the file |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/opsx/propose.md` around lines 62 - 66, The documentation uses
`outputPath` but the instruction JSON contract expects `resolvedOutputPath`;
update the markdown to replace `outputPath` with `resolvedOutputPath` everywhere
in this command's docs and examples so the artifact write-path matches the
workflow contract, and verify any surrounding references to `template`,
`context`, `rules`, and `dependencies` remain consistent with the contract.
| ``` | ||
| ## Implementing: <change-name> (schema: <schema-name>) | ||
|
|
||
| Working on task 3/7: <task description> | ||
| [...implementation happening...] | ||
| ✓ Task complete | ||
|
|
||
| Working on task 4/7: <task description> | ||
| [...implementation happening...] | ||
| ✓ Task complete | ||
| ``` |
There was a problem hiding this comment.
Label fenced output examples with text for markdownlint compliance.
These blocks are currently unlabeled and will be flagged by MD040.
Also applies to: 106-119, 123-139
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 92-92: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/openspec-apply-change/SKILL.md` around lines 92 - 102, The unlabeled
fenced code blocks in the SKILL.md example sections (for example under the
header "## Implementing: <change-name> (schema: <schema-name>)" and the other
examples at ranges noted) must be labeled with a language to satisfy
markdownlint MD040; update each triple-backtick block (e.g., the example blocks
showing task progress "Working on task ...", "[...implementation happening...]",
"✓ Task complete") to use a plain text label by changing ``` to ```text so they
are explicitly marked as text.
| ``` | ||
| ## Archive Complete | ||
|
|
||
| **Change:** <change-name> | ||
| **Schema:** <schema-name> | ||
| **Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/ | ||
| **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped") | ||
|
|
||
| All artifacts complete. All tasks complete. | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the success-output fenced block.
The fenced block starting at Line 96 is missing a language identifier, which triggers markdownlint MD040.
Use something like ```text for this example block.
Suggested diff
-```
+```text
## Archive Complete
...
All artifacts complete. All tasks complete.</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 96-96: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @skills/openspec-archive-change/SKILL.md around lines 96 - 105, The fenced
code block under the "## Archive Complete" section in SKILL.md is missing a
language tag (causing markdownlint MD040); update the opening fence for that
block (the triple backticks immediately before "## Archive Complete") to include
a language identifier such as text (e.g., change totext) so the block
becomes a plain-text fenced block and satisfies MD040.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| ┌─────────────────────────────────────────┐ | ||
| │ Use ASCII diagrams liberally │ | ||
| ├─────────────────────────────────────────┤ | ||
| │ │ | ||
| │ ┌────────┐ ┌────────┐ │ | ||
| │ │ State │────────▶│ State │ │ | ||
| │ │ A │ │ B │ │ | ||
| │ └────────┘ └────────┘ │ | ||
| │ │ | ||
| │ System diagrams, state machines, │ | ||
| │ data flows, architecture sketches, │ | ||
| │ dependency graphs, comparison tables │ | ||
| │ │ | ||
| └─────────────────────────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Label fenced examples with text to clear MD040 warnings.
These example/ASCII blocks are currently unlabeled and will be flagged by markdown lint.
Suggested fix pattern
-```
+```text
...
-```
+```Also applies to: 149-169, 172-200, 203-217, 220-247, 261-274
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/openspec-explore/SKILL.md` around lines 54 - 69, The markdown contains
unlabeled fenced code blocks (ASCII diagrams) that trigger MD040; update each
block (e.g., the ASCII diagram starting with
"┌─────────────────────────────────────────┐" and similar fenced sections around
lines 149-169, 172-200, 203-217, 220-247, 261-274) to use a language label of
text by changing ``` to ```text so linting no longer flags them; apply this
consistently to every unlabeled fenced example in SKILL.md.
| - `outputPath`: Where to write the artifact | ||
| - `dependencies`: Completed artifacts to read for context | ||
| - Read any completed dependency files for context | ||
| - Create the artifact file using `template` as the structure | ||
| - Apply `context` and `rules` as constraints - but do NOT copy them into the file |
There was a problem hiding this comment.
Fix instruction field name to resolvedOutputPath in skill docs.
Using outputPath here conflicts with the actual instructions payload and can misroute generated artifacts.
Suggested fix
- - `outputPath`: Where to write the artifact
+ - `resolvedOutputPath`: Where to write the artifact📝 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.
| - `outputPath`: Where to write the artifact | |
| - `dependencies`: Completed artifacts to read for context | |
| - Read any completed dependency files for context | |
| - Create the artifact file using `template` as the structure | |
| - Apply `context` and `rules` as constraints - but do NOT copy them into the file | |
| - `resolvedOutputPath`: Where to write the artifact | |
| - `dependencies`: Completed artifacts to read for context | |
| - Read any completed dependency files for context | |
| - Create the artifact file using `template` as the structure | |
| - Apply `context` and `rules` as constraints - but do NOT copy them into the file |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/openspec-propose/SKILL.md` around lines 66 - 70, Update the
instruction field name in the skill docs: replace any occurrence of `outputPath`
with `resolvedOutputPath` (e.g., the list entry that currently reads
"`outputPath`: Where to write the artifact") so the docs match the real
instructions payload; keep the explanatory text (e.g., "Where to write the
artifact") and leave the rest of the items (`dependencies`, `template`,
`context`, `rules`) unchanged.
1 participant
Summary
Add Claude Code plugin distribution files to enable direct installation via
/plugin install openspec@openspec.Changes
openspec-propose,openspec-explore,openspec-apply-change,openspec-archive-changeopsx/propose,opsx/apply,opsx/explore,opsx/archive.claude-plugin/plugin.jsonWhy
Currently the repo only has
AGENTS.mdat root. The installer'sverifyPluginrequires at least one ofskills/,commands/,agents/, or.claude-plugin/directories. This PR adds all three, resolving the[FAIL] openspec: ??????????error during plugin installation.Summary by CodeRabbit
New Features
Chores