proposal: add artifact workflow CLI commands (Slice 4) #415
Conversation
Add CLI commands for artifact workflow operations: - `openspec status --change <id>` - Show artifact completion state - `openspec next --change <id>` - Show ready artifacts - `openspec instructions <artifact> --change <id>` - Get enriched template - `openspec templates --change <id>` - Show template paths - `openspec new change <name>` - Create new change Commands are top-level for fluid UX and implemented in isolation for easy removal (experimental feature).
📝 WalkthroughWalkthroughIntroduces an experimental artifact-workflow CLI feature with multiple commands (status, next, instructions, templates, new change) that expose artifact graph and instruction generation APIs. Implementation is centralized in a single module, registered via CLI entry point. The specs artifact glob pattern is updated to support recursive directory matching. Changes
Sequence Diagram(s)sequenceDiagram
participant CLI as CLI User
participant Cmd as Command Handler
participant Ctx as Change Context
participant Graph as ArtifactGraph
participant Loader as Instruction Loader
participant Out as Output Formatter
CLI->>Cmd: openspec status --change foo
Cmd->>Ctx: validate --change exists
Cmd->>Ctx: loadChangeContext(changeId)
Ctx->>Graph: resolveSchema()
Graph-->>Ctx: schema resolved
Ctx->>Graph: create ArtifactGraph
Graph-->>Ctx: artifacts with metadata
Cmd->>Loader: formatChangeStatus(graph)
Loader-->>Cmd: formatted status (colors, blocks)
Cmd->>Out: print with --json/--no-color options
Out-->>CLI: ✓ status report or JSON output
CLI->>Cmd: openspec new change <name>
Cmd->>Ctx: validateChangeName(name)
Ctx-->>Cmd: name valid
Cmd->>Ctx: createChange(name, description)
Ctx-->>Cmd: directory created + README written
Cmd->>Out: print success message
Out-->>CLI: ✓ change created
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
openspec/changes/add-artifact-workflow-cli/proposal.md (1)
1-9: Fix redundant acronym in Why section.Line 3 uses "CLI interface," but CLI already stands for Command Line Interface. Simplify to just "CLI."
🔎 Proposed fix
-The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to: +The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no way to use the CLI to:Or even simpler:
-The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to: +The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently cannot:openspec/changes/add-artifact-workflow-cli/design.md (1)
27-27: Add language identifiers to fenced code blocks.Markdown linting standards require language identifiers for fenced code blocks. Lines 27 and 46 both have bare
```without language specifiers (should be```bashin both cases).🔎 Proposed fixes
Line 27 (command structure example):
-``` +```bash openspec status --change <id> openspec next --change <id> openspec instructions <artifact> --change <id> openspec templates --change <id> openspec new change <name> -``` +```Line 46 (file location example):
-``` +```text src/commands/artifact-workflow.ts -``` +```Also applies to: 46-46
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
openspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/tasks.md
🧰 Additional context used
📓 Path-based instructions (4)
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-artifact-workflow-cli/tasks.mdopenspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.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-artifact-workflow-cli/tasks.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-artifact-workflow-cli/proposal.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-artifact-workflow-cli/specs/cli-workflow/spec.md
🧠 Learnings (9)
📓 Common learnings
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: 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
📚 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:
openspec/changes/add-artifact-workflow-cli/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/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/add-artifact-workflow-cli/tasks.mdopenspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-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: 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-artifact-workflow-cli/tasks.mdopenspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.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-artifact-workflow-cli/tasks.mdopenspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-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-artifact-workflow-cli/design.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 Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-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: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-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: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-artifact-workflow-cli/design.md
🪛 LanguageTool
openspec/changes/add-artifact-workflow-cli/proposal.md
[style] ~3-~3: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...low management. Users currently have no CLI interface to: - See artifact completion status fo...
(ACRONYM_TAUTOLOGY)
🪛 markdownlint-cli2 (0.18.1)
openspec/changes/add-artifact-workflow-cli/design.md
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (4)
openspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.md (1)
1-149: Specification structure is well-formed and compliant.The spec follows all guidelines:
## ADDED Requirementsheader, 8 well-scoped requirements with actionable descriptions, and 27 total scenarios all using the correct#### Scenario: Nameformat (4 hashtags). Each scenario includes WHEN/THEN patterns with clear acceptance criteria. Coverage includes command semantics, JSON output, error handling, UI considerations, and experimental isolation—providing a solid foundation for implementation.openspec/changes/add-artifact-workflow-cli/proposal.md (1)
11-32: Proposal structure is well-formed and complete.The What Changes section clearly lists the five new commands with "NEW" markers, explains integration points with existing modules (instruction-loader, artifact-graph, change-utils), and highlights the experimental isolation strategy. The Impact section properly documents affected specs and code locations. All required sections follow the proposal.md template.
openspec/changes/add-artifact-workflow-cli/tasks.md (1)
1-48: Tasks checklist is well-structured and comprehensive.All seven sections (Core Implementation, CLI Registration, Output Formatting, Error Handling, Options, Testing, Documentation) use proper numbered hierarchy (1.1, 1.2, etc.) with checkbox items. Coverage spans command implementation, registration, output modes (text, JSON, colors, spinners), error cases, flags, and testing—aligning well with both the proposal and specification. 28 tasks provide a solid roadmap without being over-granular.
openspec/changes/add-artifact-workflow-cli/design.md (1)
1-111: Design decisions are well-documented and justified.The document provides clear rationale for each major decision: top-level verb commands for UX fluidity, single-file isolation for easy removal, explicit
--changefor deterministic behavior, and structured subcommands for extensibility. The Goals/Non-Goals clarify scope, and the Risks table explicitly addresses trade-offs. Integration notes reference concrete module sources (artifact-graph, item-discovery.ts). This design document is justified per guidelines for cross-cutting decisions and experimental isolation strategy.
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
Templates are schema-level, not change-level. The command now uses --schema instead of --change for consistency with how templates are actually resolved.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
openspec/changes/add-artifact-workflow-cli/proposal.md (1)
11-24: Mark changes as non-breaking.The "What Changes" section lists five NEW commands with no modifications to existing commands or specs. Consider explicitly indicating that these are non-breaking changes to align with proposal guidelines for breaking change markers:
## What Changes -- **NEW**: `openspec status --change <id>` shows artifact completion state -- **NEW**: `openspec next --change <id>` shows artifacts ready to create -- **NEW**: `openspec instructions <artifact> --change <id>` outputs enriched template -- **NEW**: `openspec templates [--schema <name>]` shows resolved template paths -- **NEW**: `openspec new change <name>` creates a new change directory +- **NEW** (non-breaking): `openspec status --change <id>` shows artifact completion state +- **NEW** (non-breaking): `openspec next --change <id>` shows artifacts ready to create +- **NEW** (non-breaking): `openspec instructions <artifact> --change <id>` outputs enriched template +- **NEW** (non-breaking): `openspec templates [--schema <name>]` shows resolved template paths +- **NEW** (non-breaking): `openspec new change <name>` creates a new change directory
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
openspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.md
🧰 Additional context used
📓 Path-based instructions (3)
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-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/proposal.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-artifact-workflow-cli/specs/cli-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-artifact-workflow-cli/proposal.md
🧠 Learnings (8)
📓 Common learnings
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: 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/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
📚 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-artifact-workflow-cli/design.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:
openspec/changes/add-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/proposal.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-artifact-workflow-cli/design.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/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/*/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-artifact-workflow-cli/specs/cli-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/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/**/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/changes/add-artifact-workflow-cli/specs/cli-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: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-artifact-workflow-cli/specs/cli-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: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
openspec/changes/add-artifact-workflow-cli/proposal.md
🪛 LanguageTool
openspec/changes/add-artifact-workflow-cli/proposal.md
[style] ~3-~3: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...low management. Users currently have no CLI interface to: - See artifact completion status fo...
(ACRONYM_TAUTOLOGY)
🔇 Additional comments (5)
openspec/changes/add-artifact-workflow-cli/design.md (2)
27-32: Clarify--schemaflag scope across commands.The command examples show
--schemaonly for thetemplatescommand, but the spec.md file (Requirement: Schema Selection, line 122) requiresopenspec status --change <id> --schema tdd. Verify whether:
--schemashould apply to all workflow commands (status, next, instructions) or just templates, and- Update command examples to reflect the actual design.
106-111: Verify referenced module functions.The implementation notes reference specific functions like
getActiveChangeIds()fromitem-discovery.ts,loadChangeContext()andformatChangeStatus()frominstruction-loader, etc. Confirm these functions exist and are accessible fromsrc/commands/artifact-workflow.tsbefore implementation begins.openspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.md (3)
79-93: Verify templates command signature matches design.The "Templates Command" requirement (lines 76-93) specifies behavior for
openspec templates [--schema <name>](line 84), which aligns with design.md line 31. However, ensure the optional[--schema <name>]syntax is consistent with how other optional flags are handled in error messages and help text (e.g., whether omitting--schemashould use a default or error).
132-142: Confirm color and spinner output implementation details.The "Output Formatting" requirement (lines 132-142) specifies:
- Color output using green (done), yellow (ready), red (blocked) — lines 134
- Spinner display during loading — line 142
Ensure these visual implementations:
- Are compatible with the existing CLI framework (ora spinners, colors library, etc.)
- Handle both TTY and non-TTY environments correctly
- Respect
--no-colorflag andNO_COLORenvironment variable globally
98-112: Verify "Create with description" scenario and UX flow.The "New Change Command" requirement includes a scenario (lines 110-112) for
openspec new change add-feature --description "Add new feature"that creates a change directory with description in README.md. Confirm:
- The
--descriptionflag is intentional (not mentioned in proposal.md or design.md).- The implementation creates/updates README.md with the description.
- The change directory structure and initialization are consistent with existing change scaffolding.
| ## Why | ||
|
|
||
| The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to: | ||
| - See artifact completion status for a change | ||
| - Discover what artifacts are ready to create | ||
| - Get enriched instructions for creating artifacts | ||
| - Create new changes with proper validation | ||
|
|
||
| This proposal adds CLI commands that expose the artifact workflow functionality to users and agents. |
There was a problem hiding this comment.
Fix redundant "CLI interface" phrase.
Line 3 uses the redundant phrase "no CLI interface to:" which should be simplified to "no CLI to:" since CLI already means "command-line interface."
🔎 Proposed fix
-The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to:
+The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI to:📝 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.
| ## Why | |
| The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to: | |
| - See artifact completion status for a change | |
| - Discover what artifacts are ready to create | |
| - Get enriched instructions for creating artifacts | |
| - Create new changes with proper validation | |
| This proposal adds CLI commands that expose the artifact workflow functionality to users and agents. | |
| ## Why | |
| The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI to: | |
| - See artifact completion status for a change | |
| - Discover what artifacts are ready to create | |
| - Get enriched instructions for creating artifacts | |
| - Create new changes with proper validation | |
| This proposal adds CLI commands that expose the artifact workflow functionality to users and agents. |
🧰 Tools
🪛 LanguageTool
[style] ~3-~3: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...low management. Users currently have no CLI interface to: - See artifact completion status fo...
(ACRONYM_TAUTOLOGY)
🤖 Prompt for AI Agents
In openspec/changes/add-artifact-workflow-cli/proposal.md around lines 1 to 9,
the phrase "no CLI interface to:" is redundant; replace it with "no CLI to:" (or
"no CLI for:") so the sentence reads "Users currently have no CLI to:" and
update the bullet list punctuation if needed to keep grammatical consistency.
| ### Requirement: Schema Selection | ||
| The system SHALL support custom schema selection for workflow commands. | ||
|
|
||
| #### Scenario: Default schema | ||
| - **WHEN** user runs workflow commands without `--schema` | ||
| - **THEN** the system uses the "spec-driven" schema | ||
|
|
||
| #### Scenario: Custom schema | ||
| - **WHEN** user runs `openspec status --change <id> --schema tdd` | ||
| - **THEN** the system uses the specified schema for artifact graph | ||
|
|
||
| #### Scenario: Unknown schema | ||
| - **WHEN** user specifies an unknown schema | ||
| - **THEN** the system displays an error listing available schemas |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find openspec/changes/add-artifact-workflow-cli -type f -name "*.md" | head -20Repository: Fission-AI/OpenSpec
Length of output: 292
🏁 Script executed:
cat -n openspec/changes/add-artifact-workflow-cli/design.md | head -50Repository: Fission-AI/OpenSpec
Length of output: 1914
🏁 Script executed:
cat -n openspec/changes/add-artifact-workflow-cli/proposal.md | head -50Repository: Fission-AI/OpenSpec
Length of output: 1973
🏁 Script executed:
cat -n openspec/changes/add-artifact-workflow-cli/design.md | tail -50Repository: Fission-AI/OpenSpec
Length of output: 2011
🏁 Script executed:
cat -n openspec/changes/add-artifact-workflow-cli/proposal.mdRepository: Fission-AI/OpenSpec
Length of output: 1973
🏁 Script executed:
wc -l openspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.mdRepository: Fission-AI/OpenSpec
Length of output: 136
🏁 Script executed:
cat -n openspec/changes/add-artifact-workflow-cli/specs/cli-workflow/spec.md | head -130Repository: Fission-AI/OpenSpec
Length of output: 6419
Schema Selection requirement introduces scope not defined in design/proposal documents.
The "Schema Selection" requirement (lines 114-127) specifies --schema support for workflow commands, but design.md only shows --schema for the templates command (line 31). Key inconsistencies:
- Scope mismatch: spec.md line 122 shows
openspec status --change <id> --schema tdd, but design.md (line 28) specifiesopenspec status --change <id>without--schema. - Undocumented default: spec.md line 119 defines "spec-driven" as the default schema, but this is not documented in design.md or proposal.md.
The spec introduces new behavior not previously approved. Clarify whether --schema should apply to all workflow commands or only templates, and document the default schema name in design.md.
More specific capability name that clarifies which workflow the CLI commands are for.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
openspec/changes/add-artifact-workflow-cli/proposal.md (1)
3-3: Fix the redundant "CLI interface" phrase.This is a repeat of a past review comment: the phrase "CLI interface" is tautological since CLI already stands for "command-line interface." Simplify to "no CLI to:".
🔎 Proposed fix
-The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to: +The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI to:openspec/changes/add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.md (1)
8-32: ** Schema Selection scope inconsistency remains unresolved from previous review.**The Schema Selection requirement (lines 114–127) shows
--schemaapplied to thestatuscommand (line 122), but the Status Command requirement (lines 8–32) does not include any--schemavariant scenarios. This creates structural confusion about which commands support schema selection.Additionally, the previous review flagged that design.md only documents
--schemafor thetemplatescommand, yet this spec proposes it forstatusand other "workflow commands" without design documentation.Per coding guidelines, spec changes require design justification. Either:
- Add
--schemascenarios to each affected command requirement (Status, Next, Instructions), or- Clarify in the Schema Selection requirement that it applies only to
templates, and move schema handling into the Templates Command requirement.Please confirm the design.md currently documents which commands support
--schema, or provide updated design documentation if the schema scope has changed since the previous review:#!/bin/bash # Verify design.md documents which commands support --schema grep -n "\-\-schema" openspec/changes/add-artifact-workflow-cli/design.mdAlso applies to: 114-127
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
openspec/changes/add-artifact-workflow-cli/proposal.mdopenspec/changes/add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.md
🧰 Additional context used
📓 Path-based instructions (3)
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-artifact-workflow-cli/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/proposal.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-artifact-workflow-cli/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-artifact-workflow-cli/proposal.md
🧠 Learnings (13)
📓 Common learnings
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: 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
📚 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/changes/add-artifact-workflow-cli/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: 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/add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/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/**/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/changes/add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.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-artifact-workflow-cli/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/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-artifact-workflow-cli/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-artifact-workflow-cli/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: 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-artifact-workflow-cli/specs/cli-artifact-workflow/spec.mdopenspec/changes/add-artifact-workflow-cli/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/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.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:
openspec/changes/add-artifact-workflow-cli/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: 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:
openspec/changes/add-artifact-workflow-cli/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: 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/changes/add-artifact-workflow-cli/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: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
openspec/changes/add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.md
🪛 LanguageTool
openspec/changes/add-artifact-workflow-cli/proposal.md
[style] ~3-~3: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...low management. Users currently have no CLI interface to: - See artifact completion status fo...
(ACRONYM_TAUTOLOGY)
🔇 Additional comments (1)
openspec/changes/add-artifact-workflow-cli/proposal.md (1)
1-32: Proposal structure meets all requirements.The document follows the required scaffold structure with all three sections (Why, What Changes, Impact) clearly articulated. The "Why" section concisely explains the motivation, "What Changes" enumerates the five new commands with clear integration points and experimental isolation notes, and "Impact" precisely identifies affected specs and code files. The use of NEW markers is appropriate since no breaking changes are introduced.
| ### Requirement: Experimental Isolation | ||
| The system SHALL implement artifact workflow commands in isolation for easy removal. | ||
|
|
||
| #### Scenario: Single file implementation | ||
| - **WHEN** artifact workflow feature is implemented | ||
| - **THEN** all commands are in `src/commands/artifact-workflow.ts` | ||
|
|
||
| #### Scenario: Help text marking |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Experimental Isolation requirement is incomplete without help text content.
Line 152–153 state that help text "SHALL indicate the command is experimental," but the requirement does not specify the exact help text string or where it appears in the implementation. This leaves ambiguity for developers about compliance.
Add a clarifying scenario defining the exact help text format:
🔎 Proposed addition
#### Scenario: Help text marking
- **WHEN** user runs `--help` on any artifact workflow command
- **THEN** help text indicates the command is experimental
+
+#### Scenario: Help text format
+- **WHEN** user runs `openspec status --help`
+- **THEN** help text includes prefix or footer marking: "(Experimental)" or similar clear indicatorBased on coding guidelines, each scenario should be concrete enough for implementation; this adds the needed specificity.
Add experimental CLI commands for artifact-based workflow management: - `openspec status --change <id>` - display artifact completion status - `openspec next --change <id>` - show artifacts ready to create - `openspec instructions <artifact> --change <id>` - output enriched template - `openspec templates [--schema <name>]` - show resolved template paths - `openspec new change <name>` - create new change directory Features: - JSON output support (--json flag) for all commands - Color-coded status indicators (green/yellow/red) - Progress spinners during loading - --no-color and NO_COLOR env support - --schema option for custom schema selection - Comprehensive error handling with helpful messages All commands are isolated in src/commands/artifact-workflow.ts for easy removal if the feature doesn't work out. Help text marks them as experimental.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/commands/artifact-workflow.ts (1)
349-351: Consider a top-level import for consistency.The dynamic import of
getUserSchemasDiris different from other imports in this file. Unless there's a code-splitting reason, a static import at the top would be more consistent.🔎 Suggested change
Add to imports at top of file:
import { getUserSchemasDir } from '../core/artifact-graph/resolver.js';Then simplify line 349-351:
- const { getUserSchemasDir } = await import('../core/artifact-graph/resolver.js'); - const userSchemasDir = getUserSchemasDir(); + const userSchemasDir = getUserSchemasDir();
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
openspec/changes/add-artifact-workflow-cli/tasks.mdsrc/cli/index.tssrc/commands/artifact-workflow.ts
✅ Files skipped from review due to trivial changes (1)
- openspec/changes/add-artifact-workflow-cli/tasks.md
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
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>/`
🧬 Code graph analysis (2)
src/commands/artifact-workflow.ts (2)
src/utils/item-discovery.ts (1)
getActiveChangeIds(4-23)src/core/artifact-graph/graph.ts (1)
isComplete(139-146)
src/cli/index.ts (1)
src/commands/artifact-workflow.ts (1)
registerArtifactWorkflowCommands(431-515)
🔇 Additional comments (8)
src/cli/index.ts (1)
17-17: LGTM!The import and registration follow the established patterns in this file (
registerSpecCommand,registerConfigCommand). Placement beforeprogram.parse()is correct, and the comment clearly indicates the experimental nature of these commands.Also applies to: 320-322
src/commands/artifact-workflow.ts (7)
1-28: Well-documented experimental feature.The header comment clearly explains the purpose and provides explicit removal instructions, which is excellent for experimental feature isolation.
35-69: LGTM!The color helpers properly respect the
NO_COLORenvironment variable and provide a clean abstraction for status-based coloring.
74-115: Good UX for validation errors.The validation helpers provide helpful, actionable error messages by listing available changes/schemas when the requested one isn't found.
189-228: LGTM!The next command handles edge cases well (all complete, none ready), and the suggestion to run
statuswhen blocked is helpful for users.
240-287: LGTM!The instructions command provides comprehensive artifact details and handles missing artifacts gracefully with helpful error messages listing valid artifact IDs.
431-515: LGTM!The command registration follows a consistent pattern with proper error handling. All commands are clearly marked as experimental in their descriptions, and the
newcommand group structure is clean.
408-414: No action needed—no README.md conflict exists.The
createChangefunction only validates the change name, checks if the directory exists, and creates the necessary directories. It does not create aREADME.mdfile. The code at lines 408-414 safely creates aREADME.mdonly when a description is provided, with no risk of overwriting existing content.Likely an incorrect or invalid review comment.
| if (status.isComplete) { | ||
| console.log(); | ||
| console.log(chalk.green('All artifacts complete!')); | ||
| } | ||
| } |
There was a problem hiding this comment.
Inconsistent color handling with NO_COLOR support.
Line 175 uses chalk.green directly, bypassing the isColorDisabled() check established earlier in getStatusColor(). This will output ANSI codes even when NO_COLOR=1 is set.
The same pattern appears in printInstructionsText (lines 291, 305) and nextCommand (line 209).
🔎 Proposed fix
Consider creating a helper or consistently using the color pattern:
if (status.isComplete) {
console.log();
- console.log(chalk.green('All artifacts complete!'));
+ const successColor = getStatusColor('done');
+ console.log(successColor('All artifacts complete!'));
}Apply similar fixes to:
- Line 209 in
nextCommand - Lines 291 and 305 in
printInstructionsText
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| if (status.isComplete) { | |
| console.log(); | |
| console.log(chalk.green('All artifacts complete!')); | |
| } | |
| } | |
| if (status.isComplete) { | |
| console.log(); | |
| const successColor = getStatusColor('done'); | |
| console.log(successColor('All artifacts complete!')); | |
| } | |
| } |
🤖 Prompt for AI Agents
In src/commands/artifact-workflow.ts around lines 173–177 (and also address
similar occurrences at line 209 and lines 291 & 305), direct calls to
chalk.green bypass the module's NO_COLOR-aware logic; replace these direct
chalk.color calls with the centralized color helper used elsewhere (e.g., call
the existing getStatusColor() or the same NO_COLOR-aware chalk instance) so
coloring respects isColorDisabled()/NO_COLOR, and update the three other
locations (nextCommand at 209 and printInstructionsText at 291 and 305) the same
way to keep color handling consistent.
The schema used specs/*.md but specs are stored as specs/<capability>/spec.md. Updated to specs/**/*.md so openspec status/next correctly detect spec completion.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
test/commands/artifact-workflow.test.ts (1)
54-57: Update comment to reflect recursive glob pattern.The comment references
specs/*.md, but the schema was just updated tospecs/**/*.mdto support nested directories. Consider updating this comment and potentially adding a test case that creates nested specs (e.g.,specs/capability/spec.md) to verify the recursive glob behavior.🔎 Proposed update
- // specs artifact uses glob pattern "specs/*.md" - files directly in specs/ directory + // specs artifact uses glob pattern "specs/**/*.md" - supports nested directories const specsDir = path.join(changeDir, 'specs'); await fs.mkdir(specsDir, { recursive: true }); await fs.writeFile(path.join(specsDir, 'test-spec.md'), '## Purpose\nTest spec.');Optionally, add a nested spec file to better test the recursive glob:
await fs.mkdir(path.join(specsDir, 'capability'), { recursive: true }); await fs.writeFile( path.join(specsDir, 'capability', 'nested-spec.md'), '## Purpose\nNested spec.' );
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
schemas/spec-driven/schema.yamltest/commands/artifact-workflow.test.ts
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
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: 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
📚 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:
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: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
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: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
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: 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:
schemas/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: 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:
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: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
schemas/spec-driven/schema.yaml
🧬 Code graph analysis (1)
test/commands/artifact-workflow.test.ts (2)
test/helpers/run-cli.ts (1)
runCLI(75-148)scripts/postinstall.js (1)
stat(44-44)
🔇 Additional comments (7)
schemas/spec-driven/schema.yaml (1)
11-11: LGTM! Recursive glob enables nested spec organization.The change from
specs/*.mdtospecs/**/*.mdcorrectly enables discovery of specs in nested capability directories, supporting the new artifact-workflow CLI commands.test/commands/artifact-workflow.test.ts (6)
67-156: Excellent test coverage for status command.The test suite comprehensively covers happy paths (minimal/partial/complete changes, JSON output), error cases (missing/unknown change, unknown schema), and the --schema option.
158-207: LGTM! Next command tests are well-structured.Tests appropriately verify dependency-based artifact ordering, completion states, JSON output, and error handling.
209-270: Instructions command tests are comprehensive.Tests cover artifact instructions display, dependency blocking, JSON output, and error cases (missing/unknown artifact). The blocked artifact warning test is particularly valuable.
272-307: Templates command tests cover all scenarios.Tests validate template path display for default/custom schemas, JSON output structure, and error handling for unknown schemas.
309-354: New change command tests properly verify filesystem operations.Tests correctly validate directory creation, README generation with --description flag, and error cases (invalid/duplicate/missing name).
356-386: Help text tests ensure experimental marking.Tests systematically verify that all artifact-workflow commands display the [Experimental] tag in their help text, which aligns with the design decision to mark these commands for easy removal.
- Move change to archive/2025-12-28-add-artifact-workflow-cli - Create cli-artifact-workflow spec
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.md (1)
3-3: Fix redundant "CLI interface" phrase.Line 3 uses the redundant phrase "no CLI interface to:" which should be simplified to "no CLI to:" since CLI already stands for "command-line interface."
🔎 Proposed fix
-The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI interface to: +The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI to:
🧹 Nitpick comments (1)
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.md (1)
1-10: Condense the Why section to 1–2 sentences.The Why section should open with a concise problem statement in 1–2 sentences, then optionally provide supporting context. Currently, lines 3–7 form a multi-bullet list explaining user needs, which makes the section longer and less punchy than the convention allows.
Consider restructuring to lead with a single summary sentence (e.g., "Users need CLI access to artifact workflow features") followed by the inline or collapsed list of capabilities, or consolidate the bullets into narrative form.
🔎 Suggested restructuring
## Why -The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management. Users currently have no CLI to: -- See artifact completion status for a change -- Discover what artifacts are ready to create -- Get enriched instructions for creating artifacts -- Create new changes with proper validation +The ArtifactGraph (Slice 1) and InstructionLoader (Slice 3) provide programmatic APIs for artifact-based workflow management, but users lack CLI access to these capabilities: artifact status, discovery of ready artifacts, enriched instructions, and change creation. -This proposal adds CLI commands that expose the artifact workflow functionality to users and agents. +This proposal adds top-level CLI commands to bridge this gap.Based on learnings, proposal scaffolds should follow the convention of 1–2 concise sentences in the Why section. Does your version match the project's style guide (e.g., in
openspec/AGENTS.md)?
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/design.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.mdopenspec/specs/cli-artifact-workflow/spec.md
✅ Files skipped from review due to trivial changes (2)
- openspec/specs/cli-artifact-workflow/spec.md
- openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/specs/cli-artifact-workflow/spec.md
🧰 Additional context used
📓 Path-based instructions (1)
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/archive/2025-12-28-add-artifact-workflow-cli/design.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.md
🧠 Learnings (6)
📓 Common learnings
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: 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: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
📚 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/archive/2025-12-28-add-artifact-workflow-cli/design.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/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/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/design.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.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/archive/2025-12-28-add-artifact-workflow-cli/proposal.mdopenspec/changes/archive/2025-12-28-add-artifact-workflow-cli/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/*/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/archive/2025-12-28-add-artifact-workflow-cli/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:
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.md
🪛 LanguageTool
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.md
[style] ~3-~3: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...low management. Users currently have no CLI interface to: - See artifact completion status fo...
(ACRONYM_TAUTOLOGY)
🪛 markdownlint-cli2 (0.18.1)
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/design.md
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (7)
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/proposal.md (2)
11-25: Approve structure and content of What Changes and implementation details.The What Changes section properly lists all new commands with NEW markers, describes the integration points with existing modules, and clearly explains the experimental isolation strategy. The section aligns well with the PR objectives and architecture decisions.
26-33: Approve Impact section.The Impact section correctly documents affected specs and code, notes the lack of breaking changes, and references the prior slices. Completeness looks good.
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/design.md (3)
27-33: Add language specification to fenced code block.Line 27 opens a fenced code block but omits the language tag. This should be marked as
bashto enable proper syntax highlighting.-``` +```bash openspec status --change <id> openspec next --change <id> openspec instructions <artifact> --change <id> openspec templates [--schema <name>] openspec new change <name> -``` +```bash[suggest_minor_issue]
46-48: Add language specification to fenced code block.Line 46 opens a fenced code block but omits the language tag. Since this is a file path reference, use a generic marker:
-``` +```plaintext src/commands/artifact-workflow.ts -``` +```plaintext[suggest_minor_issue]
1-112: Design document is well-structured and comprehensive.The document effectively scaffolds the design decisions for the artifact workflow CLI feature, following the expected change proposal pattern. Clear rationale for top-level commands, experimental isolation strategy, deterministic CLI design, and error handling. The risks/trade-offs table clearly articulates what has been accepted. Implementation notes ground the design in concrete file locations and dependencies.
openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.md (2)
1-47: Task list structure and coverage looks good.The task list follows the required format with numbered sections and checkbox items, and comprehensively covers the artifact workflow CLI implementation across all key areas: core commands, CLI registration, output formatting, error handling, options, testing, and documentation. All implementation tasks (1–6) are marked complete.
48-48: Clarify the intent and status of the post-archive documentation task.Task 7.2 ("Update AGENTS.md with new commands (post-archive)") is incomplete and explicitly deferred with a "(post-archive)" note. Since this change has already been archived, clarify whether this task should:
- Be removed entirely (if documentation updates are not planned for archived changes);
- Be marked as "intentionally deferred for future release cycle" with a tracking issue link; or
- Be completed and marked done (if it should have been finished before archiving).
This ensures clarity on the final documentation state of the archived change.
Summary
New Commands
openspec status --change <id>openspec next --change <id>openspec instructions <artifact> --change <id>openspec templates --change <id>openspec new change <name>Key Design Decisions
--changerequired - CLI is deterministic, agents infer from contextFiles
proposal.md- Why and what changesdesign.md- CLI design decisionsspecs/cli-workflow/spec.md- 8 requirements, 27 scenariostasks.md- 22 implementation tasksTest plan
openspec validate add-artifact-workflow-cli --strictpasses🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
status,next,instructions,templates, andnew changefor managing project artifactsImprovements
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.