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 experimental opsx release plan and agent skill templates, implements a new "apply" instructions flow (task parsing, generation, JSON/text output), scaffolds Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Developer
participant CLI as CLI
participant Templates as Skill Templates
participant FS as File System
participant Repo as Repo Inspector
participant Printer as Output
Developer->>CLI: run `artifact-experimental-setup`
CLI->>Templates: request new/continue/apply templates
Templates-->>CLI: SkillTemplate objects
CLI->>FS: create `.claude/skills` and write SKILL.md files
FS-->>CLI: success / error
CLI->>Printer: show usage guide
Printer-->>Developer: human-readable message
alt apply instructions flow
Developer->>CLI: run `instructions --artifact=apply --change <id>`
CLI->>Repo: inspect change artifacts, read tasks.md, gather context files
Repo-->>CLI: artifact metadata, tasks, context
CLI->>Printer: render apply instructions (text / JSON)
Printer-->>Developer: apply instructions
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 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 |
docs/experimental-release-plan.md
Outdated
| 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
docs/experimental-release-plan.md
Outdated
| # 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
docs/experimental-release-plan.md
Outdated
| # ✅ 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
docs/experimental-release-plan.md
Outdated
| # - 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
docs/experimental-release-plan.md
Outdated
| # 📖 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: |
Add the apply skill to guide agents through implementing tasks from an OpenSpec change: - Add `openspec instructions apply` CLI command that parses tasks.md and returns context files, progress tracking, and dynamic instructions - Add `getApplyChangeSkillTemplate()` to skill-templates.ts with full workflow guidance for implementing tasks - Update artifact-experimental-setup to generate all three skills: openspec-new-change, openspec-continue-change, openspec-apply-change The apply skill supports the fluid "actions on a change" model: - Can be invoked anytime (if tasks.md exists) - Handles blocked/ready/all_done states - Guides agents to pause on issues and suggest artifact updates - Tracks progress via task checkboxes
There was a problem hiding this comment.
Actionable comments posted: 1
Fix all issues with AI Agents 🤖
In @src/commands/artifact-workflow.ts:
- Around line 762-768: The YAML frontmatter being built in the skillContent
template literal uses template.description unquoted, which can break YAML when
description contains colons or quotes; update the skillContent construction to
wrap the description in quotes and escape any existing quotes (e.g., replace "
with \" or use JSON.stringify-like escaping) before injecting it, keeping
template.name and template.instructions unchanged so the description is safely
quoted in the resulting YAML.
🧹 Nitpick comments (1)
src/commands/artifact-workflow.ts (1)
489-492: Consider using FileSystemUtils for consistency.The code directly uses
fs.existsSyncandfs.promises.readFileinstead of the utility methodsFileSystemUtils.fileExistsandFileSystemUtils.readFile. While functionally equivalent, using the utility methods would provide consistency with the rest of the codebase and centralize filesystem operations.🔎 Proposed refactor to use FileSystemUtils
- const hasProposal = fs.existsSync(proposalPath); - const hasDesign = fs.existsSync(designPath); - const hasTasks = fs.existsSync(tasksPath); - const hasSpecs = fs.existsSync(specsPath); + const hasProposal = await FileSystemUtils.fileExists(proposalPath); + const hasDesign = await FileSystemUtils.fileExists(designPath); + const hasTasks = await FileSystemUtils.fileExists(tasksPath); + const hasSpecs = await FileSystemUtils.fileExists(specsPath);if (hasTasks) { - const tasksContent = await fs.promises.readFile(tasksPath, 'utf-8'); + const tasksContent = await FileSystemUtils.readFile(tasksPath); tasks = parseTasksFile(tasksContent); }Also applies to: 515-516
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/commands/artifact-workflow.tssrc/core/templates/skill-templates.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- src/core/templates/skill-templates.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: 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.
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: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:
src/commands/artifact-workflow.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
src/commands/artifact-workflow.ts
🧬 Code graph analysis (1)
src/commands/artifact-workflow.ts (3)
src/core/artifact-graph/instruction-loader.ts (1)
loadChangeContext(150-167)src/core/templates/skill-templates.ts (3)
getNewChangeSkillTemplate(21-81)getContinueChangeSkillTemplate(87-178)getApplyChangeSkillTemplate(184-323)src/utils/file-system.ts (1)
FileSystemUtils(44-209)
🔇 Additional comments (6)
src/commands/artifact-workflow.ts (6)
36-60: LGTM! Well-structured type definitions.The interface definitions for the Apply Instructions feature are clear and comprehensive. The state union type appropriately captures the three possible states of a change.
449-470: LGTM! Clean checkbox parsing implementation.The regex pattern correctly handles both
-and*bullet points with case-insensitive checkbox detection. The implementation is straightforward and appropriate for parsing markdown task lists.
554-627: LGTM! Well-structured command implementation.The apply instructions command follows the established patterns in the file with proper error handling, spinner management, and clear output formatting. The conditional formatting for different states (blocked, all_done, ready) provides helpful user feedback.
775-800: Excellent user experience with comprehensive setup guidance.The success message provides clear, actionable information about how to use the generated skills across different editors. The natural language examples and editor-specific instructions make this feature accessible to users.
852-870: LGTM! Clean special case handling for apply instructions.The routing logic appropriately handles the special case where
artifactId === 'apply'to invoke the apply instructions flow. The updated description accurately reflects the extended functionality of the instructions command.
906-917: LGTM! Proper command registration.The artifact-experimental-setup command registration follows the established pattern with appropriate error handling and experimental labeling.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/experimental-release-plan.md (1)
113-137: Fix documented CLI output to match actual implementation.The documented output has 5 distinct mismatches with the actual code:
- Line 118 - Title is "🧪 Experimental Artifact Workflow Setup" but should be "🧪 Experimental Artifact Workflow Skills Created"
- Lines 120–121 - File output shows "Created .claude/skills/..." but should show "✓ .claude/skills/..."
- Lines 123–126 - Remove the "✅ Skills are now available in:" section entirely; it does not exist in actual output
- Line 128 - Heading should be "📖 Usage:" not "📖 To use:"
- Lines 128–133 - Restructure to match actual order: Usage heading → "Skills work automatically in compatible editors:" subsection → editor list → "Ask Claude naturally:" section
🔎 Proposed fix for CLI output documentation
# Output: -# 🧪 Experimental Artifact Workflow Setup +# 🧪 Experimental Artifact Workflow Skills Created # -# Created .claude/skills/openspec-new-change/SKILL.md -# Created .claude/skills/openspec-continue-change/SKILL.md +# ✓ .claude/skills/openspec-new-change/SKILL.md +# ✓ .claude/skills/openspec-continue-change/SKILL.md # -# ✅ Skills are now available in: -# - Claude Code (auto-detected) -# - Cursor (enable in Settings → Rules → Import Settings) -# - Windsurf (auto-imported from .claude directory) -# -# 📖 To use: +# 📖 Usage: +# +# Skills work automatically in compatible editors: +# - Claude Code (auto-detected, ready to use) +# - Cursor (enable in Settings → Rules → Import Settings) +# - Windsurf (auto-imports from .claude directory) +# # Ask Claude naturally: # • "I want to start a new OpenSpec change to add <feature>" # • "Continue working on this change"
🧹 Nitpick comments (2)
docs/experimental-release-plan.md (2)
105-111: Add language specifications to code fence blocks.Multiple code fence blocks lack language identifiers, reducing syntax highlighting and clarity. Add language tags (e.g.,
```bash,```markdown,```yaml).Examples:
- Lines 105–111: Directory structure (use
```txtor```yaml)- Line 286: Dependency graph (use
```mermaidor```txt)- Line 380: Output example (use
```txt)- Lines 737, 755, 774, 793, 831: All output examples (use
```txt)Also applies to: 286-292, 380-384, 737-737, 755-756, 774-774, 793-793, 831-831
446-446: Use hyphens for compound adjectives.Lines 446 reference "tic tac toe" and "single player" which should be hyphenated when used as compound adjectives: "tic-tac-toe" and "single-player".
🔎 Proposed fix
- - This felt overly cautious when user had already provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthetics") + - This felt overly cautious when user had already provided enough context (e.g., "tic-tac-toe, single-player vs AI, minimal aesthetics")
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/experimental-release-plan.md
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
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
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
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/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/experimental-release-plan.md
🪛 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)
[uncategorized] ~401-~401: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...onfusion 1. Redundant CLI calls status AND `ne...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[grammar] ~446-~446: Use a hyphen to join words.
Context: ...eady provided enough context (e.g., "tic tac toe, single player vs AI, minimal ae...
(QB_NEW_EN_HYPHEN)
[grammar] ~446-~446: Use a hyphen to join words.
Context: ... provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthe...
(QB_NEW_EN_HYPHEN)
[grammar] ~578-~578: Ensure spelling is correct
Context: ...) vs create + instructions + Read + Edit×N (4+) - Scaffolding doesn't solve the re...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~663-~663: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...mplete and user wants to proceed - User wants to continue implementation after a break ...
(REP_WANT_TO_VB)
🪛 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)
380-380: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
595-595: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
690-690: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
691-691: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
692-692: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
693-693: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
696-696: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
697-697: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
698-698: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
737-737: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
755-755: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
774-774: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
793-793: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
831-831: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
docs/experimental-release-plan.md (1)
136-136: This issue has already been resolved. Bothdocs/experimental-release-plan.md(line 136) andsrc/commands/artifact-workflow.tsalready contain the correct repository URLhttps://github.com/Fission-AI/OpenSpec/issues. No placeholder URLs exist in the codebase.Likely an incorrect or invalid review comment.
Enrich the proposal template to explicitly capture capability discovery: - Add "Capabilities" section with "New Capabilities" and "Modified Capabilities" subsections to proposal template - Update proposal instruction in schema.yaml to guide agents on researching existing specs and listing capabilities - Update skill instructions with detailed guidance for the Capabilities section This creates a clear contract between proposal and specs phases - each capability listed in the proposal will need a corresponding spec file.
The `next` command was redundant with `status` - both show which artifacts are ready to create. The status command provides more context (done/ready/blocked) and is the single source of truth for artifact state. Changes: - Remove nextCommand function and CLI registration from artifact-workflow.ts - Update skill templates to use status instead of next - Update docs and specs to reflect removal - Add REMOVED Requirements section to cli-artifact-workflow spec - Remove 7 tests for the next command Migration: Use `openspec status --change <id> --json` and filter artifacts with `status: "ready"` to find artifacts that can be created next.
There was a problem hiding this comment.
Actionable comments posted: 1
Fix all issues with AI Agents 🤖
In @schemas/spec-driven/templates/proposal.md:
- Line 13: The proposal.md template's HTML comment for capabilities is not
explicit about required kebab-case naming; update the comment (the HTML comment
that begins "Capabilities being introduced (will create new
specs/<name>/spec.md)") to explicitly instruct replacing <name> with kebab-case
and include examples (e.g., user-auth, data-export) so developers see the naming
convention inline with the template.
🧹 Nitpick comments (1)
docs/experimental-release-plan.md (1)
105-111: Consider adding language specifiers to fenced code blocks.Multiple fenced code blocks throughout the document are missing language specifiers. Adding them improves syntax highlighting and readability.
Examples:
- Line 105: Could be
textorplaintextfor directory structure- Line 286: Could be
textfor dependency graph- Line 380, 737, 755, 774, 793, 831: Could be
textorplaintextfor output examplesExample fix for line 105
-``` +```text .claude/skills/ ├── openspec-new-change/ │ └── SKILL.md # name, description, instructions └── openspec-continue-change/ └── SKILL.md # name, description, instructions</details> Also applies to: 286-307, 380-383, 737-794, 831-831 </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 5b22ee58115e6e5f6abf5299a55b4332938e6f5c and 9f58815e06aaa8b9d5af2d6f77a811ec82091ba8. </details> <details> <summary>📒 Files selected for processing (4)</summary> * `docs/experimental-release-plan.md` * `schemas/spec-driven/schema.yaml` * `schemas/spec-driven/templates/proposal.md` * `src/core/templates/skill-templates.ts` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * src/core/templates/skill-templates.ts </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (10)</summary> <details> <summary>📓 Common learnings</summary>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.mdto learn how to create and apply change proposals, spec format and conventions, and project structure and guidelinesLearnt 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.mdwhen 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 codingLearnt 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 usingproposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensureproposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)</details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensureproposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)**Applied to files:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` - `docs/experimental-release-plan.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements**Applied to files:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:02.839Z</summary>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.mdto learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines**Applied to files:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` - `docs/experimental-release-plan.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>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 usingproposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/**Applied to files:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` - `docs/experimental-release-plan.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files**Applied to files:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:02.839Z</summary>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.mdwhen 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:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` - `docs/experimental-release-plan.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Createdesign.mdonly when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity**Applied to files:** - `schemas/spec-driven/templates/proposal.md` - `schemas/spec-driven/schema.yaml` - `docs/experimental-release-plan.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Checkopenspec/project.mdfor project conventions before creating specs**Applied to files:** - `schemas/spec-driven/schema.yaml` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensuretasks.mdcontains implementation checklist with numbered sections and checkbox items**Applied to files:** - `docs/experimental-release-plan.md` </details> </details><details> <summary>🪛 LanguageTool</summary> <details> <summary>docs/experimental-release-plan.md</summary> [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) --- [uncategorized] ~401-~401: If this is a compound adjective that modifies the following noun, use a hyphen. Context: ...onfusion 1. **Redundant CLI calls** ⚠️ MEDIUM PRIORITY - Users called both `status` AND `ne... (EN_COMPOUND_ADJECTIVE_INTERNAL) --- [grammar] ~446-~446: Use a hyphen to join words. Context: ...eady provided enough context (e.g., "tic tac toe, single player vs AI, minimal ae... (QB_NEW_EN_HYPHEN) --- [grammar] ~446-~446: Use a hyphen to join words. Context: ... provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthe... (QB_NEW_EN_HYPHEN) --- [grammar] ~578-~578: Ensure spelling is correct Context: ...) vs `create` + `instructions` + Read + Edit×N (4+) - Scaffolding doesn't solve the re... (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) --- [style] ~663-~663: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing. Context: ...mplete and user wants to proceed - User wants to continue implementation after a break ... (REP_WANT_TO_VB) </details> </details> <details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>docs/experimental-release-plan.md</summary> 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) --- 380-380: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 595-595: Emphasis used instead of a heading (MD036, no-emphasis-as-heading) --- 690-690: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 691-691: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 692-692: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 693-693: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 696-696: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 697-697: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 698-698: Unordered list indentation Expected: 0; Actual: 3 (MD007, ul-indent) --- 737-737: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 755-755: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 774-774: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 793-793: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 831-831: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (2)</summary><blockquote> <details> <summary>schemas/spec-driven/templates/proposal.md (1)</summary><blockquote> `9-17`: **Excellent addition: Capabilities section addresses a key workflow gap.** The new Capabilities section directly addresses the "specs directory ambiguity" issue documented in the experimental release plan. By requiring upfront capability identification, agents will know exactly which spec files to create (`specs/<name>/spec.md`) rather than having to guess paths during the specs phase. The separation of New vs Modified capabilities creates a clear contract for the downstream specs artifact, aligning well with the design decisions in the experimental plan. </blockquote></details> <details> <summary>schemas/spec-driven/schema.yaml (1)</summary><blockquote> `15-22`: **LGTM: Clear and actionable Capabilities guidance.** The updated proposal instructions make the Capabilities section explicit and actionable. The guidance to research existing specs, use kebab-case naming, and distinguish New vs Modified capabilities upfront addresses the workflow friction documented in the experimental plan's E2E testing feedback. The emphasis block appropriately highlights the critical nature of this section as it "creates the contract between proposal and specs phases." </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Update HTML comments in the Capabilities section to explicitly instruct using kebab-case identifiers with examples (user-auth, data-export, api-rate-limiting).
Add two related change proposals for enabling schema selection in the experimental artifact workflow: 1. add-per-change-schema-metadata: Store schema choice in .openspec.yaml per change, enabling auto-detection in workflow commands. Includes Zod schema design and delta specs for cli-artifact-workflow. 2. add-agent-schema-selection: Follow-up to update agent skills to support dynamic schema selection (depends on metadata change). Also includes: - Example .openspec.yaml in add-frontmatter-to-openspec-artifact-files - Clarify "Modified Capabilities" guidance in proposal template
There was a problem hiding this comment.
Actionable comments posted: 2
Fix all issues with AI Agents 🤖
In @docs/experimental-release-plan.md:
- Around line 117-137: Update the CLI output example for the artifact-workflow
command to match the actual implementation: change the top heading from "Setup"
to "Skills Created", add the "✓ " prefix before the two SKILL.md file paths,
remove the entire "Skills are now available in:" section, rename the "To use:"
heading to "Usage:", and reorder the usage content so the "Skills work
automatically in compatible editors:" subsection appears before the example
prompts and matches the real output structure.
In @src/commands/artifact-workflow.ts:
- Around line 444-450: The code is incorrectly treating design.md as required by
pushing 'design' into missingArtifacts when hasDesign is false; remove the
hasDesign check so missingArtifacts only requires 'proposal' and 'specs' (i.e.,
stop pushing 'design'), leaving the fallback that if missingArtifacts is empty
it pushes 'tasks'; do not change the existing logic that still adds design to
contextFiles when present (so design is optional but included when available).
🧹 Nitpick comments (1)
openspec/specs/cli-artifact-workflow/spec.md (1)
162-168: Consider adding a scenario for the REMOVED requirement.Per the coding guidelines, specs should include at least one
#### Scenario:per requirement. While the deprecation reason and migration guidance are clear, adding a scenario (e.g., "#### Scenario: Migrating to Status Command") would provide a concrete example of the new workflow replacing the removed Next Command, aligning with spec conventions.Please verify whether scenarios are required for REMOVED Requirements by checking
@/openspec/AGENTS.mdspecifications.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
docs/experimental-release-plan.mddocs/schema-workflow-gaps.mdopenspec/changes/add-agent-schema-selection/proposal.mdopenspec/changes/add-agent-schema-selection/tasks.mdopenspec/changes/add-per-change-schema-metadata/design.mdopenspec/changes/add-per-change-schema-metadata/proposal.mdopenspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/tasks.mdopenspec/specs/cli-artifact-workflow/spec.mdschemas/spec-driven/schema.yamlschemas/spec-driven/templates/proposal.mdsrc/commands/artifact-workflow.tssrc/core/templates/skill-templates.tstest/commands/artifact-workflow.test.ts
💤 Files with no reviewable changes (1)
- test/commands/artifact-workflow.test.ts
✅ Files skipped from review due to trivial changes (2)
- openspec/changes/add-agent-schema-selection/tasks.md
- openspec/changes/add-per-change-schema-metadata/proposal.md
🚧 Files skipped from review as they are similar to previous changes (1)
- schemas/spec-driven/templates/proposal.md
🧰 Additional context used
📓 Path-based instructions (5)
openspec/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Files:
openspec/specs/cli-artifact-workflow/spec.md
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/design.mdopenspec/changes/add-agent-schema-selection/proposal.mdopenspec/changes/add-per-change-schema-metadata/tasks.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/add-agent-schema-selection/proposal.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/add-per-change-schema-metadata/tasks.md
🧠 Learnings (17)
📓 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:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdschemas/spec-driven/schema.yamlopenspec/changes/add-per-change-schema-metadata/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/design.mdschemas/spec-driven/schema.yamlopenspec/changes/add-per-change-schema-metadata/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdschemas/spec-driven/schema.yaml
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/design.mddocs/experimental-release-plan.mdschemas/spec-driven/schema.yamlsrc/commands/artifact-workflow.tsopenspec/changes/add-agent-schema-selection/proposal.mddocs/schema-workflow-gaps.mdopenspec/changes/add-per-change-schema-metadata/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdschemas/spec-driven/schema.yamldocs/schema-workflow-gaps.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/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-per-change-schema-metadata/design.mddocs/experimental-release-plan.mdschemas/spec-driven/schema.yamlopenspec/changes/add-per-change-schema-metadata/tasks.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:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mddocs/experimental-release-plan.mdschemas/spec-driven/schema.yamlopenspec/changes/add-agent-schema-selection/proposal.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mddocs/schema-workflow-gaps.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: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.mddocs/schema-workflow-gaps.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `#### Scenario: Name` format (4 hashtags) for scenario headers, not bullets or bold text
Applied to files:
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
openspec/changes/add-per-change-schema-metadata/design.mddocs/experimental-release-plan.mdschemas/spec-driven/schema.yaml
📚 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.mdschemas/spec-driven/schema.yamlopenspec/changes/add-agent-schema-selection/proposal.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/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
docs/experimental-release-plan.mdsrc/commands/artifact-workflow.tsopenspec/changes/add-per-change-schema-metadata/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/specs/**/spec.md : Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Applied to files:
schemas/spec-driven/schema.yaml
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
schemas/spec-driven/schema.yaml
📚 Learning: 2025-11-17T12:07:21.701Z
Learnt from: ydai-hub
Repo: Fission-AI/OpenSpec PR: 268
File: src/core/configurators/iflow.ts:14-21
Timestamp: 2025-11-17T12:07:21.701Z
Learning: In the OpenSpec repository, `TemplateManager.getClaudeTemplate()` returns a generic template that works for iFlow and other CLI tools, not just Claude-specific content. It's acceptable to use this template across different tool configurators.
Applied to files:
src/core/templates/skill-templates.ts
🧬 Code graph analysis (1)
src/commands/artifact-workflow.ts (2)
src/core/artifact-graph/instruction-loader.ts (1)
loadChangeContext(150-167)src/core/templates/skill-templates.ts (3)
getNewChangeSkillTemplate(21-75)getContinueChangeSkillTemplate(81-176)getApplyChangeSkillTemplate(182-321)
🪛 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)
[uncategorized] ~401-~401: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...onfusion 1. Redundant CLI calls status AND `ne...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[grammar] ~446-~446: Use a hyphen to join words.
Context: ...eady provided enough context (e.g., "tic tac toe, single player vs AI, minimal ae...
(QB_NEW_EN_HYPHEN)
[grammar] ~446-~446: Use a hyphen to join words.
Context: ... provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthe...
(QB_NEW_EN_HYPHEN)
[grammar] ~578-~578: Ensure spelling is correct
Context: ...) vs create + instructions + Read + Edit×N (4+) - Scaffolding doesn't solve the re...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~663-~663: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...mplete and user wants to proceed - User wants to continue implementation after a break ...
(REP_WANT_TO_VB)
🪛 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)
380-380: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
595-595: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
690-690: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
691-691: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
692-692: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
693-693: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
696-696: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
697-697: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
698-698: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
737-737: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
755-755: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
774-774: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
793-793: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
831-831: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (19)
docs/schema-workflow-gaps.md (1)
213-213: Documentation update aligns with Next Command removal.The updated comment correctly reflects the Status Command behavior after the Next Command deprecation, maintaining documentation accuracy with the new status-driven workflow.
openspec/changes/add-agent-schema-selection/proposal.md (1)
1-26: Proposal and supporting documentation are complete and properly structured.The change scaffold is fully implemented with correct formatting:
proposal.mdincludes Why, What Changes, and Impact sections with clear motivation and backward compatibility statementtasks.mdcontains a comprehensive implementation checklist with 5 numbered sections and 12 checkpoint items covering all three skills (new-change, continue-change, apply-change), schema discovery, and documentation- Dependency on
add-per-change-schema-metadatais explicit and tracked in PrerequisitesAll supporting documents required by the coding guidelines are in place.
schemas/spec-driven/schema.yaml (1)
15-22: Excellent structured capability discovery! This solves a documented blocker.The new Capabilities section directly addresses the "specs directory ambiguity" pain point identified in E2E testing. By requiring explicit listing of new vs. modified capabilities with kebab-case names, this creates a clear contract between proposal and specs phases and eliminates agent confusion about where to create spec files.
The warning block appropriately emphasizes the critical nature of this section and the requirement for corresponding spec files.
Based on the experimental release plan (Decision 1: Capability Discovery in Proposal), which documents this as a blocker fix.
openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md (1)
1-98: LGTM! Spec delta follows OpenSpec conventions correctly.The spec file properly uses:
## ADDED Requirementsand## MODIFIED Requirementsheaders#### Scenario:format (4 hashtags) for all scenarios- SHALL for normative requirements
- WHEN/THEN format for scenario definitions
- Full requirement blocks in MODIFIED section
As per coding guidelines for spec delta files.
openspec/changes/add-per-change-schema-metadata/design.md (1)
1-147: LGTM! Design doc appropriately covers cross-cutting metadata system.The design document correctly justifies its existence (cross-cutting change affecting CLI, file system, and workflow) and follows the standard structure with Context, Goals/Non-Goals, Decisions, Risks/Trade-offs, and Migration Plan sections.
Key strengths:
- Clear Zod schema design with validation
- Explicit schema resolution order (flag > metadata > default)
- Backward compatibility maintained
- Minimal scope (only schema field for now)
Based on learnings: design.md is appropriate for cross-cutting changes and data model changes.
src/core/templates/skill-templates.ts (2)
11-15: Well-structured skill templates with comprehensive instructions.The SkillTemplate interface and three factory functions are well-designed:
- Clean interface with required fields matching Agent Skills spec
- Detailed step-by-step instructions with guardrails
- Clear output formats for each workflow phase
- Appropriate separation of concerns (new/continue/apply)
The templates provide comprehensive guidance for agent workflows including error handling, progress tracking, and fluid workflow integration.
Note: This approval is for the structure and content organization. The AskUserQuestion compatibility issue flagged separately still needs resolution.
Also applies to: 21-321
33-34: AskUserQuestion tool breaks cross-editor compatibility (duplicate issue).This is the same issue flagged in previous review comments: the AskUserQuestion tool is Claude-specific and not part of the Agent Skills specification. Since the PR explicitly targets "Claude Code, Cursor, Windsurf, and other Agent Skills-compatible editors," using this undocumented Claude-only tool breaks cross-editor compatibility.
The issue appears in all three skill templates:
- Line 33-34:
getNewChangeSkillTemplate()- Lines 93-94:
getContinueChangeSkillTemplate()- Line 194:
getApplyChangeSkillTemplate()Replace with a documented cross-editor approach or clearly document this as Claude-only with appropriate fallback instructions for other editors.
Also applies to: 93-94, 194-194
Likely an incorrect or invalid review comment.
docs/experimental-release-plan.md (2)
1-920: Comprehensive and well-structured experimental release plan.The document provides excellent coverage of the experimental workflow release:
- Clear overview distinguishing three workflow modes
- Detailed work items with dependency tracking
- Thorough analysis of E2E testing feedback with prioritized pain points
- Well-reasoned design decisions addressing documented blockers
- Documentation of the fluid "actions on a change" model
- Clear success criteria and scope boundaries
The plan demonstrates thoughtful iteration based on user testing and provides strong guidance for implementation and future user documentation.
Note: CLI output documentation accuracy issues flagged separately still need correction.
136-136: Replace placeholder repository URL.The placeholder URL
https://github.com/your-org/openspec/issuesshould be replaced with the actual repository URLhttps://github.com/Fission-AI/OpenSpec/issuesbefore release.Note: This same placeholder appears in
src/commands/artifact-workflow.tsat line 519 and should be updated in both locations.⛔ 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: Check `openspec/project.md` for project conventions before creating specsLearnt 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 guidelinesLearnt 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 codingopenspec/changes/add-per-change-schema-metadata/tasks.md (1)
1-29: LGTM! Well-structured implementation checklist.The tasks.md file follows the required format with numbered sections and checkbox items. The task breakdown is clear, logical, and aligns well with the per-change schema metadata feature described in the PR objectives.
src/commands/artifact-workflow.ts (9)
29-30: LGTM! Imports support the new experimental setup functionality.The imports for skill templates and FileSystemUtils are appropriately scoped to the new agent skills generation feature.
36-60: LGTM! Type definitions are well-structured.The TaskItem and ApplyInstructions interfaces appropriately model the apply instructions feature with clear field names and comprehensive state coverage.
398-419: LGTM! Task parsing correctly handles checkbox extraction.The regex pattern appropriately matches only top-level tasks (not indented sub-tasks) and supports both standard checkbox formats.
454-500: LGTM! State determination logic and data construction are sound.The function correctly handles context file collection, task parsing, progress calculation, and state transitions. The glob pattern for specs is appropriate for agent consumption.
503-576: LGTM! Command handler and output formatting are well-implemented.The applyInstructionsCommand follows established patterns with appropriate error handling and spinner feedback. The printApplyInstructionsText function provides clear, structured output for both human and agent consumption.
724-749: LGTM! Success message provides clear, helpful guidance.The output effectively communicates what was created, how to use the skills across different editors, and sets appropriate expectations for the experimental feature.
785-796: LGTM! Instruction routing elegantly handles the apply use case.The special-case routing for
artifactId === 'apply'cleanly extends the instructions command to support apply instructions without cluttering the command structure.
837-849: LGTM! Command registration follows established patterns.The artifact-experimental-setup command is properly wired with consistent error handling and spinner feedback.
720-720: No action needed — idempotency is correctly implemented.FileSystemUtils.writeFile() uses fs.writeFile(), which completely overwrites files. The
skillContentis generated fresh from template data (name, description, instructions) each run, making the operation deterministic and idempotent. Running the command multiple times produces identical results without corruption, duplication, or unintended data loss. Directory creation is handled automatically, and the behavior is intentional and safe.
…proposal Changes: - Fix generateApplyInstructions to treat design.md as optional (not required) - Update experimental-release-plan.md CLI output to match implementation - Add openspec-apply-change skill to docs (was missing) - Fix test flow numbering after adding apply skill verification step - Add change proposal for making apply instructions schema-aware The schema-aware proposal introduces an `implementation` block in schema.yaml to define when a change becomes implementable and how to track progress.
There was a problem hiding this comment.
Actionable comments posted: 1
Fix all issues with AI Agents 🤖
In @src/commands/artifact-workflow.ts:
- Around line 710-716: The YAML frontmatter built in the skillContent string
uses an unquoted description which can break parsing for colons, quotes, or
multiline text; update the template assembly in skillContent so the description
is safely represented — either wrap ${template.description} in a YAML-safe
quoted string (e.g., double quotes with proper escaping of internal
quotes/backslashes) or switch to a block scalar style (description: | followed
by a newline and the indented ${template.description}) to preserve multiline
content; ensure you apply this change where skillContent is constructed and
reference template.description (and keep template.name and template.instructions
unchanged).
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/experimental-release-plan.mdopenspec/changes/make-apply-instructions-schema-aware/proposal.mdopenspec/changes/make-apply-instructions-schema-aware/tasks.mdsrc/commands/artifact-workflow.ts
✅ Files skipped from review due to trivial changes (1)
- openspec/changes/make-apply-instructions-schema-aware/tasks.md
🧰 Additional context used
📓 Path-based instructions (2)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/make-apply-instructions-schema-aware/proposal.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/make-apply-instructions-schema-aware/proposal.md
🧠 Learnings (9)
📓 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>/`
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/make-apply-instructions-schema-aware/proposal.mddocs/experimental-release-plan.mdsrc/commands/artifact-workflow.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/make-apply-instructions-schema-aware/proposal.mddocs/experimental-release-plan.mdsrc/commands/artifact-workflow.ts
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/make-apply-instructions-schema-aware/proposal.mddocs/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: 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:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
docs/experimental-release-plan.mdsrc/commands/artifact-workflow.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
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/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
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/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
docs/experimental-release-plan.mdsrc/commands/artifact-workflow.ts
🧬 Code graph analysis (1)
src/commands/artifact-workflow.ts (3)
src/core/artifact-graph/instruction-loader.ts (1)
loadChangeContext(150-167)src/core/templates/skill-templates.ts (3)
getNewChangeSkillTemplate(21-75)getContinueChangeSkillTemplate(81-176)getApplyChangeSkillTemplate(182-321)src/utils/file-system.ts (1)
FileSystemUtils(44-209)
🪛 LanguageTool
docs/experimental-release-plan.md
[style] ~115-~115: This phrase is redundant (‘I’ stands for ‘Interface’). Use simply “CLIInterface”.
Context: ... name, description, instructions **CLI Interface:**bash openspec artifact-experiment...
(ACRONYM_TAUTOLOGY)
[uncategorized] ~406-~406: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...onfusion 1. Redundant CLI calls status AND `ne...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[grammar] ~451-~451: Use a hyphen to join words.
Context: ...eady provided enough context (e.g., "tic tac toe, single player vs AI, minimal ae...
(QB_NEW_EN_HYPHEN)
[grammar] ~451-~451: Use a hyphen to join words.
Context: ... provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthe...
(QB_NEW_EN_HYPHEN)
[grammar] ~583-~583: Ensure spelling is correct
Context: ...) vs create + instructions + Read + Edit×N (4+) - Scaffolding doesn't solve the re...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~668-~668: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...mplete and user wants to proceed - User wants to continue implementation after a break ...
(REP_WANT_TO_VB)
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-release-plan.md
105-105: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
291-291: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
385-385: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
600-600: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
695-695: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
696-696: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
697-697: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
698-698: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
701-701: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
702-702: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
703-703: Unordered list indentation
Expected: 0; Actual: 3
(MD007, ul-indent)
742-742: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
760-760: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
779-779: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
798-798: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
836-836: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
src/commands/artifact-workflow.ts (2)
398-419: Task parsing logic is sound.The parseTasksFile function correctly handles markdown checkboxes with both list markers (- and *) and case-insensitive completion indicators (x/X). The sequential ID generation is appropriate for progress tracking.
424-500: Apply instructions logic correctly handles all states.The generateApplyInstructions function properly determines blocked/ready/all_done states and builds context files with appropriate optional handling. The state determination logic covers all edge cases including missing artifacts, empty tasks, and completed tasks.
openspec/changes/make-apply-instructions-schema-aware/proposal.md (1)
1-138: Well-structured proposal following OpenSpec conventions.This proposal correctly follows the OpenSpec format with all required sections:
- Why: Concise problem statement identifying the hardcoded spec-driven artifacts issue
- What Changes: Clear scope and bullet list of changes with dependency noted
- Capabilities: Modified capability (cli-artifact-workflow) identified
- Impact: Affected code, schema format, and backward compatibility covered
The extended Design Decision section (lines 18-127) adds significant value by analyzing five options with pros/cons before documenting the chosen approach. The proposed
applyblock schema extension is technically sound and backward compatible.Based on coding guidelines for openspec/changes/*/proposal.md.
| const skillContent = `--- | ||
| name: ${template.name} | ||
| description: ${template.description} | ||
| --- | ||
| ${template.instructions} | ||
| `; |
There was a problem hiding this comment.
YAML description field should be quoted.
The description field in the YAML frontmatter is not quoted, which can break YAML parsing when descriptions contain special characters like colons, quotes, or multiline content.
🔎 Proposed fix
// Generate SKILL.md content with YAML frontmatter
const skillContent = `---
name: ${template.name}
-description: ${template.description}
+description: "${template.description.replace(/"/g, '\\"')}"
---
${template.instructions}
`;📝 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.
| const skillContent = `--- | |
| name: ${template.name} | |
| description: ${template.description} | |
| --- | |
| ${template.instructions} | |
| `; | |
| const skillContent = `--- | |
| name: ${template.name} | |
| description: "${template.description.replace(/"/g, '\\"')}" | |
| --- | |
| ${template.instructions} | |
| `; |
🤖 Prompt for AI Agents
In @src/commands/artifact-workflow.ts around lines 710-716, The YAML frontmatter
built in the skillContent string uses an unquoted description which can break
parsing for colons, quotes, or multiline text; update the template assembly in
skillContent so the description is safely represented — either wrap
${template.description} in a YAML-safe quoted string (e.g., double quotes with
proper escaping of internal quotes/backslashes) or switch to a block scalar
style (description: | followed by a newline and the indented
${template.description}) to preserve multiline content; ensure you apply this
change where skillContent is constructed and reference template.description (and
keep template.name and template.instructions unchanged).
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 [email protected]
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.