feat: simplify skill installation with profiles and smart defaults init#719
feat: simplify skill installation with profiles and smart defaults init#719
Conversation
Introduces a change proposal to simplify the init flow and skill installation: - Zero-question init with sensible defaults (core profile, both delivery) - Auto-detect AI tools from existing directories (.claude/, .cursor/, etc.) - Profile system: core (4 workflows), extended (11 workflows), custom - Delivery config: both, skills, commands - New `propose` workflow combining new + ff - Fix tool selection UX (space to select, enter to confirm) Key design decisions: - Extend existing global config (~/.config/openspec/config.json) - Profile install/uninstall immediately mutates filesystem - Safe deletion via SKILL_NAMES and COMMAND_IDS constant lookups - Filesystem as truth for installed workflows Also adds rules to openspec/config.yaml to prevent overengineering (explicit lookups over pattern matching).
|
Task completed. PR Review: feat: simplify skill installation with profiles and zero-question initOverall AssessmentThis is a well-structured change proposal with clear motivation, thorough design rationale, and detailed specs. The artifacts are internally consistent and follow the project's spec-driven conventions. Below are specific findings organized by priority. Issues1. Missing
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds design and detailed specifications to simplify OpenSpec skill/command installation: global config extensions (profile, delivery, workflows), a two-tier profile system (core, custom), a combined propose workflow, filesystem-based tool auto-detection with confirmation, profile-driven conditional generation, updated init UX (multi-select keybindings), and a phased migration plan. No runtime code changes. Changes
Sequence Diagram(s)sequenceDiagram
actor User as User
participant Init as "openspec init"
participant ToolDetect as "Tool Detection"
participant Config as "Global Config"
participant Generator as "Skill/Command Generator"
participant FS as "Filesystem"
User->>Init: run init (interactive/non-interactive)
Init->>ToolDetect: scan project for tool dirs (.claude, .cursor, ...)
ToolDetect->>FS: fs.existsSync(toolDir)
FS-->>ToolDetect: presence results
ToolDetect-->>Init: detectedTools
Init->>User: show multi-select (Space toggle, Enter confirm)
User->>Init: select/confirm tools
Init->>Config: read profile & delivery (apply defaults if absent)
Config-->>Init: profile, delivery
Init->>Generator: generate artifacts for profile+delivery+tools
Generator->>FS: write skill/command files (per delivery)
FS-->>Generator: write results
Generator-->>Init: completion
Init->>User: success message
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Greptile SummaryThis PR adds a comprehensive change proposal for simplifying OpenSpec's skill installation and initialization flow. The proposal introduces a three-tier profile system (core/extended/custom) to reduce workflow overwhelm for new users, enabling a zero-question init experience that gets users to an "aha moment" in under a minute. Key improvements include:
The change artifacts are well-structured with clear proposal, design decisions, implementation tasks, and 11 detailed spec files covering all modified and new capabilities. The design document provides strong rationale for architectural decisions like extending the existing global config, making profile install/uninstall operations immediately mutate the filesystem, and using explicit constant-based lookups for safety. Minor observations:
Confidence Score: 5/5
Important Files Changed
Flowchartflowchart TD
Start["`openspec init`"] --> DetectTools[Auto-detect AI tools<br/>from directories]
DetectTools --> ReadConfig[Read global config<br/>~/.config/openspec/config.json]
ReadConfig --> GetDefaults[Get defaults:<br/>profile=core, delivery=both]
GetDefaults --> Interactive{Interactive<br/>mode?}
Interactive -->|Yes| ShowTools[Show detected tools<br/>pre-selected]
Interactive -->|No| CheckTools{Tools<br/>detected?}
ShowTools --> ConfirmTools[User confirms/modifies<br/>Space to toggle, Enter to confirm]
CheckTools -->|Yes| UseDetected[Use detected tools]
CheckTools -->|No| Fail[Fail with error:<br/>Use --tools flag]
ConfirmTools --> ResolveProfile[Resolve profile:<br/>core/extended/custom]
UseDetected --> ResolveProfile
ResolveProfile --> CoreProfile{Profile?}
CoreProfile -->|core| InstallCore[Install 4 workflows:<br/>propose, explore, apply, archive]
CoreProfile -->|extended| InstallExtended[Install 11 workflows:<br/>all existing + propose]
CoreProfile -->|custom| InstallCustom[Install user-selected<br/>workflows from config]
InstallCore --> CheckDelivery{Delivery?}
InstallExtended --> CheckDelivery
InstallCustom --> CheckDelivery
CheckDelivery -->|both| GenBoth[Generate skills<br/>and commands]
CheckDelivery -->|skills| GenSkills[Generate<br/>skills only]
CheckDelivery -->|commands| GenCommands[Generate<br/>commands only]
GenBoth --> Success["`✓ Done<br/>Run /opsx:propose 'your idea'`"]
GenSkills --> Success
GenCommands --> Success
Last reviewed commit: b365792 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🧹 Nitpick comments (6)
openspec/changes/simplify-skill-installation/tasks.md (2)
39-42: No rationale for separatingavailable-tools.tsfromtool-detection.ts.Task 5.1 creates a new module rather than extending the existing one, but neither the task nor the design document explains the boundary. Both modules deal with tool identity and detection. Without a stated rationale (e.g., "tool-detection.ts is about installed/configured tools; available-tools.ts is about directory-scanned tools"), maintainers have no guidance on which file to add future tool-related functionality to.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/tasks.md` around lines 39 - 42, The review calls out missing rationale for creating src/core/available-tools.ts instead of extending tool-detection.ts; update the design and task text to state the clear responsibility boundary: specify that tool-detection.ts remains responsible for runtime/installed/configured tool identity and resolution, while available-tools.ts implements filesystem scanning (getAvailableTools(projectPath)) to discover directory-backed tools and maps directory names using AI_TOOLS; modify task 5.1 description to include this boundary and mention getAvailableTools and AI_TOOLS so future maintainers know which module to extend for scanning vs configuration logic, and add a short note in the design document explaining the separation.
83-88: E2E test plan omits the uninstall path.Task 10.3 covers
init → propose → apply → archivebut notprofile install/profile uninstall. Given thatprofile uninstallimmediately deletes files via SKILL_NAMES/COMMAND_IDS lookups — arguably the riskiest new operation in this PR — an explicit e2e test scenario (e.g.,profile install <workflow> → verify files → profile uninstall <workflow> → verify deletion) would provide meaningful coverage.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/tasks.md` around lines 83 - 88, Add an explicit e2e test for the uninstall path: extend task 10.3 (the end-to-end flow) to include running `profile install <workflow>` then verifying installed files exist, and then running `profile uninstall <workflow>` and verifying those files are deleted; ensure the test specifically targets the code paths that use SKILL_NAMES and COMMAND_IDS lookups (the risky immediate-delete logic) and include assertions for both successful install and safe/unexpected-file handling after uninstall (run on Windows/CI as part of 10.2/10.1).openspec/changes/simplify-skill-installation/specs/command-generation/spec.md (1)
28-33: Propose command file path only specified for Claude Code.Other tool adapters (Cursor, Windsurf, etc.) have no equivalent scenario for the
proposecommand file path. If their path conventions are handled in per-adapter specs, this is fine — otherwise those scenarios need a home before implementation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/command-generation/spec.md` around lines 28 - 33, The spec only defines the propose command path for Claude Code (`.claude/commands/opsx/propose.md`) while other adapters (Cursor, Windsurf, etc.) are missing equivalent scenarios; update the spec by either adding corresponding "Propose command file path" scenarios for each adapter (e.g., Cursor and Windsurf) that assert their expected file paths or add a clarifying note referencing the per-adapter spec files where those paths are defined (ensure you reference the "propose" requirement and the adapter names `Cursor` and `Windsurf` so implementers know whether to implement adapter-specific propose paths or rely on per-adapter specs).openspec/changes/simplify-skill-installation/specs/user-config/spec.md (1)
36-39: Specify the format for indicating defaults vs explicitly set values.The requirement says "SHALL indicate which values are defaults vs explicitly set" but does not define the format. Without this, implementations diverge — common options include a
(default)suffix, an asterisk, or a distinct column. Adding a concrete example would close the ambiguity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/user-config/spec.md` around lines 36 - 39, Update the "Scenario: List all config with profile" for the `openspec config list` command to define a concrete format for indicating defaults vs explicitly set values (e.g., append " (default)" to values that are defaults or add a "Source" column with values "default" or "explicit"); include a short example output showing profile, delivery, and workflows settings with the chosen marker so implementers have an exact template to follow.openspec/changes/simplify-skill-installation/proposal.md (1)
97-111: No explicit command to switch to thecustomprofile.The CLI commands section shows
profile set coreandprofile set extendedbut has noprofile set custom. Currently, reaching the custom profile requiresinstall/uninstallcalls that implicitly transition the profile. Adding an explicit command would improve discoverability and make the profile system feel complete.openspec profile set core openspec profile set extended +openspec profile set custom # transition to custom, keeping current workflows🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/proposal.md` around lines 97 - 111, Add an explicit "profile set custom" command to the CLI docs and example block so users can directly switch to the custom profile instead of relying on implicit install/uninstall transitions; update the examples in the Profile management section to include "openspec profile set custom" and, if the CLI implementation uses a handler like profile set (or a ProfileService method), ensure the command maps to the same activation logic used by "install"/"uninstall" so switching to custom behaves identically to the implicit transitions.openspec/changes/simplify-skill-installation/specs/cli-init/spec.md (1)
89-91: "Refresh/update the core workflows" is ambiguous — clarify whether existing files are overwritten.The spec doesn't define whether "refresh/update" means:
- Re-generate files unconditionally (overwriting user-modified skill content), or
- Add only missing workflow files, leaving existing ones intact.
Option 1 silently discards user customizations. The spec should make the behavior explicit to prevent divergent — and potentially destructive — implementations.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md` around lines 89 - 91, The spec's "refresh/update the core workflows" for the openspec init behavior is ambiguous about whether existing workflow files are overwritten; update the spec text for the scenario where a user with an extended profile runs "openspec init" with the core profile to explicitly state the intended behavior (e.g., "re-generate and overwrite core workflow files, replacing existing files" OR "only add missing core workflow files and leave existing files untouched"), and also add the expected handling for user-modified files (e.g., create backups, prompt, or skip) so implementations of openspec init, core profile refresh logic, and extended profile preservation are unambiguous.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Line 7: The markdown has four fenced code blocks without language specifiers
(causing MD040); update each fenced block by adding an appropriate language
hint: add ```text for the general output/commands blocks (the blocks containing
"..." and "$ openspec init" and "I'll create a change with 3 artifacts: ...")
and use ```shell for the shell/example block that starts with "# Profile
management (what to install)". Ensure each opening fence is updated to include
the language token while keeping the block contents unchanged.
- Around line 139-152: The impact section missed updating the COMMAND_IDS
constant to include the new "propose" command id; update the COMMAND_IDS list to
include the same "propose" identifier you added to SKILL_NAMES so profile
cleanup (openspec init --apply-profile) will remove stale propose command files,
and ensure any tests or cleanup logic that iterates COMMAND_IDS (e.g., the
safe-deletion routine) recognizes the new propose entry.
In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md`:
- Around line 65-67: The spec's hardcoded success message "/opsx:propose \"your
idea\"" is tool-specific; update the code that emits the "Init success message"
(the place that currently returns the literal "/opsx:propose \"your idea\"") to
produce a tool-agnostic or tool-aware message: either replace the hardcoded
string with a generic instruction like "Start your first change: propose your
idea using your installed tool" or detect the selected adapter and format the
example invocation accordingly (e.g., choose the appropriate slash/CLI syntax
per detected tool). Locate where the init success string is composed (the
function or template referenced by "Init success message") and change the
returned text to use a generic phrasing or branch on the configured tool to
render the correct invocation.
In `@openspec/changes/simplify-skill-installation/specs/delivery-config/spec.md`:
- Around line 28-30: Update the "Scenario: Get delivery preference" for the
`config get delivery` command to explicitly state the expected output when the
delivery field is absent in the config: specify whether the command should print
the effective value "both" (i.e., the default) or the value plus an annotation
like "(default: both, not explicitly set)"; mention the exact expected string to
avoid ambiguity so implementations of `config get delivery` and the scenario
text (Scenario: Get delivery preference) are aligned.
- Line 10: Update the two section headings "Skills only delivery" and "Commands
only delivery" to use compound-adjective hyphenation: change them to
"Skills-only delivery" and "Commands-only delivery" respectively (locate the
headings in the spec where those exact phrases appear and replace them).
In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md`:
- Around line 26-42: Add a new explicit scenario (or a clear NOTE) describing
the implicit one-way switch to the `custom` profile that occurs when running
`profile install <workflow>` or `profile uninstall <workflow>`; explain that
these commands will set the profile to `custom` if it was `core` or `extended`,
that this is irreversible via those commands alone, and include the recovery
method (e.g., run `profile set core` or `profile set <named>` to return to a
named profile). Reference the `profile install` and `profile uninstall`
behaviors and the fact that the change affects the global `workflows` config so
readers understand the impact.
- Around line 21-24: The spec currently omits filesystem side-effect behavior
for the "profile set" command; add two explicit scenarios to clarify intent: (1)
"profile set" (without --apply-profile) must only update the global config
profile setting and output confirmation, with no filesystem mutations, and (2)
"profile set --apply-profile" must update the global config profile setting,
output confirmation, and immediately mutate the filesystem by removing or
installing workflow files not part of the new profile using SKILL_NAMES /
COMMAND_IDS lookups; reference the existing "profile set" scenario, the
--apply-profile flag (Task 8.6), and the SKILL_NAMES/COMMAND_IDS mechanism when
adding these two scenarios so implementors know exactly when to mutate the
filesystem.
- Line 28: Add an explicit error scenario for the "profile set <invalid-name>"
case: state that when "profile set" is invoked with an unrecognized/invalid
profile name (e.g., "profile set typo") the system SHALL return an error
response (non-zero exit/status) and SHALL NOT change the current profile (i.e.,
the profile remains unchanged and SHALL NOT be set to `custom`), and include an
assertion that an appropriate diagnostic message is returned; apply the same
addition to the corresponding duplicate location referenced (the other
occurrence).
- Around line 53-58: Add a new scenario under the "Requirement: Profile
defaults" section to cover existing global configs that lack the profile field:
create a "Scenario: Global config exists but profile field absent" (or similar)
that states WHEN a global config file exists but does not contain a `profile`
field THEN the system SHALL behave as if profile is `core`; update the spec text
adjacent to the existing "Scenario: No global config exists" so implementations
handling schema evolution (e.g., migrations or defaults) are explicitly tested
for missing fields as well as missing files.
In `@openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md`:
- Around line 6-9: The "Basic propose invocation" scenario (Scenario: Basic
propose invocation) is underspecified because it says "generate all artifacts
needed for implementation" without enumerating them; update that scenario to
either list the canonical artifacts (e.g., proposal.md, design.md, tasks.md) or
add a clear reference to the canonical list used elsewhere (the first-time user
guidance scenario) so the behavior is explicit and consistent with the
config.yaml rule; ensure the text in the Scenario: Basic propose invocation
entry mirrors the artifact enumeration used in the first-time user guidance
scenario.
- Around line 30-32: The equivalence mixes CLI and skill models; update the
Scenario text for clarity by stating whether /opsx:propose is a skill or a CLI
and aligning the referenced invocations accordingly — e.g., replace the line
with a sentence like: "THEN the result SHALL produce the same filesystem
artifacts as running the CLI command `openspec new change \"feature-name\"`
followed by invoking the skill `/opsx:ff feature-name`" or, if you intend both
as skills, change `openspec new change` to `/opsx:new change` so the statement
consistently references `/opsx:propose`, `/opsx:new`, and `/opsx:ff`.
In `@openspec/changes/simplify-skill-installation/specs/skill-generation/spec.md`:
- Around line 23-26: The phrase "in addition to existing templates" is
ambiguous; update the spec to reference the canonical list or enumerate
templates explicitly—replace or augment that line by referencing the SKILL_NAMES
constant (or the exact list it contains) so readers know which templates are
considered "existing templates" (e.g., mention "in addition to templates listed
in SKILL_NAMES" or enumerate the names from SKILL_NAMES directly in the
scenario).
- Around line 11-14: The Scenario "Skip skill generation when delivery is
commands-only" in specs/skill-generation/spec.md currently asserts "the system
SHALL only generate command files" which belongs to command-generation; remove
that sentence from this spec so the Scenario only asserts the skill system
behavior ("SHALL NOT generate any skill files"), and if needed add or move the
removed assertion to specs/command-generation/spec.md (or reference the
command-generation spec) so command-generation remains authoritative; update the
Scenario text to only describe skill-generation outcomes and ensure no
cross-spec conflict remains.
In
`@openspec/changes/simplify-skill-installation/specs/tool-auto-detection/spec.md`:
- Around line 36-38: Update the Scenario "Case sensitivity on different
platforms" to specify the explicit mechanism rather than just the outcome: state
that the system SHALL either rely on the OS filesystem via an existence check
(e.g., use fs.existsSync(path.join(projectRoot, tool.skillsDir)) so case
handling is delegated to the platform) or SHALL normalize directory names (e.g.,
convert names to lowercase before comparison) and pick which approach is
required; reference config.yaml rule by adding the chosen mechanism
(fs.existsSync/path.join/projectRoot/tool.skillsDir or normalizing to lowercase)
in the scenario text.
---
Nitpick comments:
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Around line 97-111: Add an explicit "profile set custom" command to the CLI
docs and example block so users can directly switch to the custom profile
instead of relying on implicit install/uninstall transitions; update the
examples in the Profile management section to include "openspec profile set
custom" and, if the CLI implementation uses a handler like profile set (or a
ProfileService method), ensure the command maps to the same activation logic
used by "install"/"uninstall" so switching to custom behaves identically to the
implicit transitions.
In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md`:
- Around line 89-91: The spec's "refresh/update the core workflows" for the
openspec init behavior is ambiguous about whether existing workflow files are
overwritten; update the spec text for the scenario where a user with an extended
profile runs "openspec init" with the core profile to explicitly state the
intended behavior (e.g., "re-generate and overwrite core workflow files,
replacing existing files" OR "only add missing core workflow files and leave
existing files untouched"), and also add the expected handling for user-modified
files (e.g., create backups, prompt, or skip) so implementations of openspec
init, core profile refresh logic, and extended profile preservation are
unambiguous.
In
`@openspec/changes/simplify-skill-installation/specs/command-generation/spec.md`:
- Around line 28-33: The spec only defines the propose command path for Claude
Code (`.claude/commands/opsx/propose.md`) while other adapters (Cursor,
Windsurf, etc.) are missing equivalent scenarios; update the spec by either
adding corresponding "Propose command file path" scenarios for each adapter
(e.g., Cursor and Windsurf) that assert their expected file paths or add a
clarifying note referencing the per-adapter spec files where those paths are
defined (ensure you reference the "propose" requirement and the adapter names
`Cursor` and `Windsurf` so implementers know whether to implement
adapter-specific propose paths or rely on per-adapter specs).
In `@openspec/changes/simplify-skill-installation/specs/user-config/spec.md`:
- Around line 36-39: Update the "Scenario: List all config with profile" for the
`openspec config list` command to define a concrete format for indicating
defaults vs explicitly set values (e.g., append " (default)" to values that are
defaults or add a "Source" column with values "default" or "explicit"); include
a short example output showing profile, delivery, and workflows settings with
the chosen marker so implementers have an exact template to follow.
In `@openspec/changes/simplify-skill-installation/tasks.md`:
- Around line 39-42: The review calls out missing rationale for creating
src/core/available-tools.ts instead of extending tool-detection.ts; update the
design and task text to state the clear responsibility boundary: specify that
tool-detection.ts remains responsible for runtime/installed/configured tool
identity and resolution, while available-tools.ts implements filesystem scanning
(getAvailableTools(projectPath)) to discover directory-backed tools and maps
directory names using AI_TOOLS; modify task 5.1 description to include this
boundary and mention getAvailableTools and AI_TOOLS so future maintainers know
which module to extend for scanning vs configuration logic, and add a short note
in the design document explaining the separation.
- Around line 83-88: Add an explicit e2e test for the uninstall path: extend
task 10.3 (the end-to-end flow) to include running `profile install <workflow>`
then verifying installed files exist, and then running `profile uninstall
<workflow>` and verifying those files are deleted; ensure the test specifically
targets the code paths that use SKILL_NAMES and COMMAND_IDS lookups (the risky
immediate-delete logic) and include assertions for both successful install and
safe/unexpected-file handling after uninstall (run on Windows/CI as part of
10.2/10.1).
openspec/changes/simplify-skill-installation/specs/cli-init/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/delivery-config/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/delivery-config/spec.md
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/skill-generation/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/skill-generation/spec.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
"Handle case variations appropriately" violates the config.yaml rule requiring explicit mechanisms.
The new config.yaml rule (line 19) reads: "Be explicit about mechanisms, not just outcomes (say HOW, not just WHAT)." This scenario says WHAT (handle case) but not HOW. For cross-platform path detection, the mechanism matters:
- Linux filesystems are case-sensitive;
.Claude/would not match. - macOS HFS+ / Windows NTFS are case-insensitive by default.
The spec should specify the actual mechanism — e.g., "the system SHALL use fs.existsSync(path.join(projectRoot, tool.skillsDir)) which delegates case handling to the OS filesystem" or "the system SHALL normalize directory names to lowercase before comparison."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@openspec/changes/simplify-skill-installation/specs/tool-auto-detection/spec.md`
around lines 36 - 38, Update the Scenario "Case sensitivity on different
platforms" to specify the explicit mechanism rather than just the outcome: state
that the system SHALL either rely on the OS filesystem via an existence check
(e.g., use fs.existsSync(path.join(projectRoot, tool.skillsDir)) so case
handling is delegated to the platform) or SHALL normalize directory names (e.g.,
convert names to lowercase before comparison) and pick which approach is
required; reference config.yaml rule by adding the chosen mechanism
(fs.existsSync/path.join/projectRoot/tool.skillsDir or normalizing to lowercase)
in the scenario text.
Issues fixed: - Clarify workflow count: extended = existing 10 + new propose = 11 - Rename spec: tool-auto-detection → available-tools (matches proposal) - Change "identical" to "functionally equivalent" in propose spec - Add profile change notification when install/uninstall changes profile - Specify edge case: uninstall workflow from current non-custom profile - Specify behavior when --apply-profile confirmation is declined - Fix section numbering in design.md (6, 6a, 6b, 8) - Add scaffolding verification tasks (verify .openspec.yaml exists) - Specify case sensitivity mechanism: use fs.existsSync, let OS handle it
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (2)
openspec/changes/simplify-skill-installation/specs/available-tools/spec.md (1)
36-40:fs.existsSync()alone doesn't confirm the path is a directory.
fs.existsSync('.cursor')returnstruefor a regular file named.cursortoo. Add anisDirectory()check — e.g.,fs.existsSync(p) && fs.statSync(p).isDirectory()— to avoid false-positive tool detection.📝 Suggested addition
- **THEN** the system SHALL use `fs.existsSync()` with exact directory names from AI_TOOLS +- **THEN** the system SHALL verify the matched path is a directory (not a file)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/available-tools/spec.md` around lines 36 - 40, The current check uses fs.existsSync() with entries from AI_TOOLS which can return true for files as well as directories; update the detection logic to verify the path is a directory by combining fs.existsSync(p) with a directory stat check (e.g., fs.statSync(p).isDirectory()) wherever the project inspects AI_TOOLS entries (the code referencing fs.existsSync, fs.statSync, and AI_TOOLS), so only actual directories are considered tools and false positives from regular files are avoided.openspec/changes/simplify-skill-installation/design.md (1)
155-162: Section 7 is absent from the Decisions numbering.The
## Decisionssection jumps from §6b directly to §8, skipping §7. Either a section was removed without renumbering, or §8 should be §7. Minor, but worth fixing to avoid confusion when cross-referencing by number.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/design.md` around lines 155 - 162, The Decisions numbering skips §7 (it jumps from §6b to §8); open the "## Decisions" section and renumber the "§8" heading labeled "8. Fix Multi-Select Keybindings" to "7. Fix Multi-Select Keybindings", and update any in-document cross-references or table-of-contents entries that mention §8/§7 so numbering is consistent (search for the literal "§8", "8. Fix Multi-Select Keybindings", and any TOC entries and change them to "§7"/"7. Fix Multi-Select Keybindings").
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/simplify-skill-installation/design.md`:
- Around line 113-118: Update the §6 behavior bullet for --apply-profile to
match the detailed spec: remove the word "only" and state that --apply-profile
syncs/removes extras from both SKILL_NAMES and COMMAND_IDS (i.e., it deletes
items referenced by SKILL_NAMES and COMMAND_IDS), so the summary aligns with §6b
and specs/cli-init/spec.md and implementors will also clean up command files
when running openspec init --apply-profile.
In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md`:
- Around line 88-91: The phrase "refresh/update the core workflows" in the
"Scenario: Existing extended installation" for the `openspec init` command is
ambiguous about overwrite semantics; update that THEN clause to explicitly state
the intended behavior — e.g., replace it with either "THEN the system SHALL
regenerate core workflow files, overwriting existing content" if destructive
overwrite is intended, or "THEN the system SHALL add any missing core workflow
files and leave existing files untouched" if non-destructive behavior is
intended — and ensure the chosen wording is used consistently in the scenario
and any related acceptance criteria.
In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md`:
- Around line 53-55: Update the "Scenario: List available profiles" for the
`openspec profile list` command to indicate the active profile is clearly marked
in the output; modify the THEN clause in that scenario to require the currently
active profile be annotated (for example "core (active)") alongside the workflow
counts so users can identify which profile is active without running `openspec
profile show`.
- Around line 26-33: Add an explicit error scenario for "profile install
<workflow>" when the workflow name is unknown: define that running "profile
install bogus-workflow" SHALL fail with a non-zero exit code, SHALL NOT change
the profile or modify the global config `workflows` array, and SHALL display a
clear error listing valid workflow names (or where to find them); update the
spec to include this negative test case alongside the existing positive "Install
individual workflow" scenario so implementations of the "profile install"
command (and any validation in installWorkflow / profileInstall handlers) must
validate the workflow name and return the specified error behavior.
In `@openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md`:
- Around line 11-13: The scenario "Propose with existing change name" invoked
via the /opsx:propose command lacks defined behavior for the two choices and
non-interactive runs; update the spec to add explicit THEN clauses: for
"Continue" specify that /opsx:propose should detect existing change state
(complete vs incomplete) and either resume incomplete generation from the last
successful step using the existing change directory (reference the propose
workflow/resume logic) or, if all artifacts already exist, prompt to regenerate
artifacts or skip generation and proceed to review; for "Create new" specify
whether a new name is auto-suffixed (e.g., append a unique timestamp/sequence)
or the user is prompted for a new name and ensure the command returns the chosen
name to the workflow (reference /opsx:propose name handling); and for
non-interactive mode specify a deterministic fallback (auto-suffix new name or
fail with a clear error code) so automated callers have predictable behavior.
In `@openspec/changes/simplify-skill-installation/tasks.md`:
- Line 65: Task 8.1 references detectInstalledTools() but the implemented
function is getAvailableTools(projectPath); reconcile them by either renaming
getAvailableTools to detectInstalledTools (preserving its signature) or by
adding and exporting a small wrapper function detectInstalledTools(projectPath)
that calls getAvailableTools(projectPath) and documents their relationship; then
update the task text so the name used in the init step matches the exported
symbol (either detectInstalledTools or getAvailableTools) to remove the
mismatch.
- Around line 44-52: Add the missing "propose" command id to the COMMAND_IDS
constant (the same enum/array used by the safe-deletion check) so the new
openspec-propose skill and its command template ("propose") are recognized
during profile cleanup; update the COMMAND_IDS definition to include "propose"
alongside existing entries, ensuring the string matches the command template id
and the SKILL_NAMES entry "openspec-propose".
---
Duplicate comments:
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Around line 139-152: The proposal adds "propose" to SKILL_NAMES but omitted
the matching entry in COMMAND_IDS; update the COMMAND_IDS constant to include a
mapping for "propose" (the same identifier used in SKILL_NAMES) so that safe
deletion and command lookups work consistently—locate the COMMAND_IDS definition
and add the propose key with the appropriate command id string used elsewhere
(matching how other skills are mapped).
- Around line 7-17: The fenced code blocks that show the shell interaction (the
block starting with "0:00 $ openspec init" and the other blocks containing
"/opsx:propose", agent output, and "/opsx:apply") lack language specifiers and
trigger MD040; update each triple-backtick fence to include an appropriate
language (e.g., ```bash or ```sh for shell/session blocks, or ```text if you
prefer plain text) so markdownlint no longer flags them—locate the fences around
the snippets like "0:00 $ openspec init", the "/opsx:propose ..." interaction,
the agent-created files list, and the "/opsx:apply" block and add the language
tag to each opening ``` fence.
In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md`:
- Around line 65-67: In the "Scenario: Init success message" replace the
hardcoded Claude Code invocation string "Start your first change: /opsx:propose
\"your idea\"" with a tool-agnostic or conditional message: either a generic
prompt such as "Start your first change: propose \"your idea\"" or generate the
displayed example dynamically based on detected tool(s) (e.g., map detected tool
names to their invocation syntax and render the appropriate example). Update the
spec text where that exact string appears so consumers no longer see the
Claude-specific "/opsx:propose" unless the implementation explicitly detects and
chooses that tool's syntax.
In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md`:
- Around line 26-44: The spec's "Install individual workflow" and "Uninstall
individual workflow" scenarios implicitly change profile to `custom` without
documenting recovery; add a short dedicated scenario or NOTE after both
scenarios that (1) explicitly states this is a one-way automatic switch unless
the user manually resets the profile, (2) documents the recovery command (e.g.,
`openspec profile set core`) and any prerequisites/validation for reverting, and
(3) clarifies whether reverting will remove or preserve workflows added/removed
while in `custom` so implementers know expected behavior for
SKILL_NAMES/COMMAND_IDS handling.
- Around line 62-67: Add a new parallel scenario under the "Requirement: Profile
defaults" section to cover schema-evolution: when a global config file exists
but lacks a `profile` key, the system SHALL behave as if profile is `core`;
specifically, mirror the existing "Scenario: No global config exists" structure
with a new scenario (e.g., "Scenario: Global config exists but profile field
absent") that states WHEN the global config file exists and has no `profile`
field THEN the system SHALL default to `core`, referencing task 1.4/schema
evolution for context.
- Around line 21-25: The spec currently omits whether "openspec profile set
<name>" mutates filesystem artifacts and lacks an error scenario for invalid
names; update the "Set profile" scenarios to (1) explicitly state that "openspec
profile set <name>" only updates the global config profile setting (no
install/remove of workflow files or other FS side-effects) and emits a
confirmation message, and (2) add a new negative scenario for "openspec profile
set <invalid-name>" that defines expected behavior: validate names, print a
clear error message, and exit with a non-zero status code; reference the
"openspec profile set <name>" and "profile set <invalid-name>" commands and the
global config profile setting in the spec text so implementers know to enforce
config-only changes and proper validation/exit semantics.
In `@openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md`:
- Around line 30-32: Clarify the ambiguous equivalence statement: explicitly
state whether `propose` is a CLI command or an AI skill (slash command), and
define what "equivalent" means (e.g., produces the same filesystem artifacts and
metadata as running `openspec new change "feature-name"` and then invoking the
`/opsx:ff feature-name` skill, or simply yields the same end-state behavior via
different invocation paths). Update the Scenario text to name the invocation
method for `propose` (CLI or skill) and add a short parenthetical defining
equivalence as either "artifact-equivalent" or "invocation-equivalent" so
readers know whether you mean identical files/outputs or equivalent operational
outcome.
- Around line 6-9: Update the "Basic propose invocation" scenario so the vague
THEN "the system SHALL generate all artifacts needed for implementation" is
replaced with an explicit list of artifacts (e.g., proposal.md, design.md,
tasks.md) to match the first-time user guidance; modify the Scenario: Basic
propose invocation block (the WHEN `/opsx:propose "add user authentication"` and
the corresponding THEN line) to enumerate those filenames instead of the generic
phrase.
---
Nitpick comments:
In `@openspec/changes/simplify-skill-installation/design.md`:
- Around line 155-162: The Decisions numbering skips §7 (it jumps from §6b to
§8); open the "## Decisions" section and renumber the "§8" heading labeled "8.
Fix Multi-Select Keybindings" to "7. Fix Multi-Select Keybindings", and update
any in-document cross-references or table-of-contents entries that mention §8/§7
so numbering is consistent (search for the literal "§8", "8. Fix Multi-Select
Keybindings", and any TOC entries and change them to "§7"/"7. Fix Multi-Select
Keybindings").
In `@openspec/changes/simplify-skill-installation/specs/available-tools/spec.md`:
- Around line 36-40: The current check uses fs.existsSync() with entries from
AI_TOOLS which can return true for files as well as directories; update the
detection logic to verify the path is a directory by combining fs.existsSync(p)
with a directory stat check (e.g., fs.statSync(p).isDirectory()) wherever the
project inspects AI_TOOLS entries (the code referencing fs.existsSync,
fs.statSync, and AI_TOOLS), so only actual directories are considered tools and
false positives from regular files are avoided.
openspec/changes/simplify-skill-installation/specs/cli-init/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/profiles/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/profiles/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md
Show resolved
Hide resolved
- Add language specifiers to fenced code blocks in proposal.md - Add COMMAND_IDS update for propose in modified files list - Make init success message tool-aware (colon vs hyphen syntax) - Fix grammar: "Skills-only" and "Commands-only" in delivery-config - Specify config get delivery output when field absent: "both (default)" - Add profile set scenarios: config-only vs --apply-profile with filesystem mutation - Add error scenarios for invalid profile name and unknown workflow - Add scenario for existing config without profile field - Mark active profile in profile list output - Enumerate artifacts in propose basic scenario - Fix propose equivalence to use skill syntax consistently - Specify continue/create new branches in propose - Remove out-of-scope command assertion from skill-generation spec - Reference SKILL_NAMES constant instead of vague "existing templates" - Fix design.md: SKILL_NAMES AND COMMAND_IDS (not "only") - Specify overwrite semantics for refresh/update - Add task 6.8: propose to COMMAND_IDS - Fix function name: getAvailableTools() not detectInstalledTools()
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/simplify-skill-installation/design.md`:
- Line 156: The heading "### 8. Fix Multi-Select Keybindings" jumps from §6b and
leaves §7 missing; update the decision numbering so it is sequential by either
renaming the heading text "### 8. Fix Multi-Select Keybindings" to "### 7. Fix
Multi-Select Keybindings" or re-inserting the removed §7 content (or a brief
placeholder note) before this heading to preserve history; ensure any other
subsequent numbered headings are adjusted consistently so there are no gaps in
the decision log.
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Around line 68-81: The UX text for the new propose workflow is inconsistent
about which artifacts it creates; update the /opsx:propose description and the
"Why" timeline so they match intent: either include specs/ in the list and
change "3 artifacts" to "4 artifacts" (update the UX message that currently
lists proposal.md, design.md, tasks.md to also list specs/) if propose indeed
runs both new + ff, or explicitly remove "all artifacts" and change the UX
message to state that propose creates only proposal.md, design.md, tasks.md and
that specs/ (delta specs) are generated later by /opsx:apply; ensure references
to the propose workflow and /opsx:apply remain consistent across the proposal.md
content.
In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md`:
- Around line 27-32: The "Set profile with apply" scenario's install step ("the
system SHALL install any missing workflow files for the new profile") lacks a
tool-detection clause; add a pre-install step mirroring the "profile install"
scenario by explicitly stating the system SHALL detect all configured tools in
the current project (so the install targets the same set as SKILL_NAMES and
COMMAND_IDS lookups), and clarify that only workflow files for those detected
tools will be generated/installed when performing the apply-profile install
step.
In `@openspec/changes/simplify-skill-installation/specs/skill-generation/spec.md`:
- Around line 22-32: The requirement text is self-contradictory about where the
openspec-propose template lives; update the Scenario "Propose skill in
templates" so it describes the post-change behavior that the `openspec-propose`
template is returned via the unified SKILL_NAMES lookup (not "in addition to"
SKILL_NAMES), and remove any phrasing that implies a separate fetch path; ensure
the Requirement and Scenario consistently state that `SKILL_NAMES` includes
`openspec-propose`.
---
Duplicate comments:
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Line 7: The fenced code blocks in simplify-skill-installation proposal.md
currently lack language tokens; update every triple-backtick fence (```) to
include the appropriate language specifier (e.g., ```text or ```shell) so each
of the code blocks (the four blocks referenced in the review) carry correct
language tokens and are consistent across the document; ensure you change each
opening fence only and keep the fence content unchanged.
| The `propose` workflow is new - it combines `new` + `ff` into a single command that creates a change and generates all artifacts. | ||
|
|
||
| ### 5. Improved Propose UX | ||
|
|
||
| `/opsx:propose` should naturally onboard users by explaining what it's doing: | ||
|
|
||
| ```text | ||
| I'll create a change with 3 artifacts: | ||
| - proposal.md (what & why) | ||
| - design.md (how) | ||
| - tasks.md (implementation steps) | ||
|
|
||
| When ready to implement, run /opsx:apply | ||
| ``` |
There was a problem hiding this comment.
Artifact count inconsistency: "all artifacts" vs "3 artifacts".
Line 68 states that propose "generates all artifacts", but the UX message at line 75 claims only 3 and omits specs/. Since propose = new + ff, and ff is the workflow that generates delta specs, specs/ should be a fourth artifact. The same omission appears in the "Why" timeline at line 13.
Either clarify that propose intentionally defers specs/ generation to /opsx:apply (and remove "all artifacts"), or add specs/ to both the count and the list.
✏️ Option A — if `propose` does generate specs
-I'll create a change with 3 artifacts:
+I'll create a change with 4 artifacts:
- proposal.md (what & why)
- design.md (how)
+- specs/ (delta specs)
- tasks.md (implementation steps)-0:45 Agent creates proposal.md, design.md, tasks.md
+0:45 Agent creates proposal.md, design.md, specs/, tasks.md✏️ Option B — if specs/ is deferred to apply
-it combines `new` + `ff` into a single command that creates a change and generates all artifacts.
+it combines `new` + `ff` into a single command that creates a change and generates the planning artifacts (proposal.md, design.md, tasks.md); delta specs are produced during `/opsx:apply`.📝 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.
| The `propose` workflow is new - it combines `new` + `ff` into a single command that creates a change and generates all artifacts. | |
| ### 5. Improved Propose UX | |
| `/opsx:propose` should naturally onboard users by explaining what it's doing: | |
| ```text | |
| I'll create a change with 3 artifacts: | |
| - proposal.md (what & why) | |
| - design.md (how) | |
| - tasks.md (implementation steps) | |
| When ready to implement, run /opsx:apply | |
| ``` | |
| The `propose` workflow is new - it combines `new` + `ff` into a single command that creates a change and generates all artifacts. | |
| ### 5. Improved Propose UX | |
| `/opsx:propose` should naturally onboard users by explaining what it's doing: | |
| The `propose` workflow is new - it combines `new` + `ff` into a single command that creates a change and generates all artifacts. | |
| ### 5. Improved Propose UX | |
| `/opsx:propose` should naturally onboard users by explaining what it's doing: | |
| ```text | |
| I'll create a change with 3 artifacts: | |
| - proposal.md (what & why) | |
| - design.md (how) | |
| - tasks.md (implementation steps) | |
| When ready to implement, run /opsx:apply | |
| ``` | |
| The `propose` workflow is new - it combines `new` + `ff` into a single command that creates a change and generates the planning artifacts (proposal.md, design.md, tasks.md); delta specs are produced during `/opsx:apply`. | |
| ### 5. Improved Propose UX | |
| `/opsx:propose` should naturally onboard users by explaining what it's doing: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/simplify-skill-installation/proposal.md` around lines 68 -
81, The UX text for the new propose workflow is inconsistent about which
artifacts it creates; update the /opsx:propose description and the "Why"
timeline so they match intent: either include specs/ in the list and change "3
artifacts" to "4 artifacts" (update the UX message that currently lists
proposal.md, design.md, tasks.md to also list specs/) if propose indeed runs
both new + ff, or explicitly remove "all artifacts" and change the UX message to
state that propose creates only proposal.md, design.md, tasks.md and that specs/
(delta specs) are generated later by /opsx:apply; ensure references to the
propose workflow and /opsx:apply remain consistent across the proposal.md
content.
There was a problem hiding this comment.
--apply-profile install step (line 31) has no tool-detection clause.
Line 31 specifies that missing workflow files shall be installed, but unlike the profile install scenario (which explicitly requires "detect all configured tools in current project" at line 44), there is no equivalent step here. An implementor has no guidance on which tools to target when generating those files — leading to inconsistent behavior or a best-guess implementation.
✏️ Proposed addition
#### Scenario: Set profile with apply
- **WHEN** user runs `openspec profile set <name> --apply-profile`
- **THEN** the system SHALL update the global config profile setting
- **THEN** the system SHALL remove workflow files not in new profile (via SKILL_NAMES and COMMAND_IDS lookups)
- **THEN** the system SHALL ask for confirmation before removing files
+- **THEN** the system SHALL detect all configured tools in current project
- **THEN** the system SHALL install any missing workflow files for the new profile🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md` around
lines 27 - 32, The "Set profile with apply" scenario's install step ("the system
SHALL install any missing workflow files for the new profile") lacks a
tool-detection clause; add a pre-install step mirroring the "profile install"
scenario by explicitly stating the system SHALL detect all configured tools in
the current project (so the install targets the same set as SKILL_NAMES and
COMMAND_IDS lookups), and clarify that only workflow files for those detected
tools will be generated/installed when performing the apply-profile install
step.
| #### Scenario: Propose skill in templates | ||
| - **WHEN** getting skill templates | ||
| - **THEN** the system SHALL include `openspec-propose` template | ||
| - **THEN** the template SHALL be in addition to templates listed in SKILL_NAMES constant | ||
|
|
||
| ### Requirement: Skill names constant update | ||
| The `SKILL_NAMES` constant SHALL include the propose workflow. | ||
|
|
||
| #### Scenario: Updated skill names | ||
| - **WHEN** referencing `SKILL_NAMES` constant | ||
| - **THEN** it SHALL include `openspec-propose` in addition to existing names |
There was a problem hiding this comment.
Self-contradiction: openspec-propose cannot be "in addition to SKILL_NAMES" and also inside SKILL_NAMES simultaneously.
Line 25 implies openspec-propose lives outside SKILL_NAMES ("in addition to templates listed in SKILL_NAMES constant"), while lines 27–32 specify that SKILL_NAMES SHALL include openspec-propose. An implementor reading line 25 in isolation could infer a separate, parallel fetch path for the propose template rather than the unified SKILL_NAMES lookup the next requirement mandates.
Since Requirement at lines 27–32 establishes openspec-propose as part of SKILL_NAMES, line 25 should describe the post-change state:
✏️ Proposed fix
#### Scenario: Propose skill in templates
- **WHEN** getting skill templates
- **THEN** the system SHALL include `openspec-propose` template
-- **THEN** the template SHALL be in addition to templates listed in SKILL_NAMES constant
+- **THEN** the template SHALL be retrievable via the SKILL_NAMES constant🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/simplify-skill-installation/specs/skill-generation/spec.md`
around lines 22 - 32, The requirement text is self-contradictory about where the
openspec-propose template lives; update the Scenario "Propose skill in
templates" so it describes the post-change behavior that the `openspec-propose`
template is returned via the unified SKILL_NAMES lookup (not "in addition to"
SKILL_NAMES), and remove any phrasing that implies a separate fetch path; ensure
the Requirement and Scenario consistently state that `SKILL_NAMES` includes
`openspec-propose`.
|
@1code review again |
|
Task completed. Sure — here's a quick summary of the 6 issues and 4 nits: Issues
Nits
Powered by 1Code |
- Update design to use existing CLAUDE.md mechanisms - Add cli-update spec for managing skill updates - Clarify profile system and user config interactions - Add explorations directory with design notes - Update docs with clearer concepts
Clarify that init auto-detects tools and asks for confirmation, rather than being completely question-free. Update examples to show the tool confirmation UI.
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
openspec/specs/openspec-conventions/spec.md (1)
39-497:⚠️ Potential issue | 🟡 MinorPre-existing: file self-violates its own
Validating header uniquenessconstraint (7 duplicate pairs).The
## Requirementssection (lines 6–247) and the thematic sections below (lines 248–497) contain identical### Requirement:headers for every shared requirement:
Header First occurrence Duplicate Project StructureLine 39 Line 258 Structured Format for Behavioral SpecsLine 65 Line 288 Header-Based Requirement IdentificationLine 94 Line 319 Change Storage ConventionLine 123 Line 348 Archive Process EnhancementLine 166 Line 391 Proposal FormatLine 189 Line 414 Change ReviewLine 208 Line 447 Per lines 117–121 of this same spec, validation tools SHALL flag duplicate headers as errors, and the archive command relies on normalized header matching (lines 170–179) to apply delta changes — duplicates would cause double-application or ambiguous resolution. The two new requirements added by this PR do not introduce new duplicates, but the structural issue will affect any tooling that processes this file.
This appears to be caused by the file having two organizational layers (a flat
## Requirementsindex followed by thematic sub-sections) rather than one. Consider collapsing to a single authoritative location per requirement, or explicitly designating the thematic sections as non-normative prose.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/specs/openspec-conventions/spec.md` around lines 39 - 497, The spec currently duplicates seven `### Requirement:` headers (Project Structure; Structured Format for Behavioral Specs; Header-Based Requirement Identification; Change Storage Convention; Archive Process Enhancement; Proposal Format; Change Review), violating the file's own "Validating header uniqueness" rule; collapse or remove the duplicate set by keeping one authoritative requirement entry per named header (e.g., retain the first canonical `### Requirement: Project Structure` and remove or merge the later `### Requirement: Project Structure` duplicate), or mark the thematic second set explicitly as non-normative prose (e.g., convert those `### Requirement:` headings to plain subheadings) so programmatic matching uses a single normalized header per requirement; ensure any moved content is merged under the retained header and run the header-uniqueness validator to confirm no duplicates remain.
🧹 Nitpick comments (5)
openspec/specs/openspec-conventions/spec.md (2)
16-38: Minor: missing blank line between### Requirement:header and SHALL statement.The majority of requirements in this file (e.g., lines 7–9, 65–67, 94–96) have a blank line separating the
### Requirement:heading from the opening SHALL statement. The two new requirements at lines 16–17 and 28–29 omit this blank line, creating a visual inconsistency. (There is one pre-existing exception at line 230–231, but the dominant pattern includes the blank line.)✏️ Proposed fix
-### Requirement: Behavior-First Specification Boundary -OpenSpec specifications SHALL capture verifiable behavior contracts and avoid internal implementation detail. +### Requirement: Behavior-First Specification Boundary + +OpenSpec specifications SHALL capture verifiable behavior contracts and avoid internal implementation detail.-### Requirement: Progressive Rigor -OpenSpec conventions SHALL keep specs lightweight by default and scale rigor only when risk or coordination complexity demands it. +### Requirement: Progressive Rigor + +OpenSpec conventions SHALL keep specs lightweight by default and scale rigor only when risk or coordination complexity demands it.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/specs/openspec-conventions/spec.md` around lines 16 - 38, The two new requirement blocks titled "Requirement: Behavior-First Specification Boundary" and "Requirement: Progressive Rigor" are missing the blank line between the `### Requirement:` header and the opening SHALL sentence; update spec.md by inserting a single blank line immediately after each of those `### Requirement:` headers so they match the existing pattern (e.g., the blocks for "Requirement: Behavior-First Specification Boundary" and "Requirement: Progressive Rigor" should have a newline before the first SHALL statement).
35-37: "Proportionally" is undefined — consider anchoring it with at least one concrete example.The THEN clause
authors increase detail and explicit validation expectations proportionallyis open to interpretation. Without at least one example of what "increased rigor" looks like (e.g., requiring an explicit rollback plan, adding an ADR, mandating explicit sign-off steps intasks.md), the requirement is not verifiable, which conflicts with the Behavior-First principle being introduced by the sibling requirement at lines 19–22.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/specs/openspec-conventions/spec.md` around lines 35 - 37, The THEN clause in "Scenario: High-risk or cross-boundary change specification" is vague because "proportionally" is undefined; update the clause to list concrete, verifiable requirements (e.g., require an explicit rollback plan, a new or updated ADR, a migration plan with verification steps, a testing matrix, and documented explicit sign-offs in tasks.md) and/or add a bulleted example list showing specific escalation levels (e.g., cross-team: add sign-off; API-breaking: add ADR + rollback plan; security-sensitive: add threat model + security review). Ensure you edit the heading "Scenario: High-risk or cross-boundary change specification" and replace or augment the THEN line `authors increase detail and explicit validation expectations proportionally` with these concrete examples so reviewers can verify compliance.openspec/changes/simplify-skill-installation/specs/cli-init/spec.md (1)
86-89: No output notification specified before overwriting customized workflow files.The overwrite intent is now explicit (good), but the spec doesn't require any message indicating which files are being overwritten. A user who has customized a workflow file (e.g.,
explore.md) will lose those edits silently. Adding a "Overwriting: explore, apply, ..." line to the output — without requiring a confirmation prompt — would at least make the side-effect visible.✏️ Optional addition
#### Scenario: Existing custom installation - **WHEN** user has custom profile with extra workflows and runs `openspec init` with core profile - **THEN** the system SHALL NOT remove extra workflows +- **THEN** the system SHALL display: "Overwriting: <list of core workflow files being regenerated>" - **THEN** the system SHALL regenerate core workflow files, overwriting existing content with latest templates🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md` around lines 86 - 89, Update the "Scenario: Existing custom installation" behavior to require a non-interactive notification before overwriting core workflow files: when running `openspec init` with core profile and core workflow files will be regenerated (e.g., explore.md, apply.md), the spec must add a THEN clause that the CLI outputs a line like "Overwriting: explore.md, apply.md, ..." listing the files to be overwritten (no confirmation prompt required), and ensure this notification appears immediately prior to the overwrite action so users see which customized files will be replaced.openspec/changes/simplify-skill-installation/specs/user-config/spec.md (1)
15-18: Consider specifying behavior whencustomprofile has an empty or absentworkflowsarray.As written,
profile: "custom"with noworkflowsfield silently produces a zero-workflow installation. A user who accidentally ends up in this state (e.g., after uninstalling all workflows) gets no feedback. Adding a warning case would make the behavior explicit.✏️ Optional addition
+#### Scenario: Custom profile with empty workflows +- **WHEN** config contains `profile: "custom"` and `workflows` is an empty array (or absent) +- **THEN** the system SHALL display a warning: "No workflows configured. Run `openspec config profile` to select workflows." +- **AND** the system SHALL NOT generate any skill or command files🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/user-config/spec.md` around lines 15 - 18, The spec currently treats profile: "custom" with a missing or empty workflows array as silently resulting in zero workflows; update the behavior so that when profile: "custom" and the "workflows" field is absent or an empty array the system still treats it as [] but emits a clear warning/notice to the user (or installer log) indicating no workflows are enabled and suggesting next steps (e.g., how to add workflows); locate the code that checks for profile: "custom" and reads the "workflows" array and add the warning branch for workflows === undefined || workflows.length === 0, leaving the empty-array semantics intact.openspec/changes/simplify-skill-installation/specs/profiles/spec.md (1)
50-53: No failure path defined for auto-triggeredopenspec update.Lines 51-52 specify that when the user confirms, the system SHALL run
openspec updateautomatically — but there's no scenario covering what happens if that update fails. Without guidance, implementors will diverge on whether to roll back the global config change, leave the config updated and report the error, or something else.✏️ Optional addition
+#### Scenario: Auto-triggered update fails +- **WHEN** user confirms "Apply to this project now?" +- **AND** `openspec update` exits with a non-zero code +- **THEN** the system SHALL display the update error +- **THEN** the system SHALL preserve the global config change (do NOT roll back) +- **THEN** the system SHALL display: "Config saved. Fix the error above, then run `openspec update` manually."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md` around lines 50 - 53, Add an explicit failure path for the auto-triggered "openspec update" invoked after updating the global config: when the update command invoked by the confirmation prompt ("Apply to this project now? (y/n)" → run `openspec update`) fails, the implementation must (a) surface a clear error to the user including the underlying error message, (b) leave the global config in a consistent state by either rolling back the global config change or documenting that the config was changed but the project update failed, and (c) offer remediation options (retry `openspec update`, run it manually later, or rollback) in the user-facing message; update the spec text around the "WHEN user confirms" / "THEN the system SHALL run `openspec update` automatically" steps to state which of these behaviors is required and what user-facing messages/actions should be presented.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Around line 104-122: The fenced code block showing the interactive picker
example (the block that begins with "$ openspec config profile" and contains the
"Delivery: [skills] [commands] [both]" and workflow checklist) is missing a
language specifier; add a language tag (e.g., "text") to the opening fence so
the block becomes ```text and the content is treated as plain text for MD040
compliance.
In `@openspec/changes/simplify-skill-installation/specs/cli-update/spec.md`:
- Around line 36-42: The scenario "Delivery changed to skills-only" incorrectly
scopes deletion to "command files for workflows in the profile"; update the spec
for the "Delivery changed to skills-only" scenario (triggered by running
`openspec update` with global config `delivery: skills`) to require deletion of
all command files in the project (not just those belonging to profile
workflows), ensure the spec also clarifies that skill files are
generated/updated and the final message remains "Removed: <count> command files
(delivery: skills)"; reference the scenario title, the `openspec update` action,
the `delivery: skills` config, and the expected removal message when making the
change.
In `@openspec/explorations/workspace-architecture.md`:
- Around line 30-35: The "After (simplified)" snippet still lists the deprecated
`extended` preset (the line `openspec config profile extended # preset
shortcut`), which contradicts design.md §2 and profiles/spec.md that define only
`core` and `custom`; update that snippet to remove or replace the `extended`
entry so it reflects the final two-profile design (e.g., change to `openspec
config profile custom # preset shortcut` or remove the line entirely), and
verify the surrounding "What We've Decided" text no longer references
`extended`.
In `@openspec/specs/docs-agent-instructions/spec.md`:
- Line 58: Replace the unhyphenated compound modifier "security/privacy
sensitive work" with the hyphenated form "security/privacy-sensitive work" in
the markdown text (look for the line containing "**AND** reserve deeper, fuller
specification style for higher-risk changes (such as API breaks, migrations,
cross-team, or security/privacy sensitive work)"); ensure the hyphen is added so
the compound modifier correctly reads "security/privacy-sensitive work".
---
Outside diff comments:
In `@openspec/specs/openspec-conventions/spec.md`:
- Around line 39-497: The spec currently duplicates seven `### Requirement:`
headers (Project Structure; Structured Format for Behavioral Specs; Header-Based
Requirement Identification; Change Storage Convention; Archive Process
Enhancement; Proposal Format; Change Review), violating the file's own
"Validating header uniqueness" rule; collapse or remove the duplicate set by
keeping one authoritative requirement entry per named header (e.g., retain the
first canonical `### Requirement: Project Structure` and remove or merge the
later `### Requirement: Project Structure` duplicate), or mark the thematic
second set explicitly as non-normative prose (e.g., convert those `###
Requirement:` headings to plain subheadings) so programmatic matching uses a
single normalized header per requirement; ensure any moved content is merged
under the retained header and run the header-uniqueness validator to confirm no
duplicates remain.
---
Duplicate comments:
In `@openspec/changes/simplify-skill-installation/proposal.md`:
- Around line 67-80: The prose is inconsistent: the `propose` workflow text
claims it "generates all artifacts" but the UX message for `/opsx:propose` lists
only proposal.md, design.md, and tasks.md and defers specs/ to `/opsx:apply`;
decide which behavior is correct and make the copy consistent—either change the
claim to say `propose` generates the three artifacts (proposal.md, design.md,
tasks.md) and update the timeline to reflect specs/ are created by
`/opsx:apply`, or explicitly state that `propose` also generates specs/ (delta
specs) and update the UX message and timeline to include specs/ alongside
proposal.md, design.md, tasks.md; ensure the terms `/opsx:propose`,
`/opsx:apply`, `proposal.md`, `design.md`, `tasks.md`, and `specs/` are updated
consistently.
---
Nitpick comments:
In `@openspec/changes/simplify-skill-installation/specs/cli-init/spec.md`:
- Around line 86-89: Update the "Scenario: Existing custom installation"
behavior to require a non-interactive notification before overwriting core
workflow files: when running `openspec init` with core profile and core workflow
files will be regenerated (e.g., explore.md, apply.md), the spec must add a THEN
clause that the CLI outputs a line like "Overwriting: explore.md, apply.md, ..."
listing the files to be overwritten (no confirmation prompt required), and
ensure this notification appears immediately prior to the overwrite action so
users see which customized files will be replaced.
In `@openspec/changes/simplify-skill-installation/specs/profiles/spec.md`:
- Around line 50-53: Add an explicit failure path for the auto-triggered
"openspec update" invoked after updating the global config: when the update
command invoked by the confirmation prompt ("Apply to this project now? (y/n)" →
run `openspec update`) fails, the implementation must (a) surface a clear error
to the user including the underlying error message, (b) leave the global config
in a consistent state by either rolling back the global config change or
documenting that the config was changed but the project update failed, and (c)
offer remediation options (retry `openspec update`, run it manually later, or
rollback) in the user-facing message; update the spec text around the "WHEN user
confirms" / "THEN the system SHALL run `openspec update` automatically" steps to
state which of these behaviors is required and what user-facing messages/actions
should be presented.
In `@openspec/changes/simplify-skill-installation/specs/user-config/spec.md`:
- Around line 15-18: The spec currently treats profile: "custom" with a missing
or empty workflows array as silently resulting in zero workflows; update the
behavior so that when profile: "custom" and the "workflows" field is absent or
an empty array the system still treats it as [] but emits a clear warning/notice
to the user (or installer log) indicating no workflows are enabled and
suggesting next steps (e.g., how to add workflows); locate the code that checks
for profile: "custom" and reads the "workflows" array and add the warning branch
for workflows === undefined || workflows.length === 0, leaving the empty-array
semantics intact.
In `@openspec/specs/openspec-conventions/spec.md`:
- Around line 16-38: The two new requirement blocks titled "Requirement:
Behavior-First Specification Boundary" and "Requirement: Progressive Rigor" are
missing the blank line between the `### Requirement:` header and the opening
SHALL sentence; update spec.md by inserting a single blank line immediately
after each of those `### Requirement:` headers so they match the existing
pattern (e.g., the blocks for "Requirement: Behavior-First Specification
Boundary" and "Requirement: Progressive Rigor" should have a newline before the
first SHALL statement).
- Around line 35-37: The THEN clause in "Scenario: High-risk or cross-boundary
change specification" is vague because "proportionally" is undefined; update the
clause to list concrete, verifiable requirements (e.g., require an explicit
rollback plan, a new or updated ADR, a migration plan with verification steps, a
testing matrix, and documented explicit sign-offs in tasks.md) and/or add a
bulleted example list showing specific escalation levels (e.g., cross-team: add
sign-off; API-breaking: add ADR + rollback plan; security-sensitive: add threat
model + security review). Ensure you edit the heading "Scenario: High-risk or
cross-boundary change specification" and replace or augment the THEN line
`authors increase detail and explicit validation expectations proportionally`
with these concrete examples so reviewers can verify compliance.
| ``` | ||
| $ openspec config profile | ||
|
|
||
| Delivery: [skills] [commands] [both] | ||
| ^^^^^^ | ||
|
|
||
| Workflows: (space to toggle, enter to save) | ||
| [x] propose | ||
| [x] explore | ||
| [x] apply | ||
| [x] archive | ||
| [ ] new | ||
| [ ] ff | ||
| [ ] continue | ||
| [ ] verify | ||
| [ ] sync | ||
| [ ] bulk-archive | ||
| [ ] onboard | ||
| ``` |
There was a problem hiding this comment.
Fenced code block at line 104 is still missing a language specifier (MD040).
The interactive picker example block has no language tag despite the prior round of MD040 fixes (which addressed lines 7, 27, 74, and 97).
✏️ Suggested fix
-```
+```text
$ openspec config profile
Delivery: [skills] [commands] [both]
...🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 104-104: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/simplify-skill-installation/proposal.md` around lines 104 -
122, The fenced code block showing the interactive picker example (the block
that begins with "$ openspec config profile" and contains the "Delivery:
[skills] [commands] [both]" and workflow checklist) is missing a language
specifier; add a language tag (e.g., "text") to the opening fence so the block
becomes ```text and the content is treated as plain text for MD040 compliance.
There was a problem hiding this comment.
@TabishB, understood! This suggestion is coming from the markdownlint-cli2 static analysis tool that's checking the PR.
If you'd like to stop seeing MD040 warnings, you can configure markdownlint to ignore this rule by:
-
Adding a
.markdownlint.yamlor.markdownlint.jsonfile to your repository with:MD040: false
-
Or adding a comment to disable it for specific blocks:
<!-- markdownlint-disable MD040 -->your code block here
<!-- markdownlint-enable MD040 -->
Alternatively, if you'd prefer I simply not mention MD040 violations in my reviews regardless of what the linter reports, I can add that as a learning for this project. Let me know which approach you prefer!
🧠 Learnings used
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
| #### Scenario: Delivery changed to skills-only | ||
| - **WHEN** user runs `openspec update` | ||
| - **AND** global config specifies `delivery: skills` | ||
| - **AND** project has command files installed | ||
| - **THEN** the system SHALL delete command files for workflows in the profile | ||
| - **THEN** the system SHALL generate/update skill files only | ||
| - **THEN** the system SHALL display: "Removed: <count> command files (delivery: skills)" |
There was a problem hiding this comment.
Scenario "Delivery changed to skills-only" scope is misleadingly narrower than intended.
Line 40 says the system SHALL delete command files "for workflows in the profile," but the "Delivery change with extra workflows" scenario (lines 67-72) clarifies that all command files are deleted — including those for extra workflows not in the profile. An implementor testing against only this scenario would skip cleanup of extra-workflow command files, producing a partially cleaned project.
✏️ Suggested fix
-- **THEN** the system SHALL delete command files for workflows in the profile
+- **THEN** the system SHALL delete command files for all installed workflows (including extras not in profile)📝 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.
| #### Scenario: Delivery changed to skills-only | |
| - **WHEN** user runs `openspec update` | |
| - **AND** global config specifies `delivery: skills` | |
| - **AND** project has command files installed | |
| - **THEN** the system SHALL delete command files for workflows in the profile | |
| - **THEN** the system SHALL generate/update skill files only | |
| - **THEN** the system SHALL display: "Removed: <count> command files (delivery: skills)" | |
| #### Scenario: Delivery changed to skills-only | |
| - **WHEN** user runs `openspec update` | |
| - **AND** global config specifies `delivery: skills` | |
| - **AND** project has command files installed | |
| - **THEN** the system SHALL delete command files for all installed workflows (including extras not in profile) | |
| - **THEN** the system SHALL generate/update skill files only | |
| - **THEN** the system SHALL display: "Removed: <count> command files (delivery: skills)" |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/simplify-skill-installation/specs/cli-update/spec.md` around
lines 36 - 42, The scenario "Delivery changed to skills-only" incorrectly scopes
deletion to "command files for workflows in the profile"; update the spec for
the "Delivery changed to skills-only" scenario (triggered by running `openspec
update` with global config `delivery: skills`) to require deletion of all
command files in the project (not just those belonging to profile workflows),
ensure the spec also clarifies that skill files are generated/updated and the
final message remains "Removed: <count> command files (delivery: skills)";
reference the scenario title, the `openspec update` action, the `delivery:
skills` config, and the expected removal message when making the change.
| **After (simplified):** | ||
| ``` | ||
| openspec config profile # interactive picker (delivery + workflows) | ||
| openspec config profile core # preset shortcut | ||
| openspec config profile extended # preset shortcut | ||
| ``` |
There was a problem hiding this comment.
extended preset in "What We've Decided" contradicts the final two-profile design.
Line 34 still shows openspec config profile extended # preset shortcut in the "After (simplified)" section, but design.md §2 explicitly dropped extended ("Extended is redundant") and the normative profiles/spec.md defines only core and custom. Readers consulting this "decided" section for the final command surface will believe extended is a valid shortcut when it is not.
✏️ Suggested fix
openspec config profile # interactive picker (delivery + workflows)
openspec config profile core # preset shortcut
-openspec config profile extended # preset shortcut🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 31-31: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/explorations/workspace-architecture.md` around lines 30 - 35, The
"After (simplified)" snippet still lists the deprecated `extended` preset (the
line `openspec config profile extended # preset shortcut`), which contradicts
design.md §2 and profiles/spec.md that define only `core` and `custom`; update
that snippet to remove or replace the `extended` entry so it reflects the final
two-profile design (e.g., change to `openspec config profile custom # preset
shortcut` or remove the line entirely), and verify the surrounding "What We've
Decided" text no longer references `extended`.
| #### Scenario: Applying progressive rigor | ||
| - **WHEN** an agent drafts specs for routine changes | ||
| - **THEN** instructions SHALL favor concise, lightweight requirements and scenarios | ||
| - **AND** reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy sensitive work) |
There was a problem hiding this comment.
Missing hyphen in compound modifier.
security/privacy sensitive work should be security/privacy-sensitive work — the compound modifier preceding the noun requires a hyphen.
✏️ Proposed fix
- - **AND** reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy sensitive work)
+ - **AND** reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy-sensitive work)📝 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.
| - **AND** reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy sensitive work) | |
| - **AND** reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy-sensitive work) |
🧰 Tools
🪛 LanguageTool
[grammar] ~58-~58: Use a hyphen to join words.
Context: ...rations, cross-team, or security/privacy sensitive work) #### Scenario: Time-to-...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/specs/docs-agent-instructions/spec.md` at line 58, Replace the
unhyphenated compound modifier "security/privacy sensitive work" with the
hyphenated form "security/privacy-sensitive work" in the markdown text (look for
the line containing "**AND** reserve deeper, fuller specification style for
higher-risk changes (such as API breaks, migrations, cross-team, or
security/privacy sensitive work)"); ensure the hyphen is added so the compound
modifier correctly reads "security/privacy-sensitive work".
- Add tasks to update explore.ts references to /opsx:propose - Create exploration note for deeper explore → propose UX questions - Captures open questions about exploration artifacts, lifecycle, context handoff, and transition smoothness
TabishB
changed the title
- Add ## Purpose sections to all 10 spec files (required by schema) - Add specs/ to propose workflow's first-time user guidance scenario - Add --tools flag scenario for interactive mode in cli-init/spec.md - Clarify that profile changes take effect on next init/update - Fix design snippet to use AI_TOOLS config instead of TOOL_DIRS constant - Add explicit Windsurf detection scenario to available-tools/spec.md - Mark tasks 10.2-10.3 as follow-up work (out of scope) - Fix capability name: init → cli-init in proposal.md
1 participant
Summary
proposeworkflow combiningnew+fffor faster onboardingKey Design Decisions
~/.config/openspec/config.jsoninstead of new fileInit Flow
Change Artifacts
proposal.md- Why and what changesdesign.md- Technical decisions and rationalespecs/- Delta specs for capabilitiestasks.md- Implementation tasks grouped by featureexplorations/explore-workflow-ux.md- Open UX questions for explore → proposeTest plan
/opsx:applyafter merge🤖 Generated with Claude Code