feat: add Agent Skills for experimental artifact workflow #424
Conversation
Implements Task #3 from the experimental release plan: - Create skill templates for openspec-new-change and openspec-continue-change - Add artifact-experimental-setup CLI command - Generate Agent Skills in .claude/skills/ directory - Support cross-editor compatibility (Claude Code, Cursor, Windsurf) Skills follow the Agent Skills specification and provide: - Natural language invocation by AI assistants - Step-by-step artifact creation workflow - Dependency-driven change management
📝 WalkthroughWalkthroughAdds an OpenSpec experimental release plan document, two new agent-skill template generators, and a CLI scaffolding command that creates Changes
Sequence Diagram(s)(omitted — changes are template generation and local CLI scaffolding interacting with the filesystem; flow is simple and self-evident.) Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
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. |
![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
🧹 Nitpick comments (2)
docs/experimental-release-plan.md (2)
105-111: Minor documentation formatting improvements.Static analysis identified two minor formatting issues:
Line 113: "CLI Interface" is technically redundant (CLI already means "Command Line Interface"). Consider using just "CLI" or "Command Interface".
Line 105: The fenced code block is missing a language specifier. Add a language tag for better rendering.
🔎 Proposed fixes
**Skill Format:** Each skill is a directory with a `SKILL.md` file: -``` +```text .claude/skills/ ├── openspec-new-change/ │ └── SKILL.md # name, description, instructions └── openspec-continue-change/ └── SKILL.md # name, description, instructions-CLI Interface:
+CLI:openspec artifact-experimental-setupAlso applies to: 113-113
286-308: Add language specifier to dependency graph code block.The dependency graph code block (line 286) is missing a language specifier, as flagged by static analysis. Adding a language tag improves rendering and readability.
🔎 Proposed fix
## Dependency Graph -``` +```text 1. Remove WF skill files └── (no dependencies)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/experimental-release-plan.mdsrc/commands/artifact-workflow.tssrc/core/templates/skill-templates.ts
🧰 Additional context used
🧠 Learnings (4)
📓 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
📚 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:
docs/experimental-release-plan.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: 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:
docs/experimental-release-plan.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/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/experimental-release-plan.md
🧬 Code graph analysis (1)
src/commands/artifact-workflow.ts (2)
src/core/templates/skill-templates.ts (2)
getNewChangeSkillTemplate(21-81)getContinueChangeSkillTemplate(87-178)src/utils/file-system.ts (1)
FileSystemUtils(44-209)
🪛 LanguageTool
docs/experimental-release-plan.md
[style] ~113-~113: This phrase is redundant (‘I’ stands for ‘Interface’). Use simply “CLIInterface”.
Context: ... name, description, instructions **CLI Interface:**bash openspec artifact-experiment...
(ACRONYM_TAUTOLOGY)
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-release-plan.md
105-105: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
286-286: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
src/commands/artifact-workflow.ts (2)
458-525: LGTM! Idempotent skill generation implemented correctly.The implementation correctly:
- Uses
FileSystemUtils.writeFile()which creates directories as needed- Generates valid YAML frontmatter for Agent Skills specification
- Provides clear user feedback with created file paths and usage instructions
- Handles errors appropriately
The command is idempotent (will overwrite existing skills on re-run), which aligns with the PR objectives.
620-632: No action needed; no duplicate command registration exists.The codebase contains only a single registration of the
artifact-experimental-setupcommand at line 622 insrc/commands/artifact-workflow.ts. No duplicate registration was found elsewhere.Likely an incorrect or invalid review comment.
src/core/templates/skill-templates.ts (1)
99-99: Critical: Referenced commandopenspec listdoes not exist.Line 99 instructs agents to run
openspec list --jsonto get available changes, but this command is not implemented in the codebase. The skill will fail when invoked because the referenced command doesn't exist.Verify the missing command:
#!/bin/bash # Search for 'list' command registration in artifact-workflow.ts rg -n "\.command\('list'\)" --type ts # Search for listCommand function definition rg -n "function listCommand" --type ts # Check if there's any list-related command rg -n "list.*command" --type ts -i -g '!node_modules'🔎 Proposed fix
Option 1: Implement the missing
openspec listcommandAdd a new list command to
src/commands/artifact-workflow.tsafter the newChangeCommand function:// List Command interface ListOptions { json?: boolean; } async function listCommand(options: ListOptions): Promise<void> { const spinner = ora('Loading changes...').start(); try { const projectRoot = process.cwd(); const changesPath = path.join(projectRoot, 'openspec', 'changes'); const entries = await fs.promises.readdir(changesPath, { withFileTypes: true }); const changes = []; for (const entry of entries) { if (entry.isDirectory() && entry.name !== 'archive' && !entry.name.startsWith('.')) { const changePath = path.join(changesPath, entry.name); const stats = await fs.promises.stat(changePath); changes.push({ name: entry.name, lastModified: stats.mtime.toISOString(), }); } } // Sort by most recently modified changes.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime()); spinner.stop(); if (options.json) { console.log(JSON.stringify(changes, null, 2)); return; } if (changes.length === 0) { console.log('No changes found.'); return; } console.log('Available changes:'); for (const change of changes) { console.log(` ${change.name} (modified: ${change.lastModified})`); } } catch (error) { spinner.stop(); throw error; } }Then register the command in
registerArtifactWorkflowCommands:// List command program .command('list') .description('[Experimental] List all changes sorted by most recently modified') .option('--json', 'Output as JSON array') .action(async (options: ListOptions) => { try { await listCommand(options); } catch (error) { console.log(); ora().fail(`Error: ${(error as Error).message}`); process.exit(1); } });Option 2: Remove the list command reference from the skill template
If the list command is not needed, update line 99 to use a different approach for change selection, such as requiring the user to always specify the change name explicitly.
⛔ Skipped due to learnings
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 searchLearnt 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 changesLearnt 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 approvalLearnt 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
docs/experimental-release-plan.md
Outdated
| # Claude will automatically use the appropriate skill. | ||
| # | ||
| # 💡 This is an experimental feature. Feedback welcome at: | ||
| # https://github.com/your-org/openspec/issues |
There was a problem hiding this comment.
Update placeholder GitHub repository URL.
Line 136 uses a placeholder URL https://github.com/your-org/openspec/issues. This same placeholder appears in the implementation at line 519 of src/commands/artifact-workflow.ts. Update both locations to use the actual repository URL.
Verify the correct repository URL and update both locations:
#!/bin/bash
# Find the repository URL from package.json or git config
cat package.json | jq -r '.repository.url' 2>/dev/null || git config --get remote.origin.urlBased on the PR context showing "Fission-AI/OpenSpec", the URL should likely be:
https://github.com/Fission-AI/OpenSpec/issues
🤖 Prompt for AI Agents
In docs/experimental-release-plan.md around line 136 and
src/commands/artifact-workflow.ts around line 519, the placeholder GitHub issues
URL `https://github.com/your-org/openspec/issues` is used; replace it with the
correct repo issues URL (likely
`https://github.com/Fission-AI/OpenSpec/issues`), updating both locations
consistently, and verify the repository URL first by checking package.json
repository.url or git remote origin before committing the change.
| Use the **AskUserQuestion tool** (open-ended, no preset options) to ask: | ||
| > "What change do you want to work on? Describe what you want to build or fix." |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's see the file and its context
cat -n src/core/templates/skill-templates.ts | head -50Repository: Fission-AI/OpenSpec
Length of output: 2054
🌐 Web query:
Claude AskUserQuestion tool specification and documentation
💡 Result:
Short answer: AskUserQuestion is a Claude "tool" introduced as an interactive clarification UI that lets a Claude agent pause and ask the human a question (single- or multi-option or free-text) during agent workflows. Public official doc pages currently describe Claude tool use and how to declare tools but (as of the sources below) do not include a full AskUserQuestion reference; the most detailed public traces are a GitHub issue requesting official docs, community skill examples showing an input schema, and forum reports about runtime constraints (e.g., not usable inside stateless subagents). [1][2][3][4][5][6]
Key implementation notes gathered from public sources
- Purpose: prompt the human for clarifying input during agent/command execution. [1][2]
- Typical input schema (community examples / suggested doc): { "question": "string" } or a richer object with question text, header, options, multiSelect flags; output: { "answer": "string" } (or selected option(s)). This schema appears in community skill examples and an SDK-docs issue suggestion (not yet in official SDK reference). [1][5][6]
- Behavior/constraints reported by users: AskUserQuestion must be available to the running agent (not all subagent/task contexts); options are commonly limited (community posts mention ~4 options), and it may require enabling plan/skill mode in some workflows. These are community/issue reports, not formal spec text. [4][3]
- Where to look / how to use: use the standard tool-declaration mechanism (tools top-level parameter with name, description, input_schema) in Claude tool use API requests; then call AskUserQuestion per that tool’s input schema when the agent needs clarification. Official tool-use overview and implementation guides cover the general tool mechanism. [2][3]
Sources
- GitHub issue documenting missing AskUserQuestion docs and suggested input/output schema. [anthropics/claude-code issue]. [1]
- Claude docs — “How to implement tool use” (describes tools, input_schema, and declaring client tools). [2]
- Claude blog / announcement on tool use (product overview). [3]
- GitHub issue and community bug reports about AskUserQuestion behavior in skills / plan mode. [4]
- Community skill examples showing AskUserQuestion usage and richer schema (headers, options, multiSelect). [5]
- Community forum (Reddit) thread describing runtime constraint (AskUserQuestion not usable in stateless subagents) and practical limits. [6]
If you want, I can:
- fetch the exact schema examples from the most recent Claude Code repo/skill files and produce a ready-to-use AskUserQuestion tool-definition (TS/Python JSON Schema + example calls), or
- open/monitor the official docs pages and GitHub issues and return direct quoted snippets once the docs are published. Which would you prefer?
🌐 Web query:
Agent Skills specification tools list supported features
💡 Result:
Short list of "tools" features commonly supported by the Agent Skills (SKILL.md) ecosystem and by tools that implement the Agent Skills spec:
- Tool registration / discovery (register tools inside a skill and let agents discover them). [1][2]
- Declarative tool metadata (name, description, inputs/outputs, argument definitions, types). [1][3]
- Named arguments / typed parameters and validation (required vs optional, types, defaults). [2][3]
- Command / executable invocation (shell/CLI command or function invocation). [2][3]
- HTTP endpoints / REST handlers exposed by a skill. [4]
- Hooks / lifecycle callbacks around tool calls (before_toolcall, on_message, after_toolcall). [4]
- Tool sandboxing / execution environment hints (local, sandbox, container, secure enclave). [3][1]
- Authentication & secrets handling for tool access (credentials, tokens) and scopes. [1][3]
- Tool result formatting (structured outputs, status codes, stderr/stdout capture). [2][3]
- Handoffs / routing (route work to other agents or skills). [4][1]
- Multi-file resources and dependencies (declare scripts, docs, resource files, dependencies). [1][3]
- Versioning / compatibility metadata and skill dependency declarations. [1][3]
- Tool discovery priority / multi-source resolution (project, registry, plugins, directories). [3]
- Validation tooling / CLI (skill validators, spec linters, CI checks). [1][3]
- Interop / reuse across agent products (single skill usable by VS Code, Copilot, Cursor, etc.). [1][5]
Sources: Agent Skills specification & ecosystem docs, VS Code Agent Skills integration, skillkit implementation notes, WebAgents/skill frameworks. [1][2][3][4][5]
Sources:
[1] agentskills.io (Agent Skills overview).
[2] VS Code — Use Agent Skills in VS Code (SKILL.md structure, locations).
[3] skillkit / PyPI (skill implementation features: metadata, discovery, model-agnostic).
[4] WebAgents / Skills docs (tools, hooks, HTTP endpoints, handoffs).
[5] Ecosystem adoption lists (tools supporting Agent Skills).
Replace AskUserQuestion with a cross-editor compatible solution.
The "AskUserQuestion tool" is Claude-specific and undocumented in official Claude documentation. It is not part of the Agent Skills specification and is reported to have runtime constraints (e.g., unavailable in stateless subagents). Since the PR explicitly targets Claude Code, Cursor, Windsurf, and other Agent Skills-compatible editors, using this tool breaks cross-editor compatibility. Either use a documented cross-editor approach (e.g., standard CLI input flow or documented Agent Skills mechanisms) or clearly document this as Claude-only with appropriate fallback instructions for other editors.
🤖 Prompt for AI Agents
In src/core/templates/skill-templates.ts around lines 33–34, the template uses
the Claude-only AskUserQuestion tool which breaks cross-editor compatibility;
replace it with a documented, cross-editor approach: remove AskUserQuestion
usage and instead implement an open-ended prompt using a standard Agent
Skills-compatible input pattern (e.g., a generic "prompt user"/GetUserInput
mechanism or a simple CLI/stdin fallback) and add a short fallback: if the
runtime/editor does not provide a documented prompt API, fall back to
synchronous stdin or throw a clear "interactive input required" error with
instructions; update the template text to a neutral prompt string ("What change
do you want to work on? Describe what you want to build or fix.") and document
in comments that Claude-only tools must not be used and specify the fallback
behavior.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
src/commands/artifact-workflow.ts (1)
537-543: Consider quoting the YAML description field for safety.The
descriptionfield is inserted directly into YAML frontmatter without quoting. If a future template description contains YAML special characters (:,#,",',[,{, etc.), it could break parsing.🔎 Proposed fix to quote the description
// Generate SKILL.md content with YAML frontmatter const skillContent = `--- name: ${template.name} -description: ${template.description} +description: "${template.description.replace(/"/g, '\\"')}" --- ${template.instructions} `;
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/commands/artifact-workflow.ts
🧰 Additional context used
🧠 Learnings (1)
📓 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: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
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.
🧬 Code graph analysis (1)
src/commands/artifact-workflow.ts (1)
src/core/templates/skill-templates.ts (2)
getNewChangeSkillTemplate(21-81)getContinueChangeSkillTemplate(87-178)
🔇 Additional comments (3)
src/commands/artifact-workflow.ts (3)
29-30: LGTM!The new imports are correctly added and both are utilized in the
artifactExperimentalSetupCommandfunction. The import paths follow the existing ES module convention used throughout the file.
574-574: Verify the feedback URL matches the correct repository.The URL references
github.com/anthropics/openspecbut this PR is inFission-AI/OpenSpec. Confirm this is the intended canonical location for feedback, or update to match the actual repository.
674-687: LGTM!The command registration follows the established pattern used by other commands in this file. Error handling is consistent with the rest of the codebase.
Note: The AI summary mentioned "duplicated CLI registration" but only one registration of
artifact-experimental-setupexists in the provided code. This appears to be an inconsistency in the summary.
Replace placeholder `https://github.com/your-org/openspec/issues` with correct URL `https://github.com/Fission-AI/OpenSpec/issues` in: - docs/experimental-release-plan.md - src/commands/artifact-workflow.ts Verified against package.json repository.url field.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/experimental-release-plan.md (1)
1-381: Comprehensive and well-structured release plan.The document provides:
- Clear differentiation between the three workflow modes
- Detailed work items with task checklists
- E2E testing scenarios with validation checklist
- Dependency graph for work item ordering
- Explicit out-of-scope items to prevent scope creep
- Measurable success criteria
The GitHub issues URL at line 136 now correctly points to
https://github.com/Fission-AI/OpenSpec/issues.
🧹 Nitpick comments (3)
src/commands/artifact-workflow.ts (1)
537-543: Quote YAML string values for robustness.The description field is interpolated directly without quotes. While current descriptions work, YAML can break if future descriptions contain colons followed by spaces (e.g.,
"Note: this is important"), leading colons, or other special characters.🔎 Proposed fix using YAML single-quoted strings
const skillContent = `--- name: ${template.name} -description: ${template.description} +description: '${template.description.replace(/'/g, "''")}' --- ${template.instructions} `;Alternatively, consider using a YAML library like
yamlorjs-yamlto serialize the frontmatter safely.docs/experimental-release-plan.md (2)
103-111: Add language specifier to code blocks.Per markdownlint (MD040), fenced code blocks should specify a language. For directory structure diagrams,
textorplaintextis conventional.🔎 Proposed fix
**Skill Format:** Each skill is a directory with a `SKILL.md` file: -``` +```text .claude/skills/ ├── openspec-new-change/ │ └── SKILL.md # name, description, instructions └── openspec-continue-change/ └── SKILL.md # name, description, instructions</details> --- `284-308`: **Add language specifier to dependency graph code block.** Same as above—`text` or `plaintext` is appropriate for ASCII diagrams. <details> <summary>🔎 Proposed fix</summary> ```diff ## Dependency Graph -``` +```text 1. Remove WF skill files └── (no dependencies)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/experimental-release-plan.mdsrc/commands/artifact-workflow.ts
🧰 Additional context used
🧠 Learnings (3)
📓 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: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
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.
📚 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:
docs/experimental-release-plan.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: 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:
docs/experimental-release-plan.md
🧬 Code graph analysis (1)
src/commands/artifact-workflow.ts (2)
src/core/templates/skill-templates.ts (2)
getNewChangeSkillTemplate(21-81)getContinueChangeSkillTemplate(87-178)src/utils/file-system.ts (1)
FileSystemUtils(44-209)
🪛 LanguageTool
docs/experimental-release-plan.md
[style] ~113-~113: This phrase is redundant (‘I’ stands for ‘Interface’). Use simply “CLIInterface”.
Context: ... name, description, instructions **CLI Interface:**bash openspec artifact-experiment...
(ACRONYM_TAUTOLOGY)
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-release-plan.md
105-105: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
286-286: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
src/commands/artifact-workflow.ts (3)
29-30: LGTM!The new imports for skill template generators and
FileSystemUtilsare properly structured and align with the implementation below.
513-580: Well-structured implementation.The function correctly:
- Uses
FileSystemUtils.writeFilewhich auto-creates parent directories- Is idempotent (safe to run multiple times)
- Provides clear, actionable output for multiple editor environments
- Follows the error handling pattern established by other commands
674-687: Command registration looks correct.The registration follows the established pattern for other commands in this file. The error handling is consistent with sibling commands.
Note: The AI summary mentioned duplicate registration, but only one registration is present in this code segment.
Changes SummaryThis PR implements Task #3 of the experimental release plan by adding Agent Skills support for the experimental artifact workflow. It introduces a new Type: feature Components Affected: CLI commands, Agent Skills generation, Template system, Experimental workflow documentation Files Changed
Architecture Impact
Risk Areas: YAML frontmatter generation - description field is not quoted, will break YAML parsing if description contains special characters or spans multiple lines, Command idempotency - running the command multiple times may not be truly idempotent if files already exist (depends on FileSystemUtils.writeFile() behavior), Path construction - uses process.cwd() which may not always be the correct project root in all contexts, No input validation - command accepts no arguments and doesn't validate that it's being run in a valid OpenSpec project Suggestions
Full review in progress... | Powered by diffray |
| openspec artifact-experimental-setup | ||
|
|
||
| # Output: | ||
| # 🧪 Experimental Artifact Workflow Setup |
There was a problem hiding this comment.
🟠 HIGH - Incorrect CLI output title in documentation
Agent: documentation
Category: docs
Description:
Documentation claims CLI output title is '🧪 Experimental Artifact Workflow Setup' but code outputs '🧪 Experimental Artifact Workflow Skills Created'
Suggestion:
Update line 118 to match actual code output: '# 🧪 Experimental Artifact Workflow Skills Created'
Why this matters: Broken links frustrate users and hurt credibility.
Confidence: 95%
Rule: docs_broken_links
Review ID: 44d9f78e-5d13-4ad6-bb8f-c081c005ced0
Rate it 👍 or 👎 to improve future reviews | Powered by diffray
| # Created .claude/skills/openspec-new-change/SKILL.md | ||
| # Created .claude/skills/openspec-continue-change/SKILL.md |
There was a problem hiding this comment.
🟠 HIGH - Incorrect CLI output format for created files
Agent: documentation
Category: docs
Description:
Documentation shows 'Created .claude/skills/...' but actual code outputs files with checkmark prefix '✓ .claude/skills/...'
Suggestion:
Update lines 120-121 to show: '✓ .claude/skills/openspec-new-change/SKILL.md' and '✓ .claude/skills/openspec-continue-change/SKILL.md'
Why this matters: Broken links frustrate users and hurt credibility.
Confidence: 95%
Rule: docs_broken_links
Review ID: 44d9f78e-5d13-4ad6-bb8f-c081c005ced0
Rate it 👍 or 👎 to improve future reviews | Powered by diffray
| # ✅ Skills are now available in: | ||
| # - Claude Code (auto-detected) | ||
| # - Cursor (enable in Settings → Rules → Import Settings) | ||
| # - Windsurf (auto-imported from .claude directory) |
There was a problem hiding this comment.
🟠 HIGH - Documentation shows non-existent output section
Agent: documentation
Category: docs
Description:
Documentation shows section '✅ Skills are now available in:' with editor list, but this section does not exist in actual code output. Code includes editors inside Usage section instead.
Suggestion:
Remove lines 123-126 entirely. The actual code output proceeds directly to '📖 Usage:' section after listing created files, with editors listed inside the Usage section.
Why this matters: Broken links frustrate users and hurt credibility.
Confidence: 95%
Rule: docs_broken_links
Review ID: 44d9f78e-5d13-4ad6-bb8f-c081c005ced0
Rate it 👍 or 👎 to improve future reviews | Powered by diffray
| # - Cursor (enable in Settings → Rules → Import Settings) | ||
| # - Windsurf (auto-imported from .claude directory) | ||
| # | ||
| # 📖 To use: |
There was a problem hiding this comment.
🟡 MEDIUM - Incorrect CLI output section heading
Agent: documentation
Category: docs
Description:
Documentation shows '# 📖 To use:' but actual code outputs '📖 Usage:'
Suggestion:
Update line 128 from '# 📖 To use:' to '# 📖 Usage:'
Why this matters: Broken links frustrate users and hurt credibility.
Confidence: 90%
Rule: docs_broken_links
Review ID: 44d9f78e-5d13-4ad6-bb8f-c081c005ced0
Rate it 👍 or 👎 to improve future reviews | Powered by diffray
| # 📖 To use: | ||
| # Ask Claude naturally: | ||
| # • "I want to start a new OpenSpec change to add <feature>" | ||
| # • "Continue working on this change" | ||
| # | ||
| # Claude will automatically use the appropriate skill. |
There was a problem hiding this comment.
🟠 HIGH - Incorrect documentation of CLI output structure
Agent: documentation
Category: docs
Description:
Documentation structure does not match actual code output. Code shows: (1) '📖 Usage:' heading, (2) 'Skills work automatically in compatible editors:' with 3 editors, (3) 'Ask Claude naturally:' with examples. Doc shows different organization.
Suggestion:
Restructure lines 128-133 to match actual code output: Show '📖 Usage:' section, then 'Skills work automatically in compatible editors:' subsection with three editors, then 'Ask Claude naturally:' subsection with usage examples
Why this matters: Broken links frustrate users and hurt credibility.
Confidence: 88%
Rule: docs_broken_links
Review ID: 44d9f78e-5d13-4ad6-bb8f-c081c005ced0
Rate it 👍 or 👎 to improve future reviews | Powered by diffray
Review Summary
Validated 5 issues: 5 kept (all verified documentation-code mismatches that could confuse users) Issues Found: 5💬 See 5 individual line comment(s) for details. 📊 1 unique issue type(s) across 5 location(s) 📋 Full issue list (click to expand)🟠 HIGH - Incorrect CLI output title in documentation (5 occurrences)Agent: documentation Category: docs Why this matters: Broken links frustrate users and hurt credibility. 📍 View all locations
Rule: Review ID: |
Summary
Implements Task #3: Add Agent Skills for Experimental Workflow from the experimental release plan.
This PR adds Agent Skills support for the experimental artifact workflow, enabling cross-editor compatibility with Claude Code, Cursor, Windsurf, and other Agent Skills-compatible editors.
Changes
New Files
src/core/templates/skill-templates.ts- Skill template definitionsgetNewChangeSkillTemplate()- Start a new changegetContinueChangeSkillTemplate()- Continue working on a changedocs/experimental-release-plan.md- Complete experimental release plan documentationModified Files
src/commands/artifact-workflow.tsartifactExperimentalSetupCommand()functionartifact-experimental-setupCLI commandFeatures
Command:
openspec artifact-experimental-setupCreates Agent Skills in
.claude/skills/directory:openspec-new-change/SKILL.md- Start new changes with artifact workflowopenspec-continue-change/SKILL.md- Continue working on changesAgent Skills Format
Each skill follows the Agent Skills specification:
Cross-Editor Support
✅ Claude Code - Auto-detected, ready to use
✅ Cursor - Enable via Settings → Rules → Import Settings
✅ Windsurf - Auto-imports from
.claudedirectory✅ Other editors - Any Agent Skills-compatible editor
Usage
Claude will automatically invoke the appropriate skill based on the user's request.
Implementation Details
FileSystemUtils.writeFile()/openspec:*or/opsx:*commands)Testing
✅ Command builds successfully
✅ Skills generated in correct directory structure
✅ SKILL.md files contain valid YAML frontmatter
✅ Command is idempotent
✅ Help text shows command correctly
Next Steps
Per the experimental release plan:
Checklist
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
Summary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.