feat(workflows): select schemas before change creation - #1615
Conversation
📝 WalkthroughWalkthroughThe change adds shared, fail-closed schema-selection guidance to generated ChangesWorkflow schema selection
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant Workflow
participant Context
participant Schemas
participant OpenSpec
Workflow->>Context: Resolve root with context --json
Context-->>Workflow: Return root and store context
Workflow->>Schemas: Discover schemas with schemas --json
Schemas-->>Workflow: Return names and descriptions
Workflow->>OpenSpec: Create change with confirmed --schema
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 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: 1
🧹 Nitpick comments (1)
test/core/templates/schema-selection.test.ts (1)
27-58: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winAdd assertions for the ambiguity and rejection stop conditions.
The PR contract requires fail-closed behavior for ambiguity, rejection, and discovery failures. This test checks marker phrases, but it does not verify the required actions: stop before creation, list candidates, ask the user to choose, and report root-resolution failures. A regression could remove those actions while this test still passes.
Proposed assertions
expect(SCHEMA_SELECTION_GUIDANCE).toContain('exactly one is a clear match'); + expect(SCHEMA_SELECTION_GUIDANCE).toContain( + 'If no unique recommendation is possible, stop before creating the change' + ); + expect(SCHEMA_SELECTION_GUIDANCE).toContain( + 'list the relevant candidates with their descriptions' + ); + expect(SCHEMA_SELECTION_GUIDANCE).toContain( + 'ask the user to choose' + ); + expect(SCHEMA_SELECTION_GUIDANCE).toContain( + 'If the user rejects a recommendation, stop and list the relevant candidates' + ); + expect(SCHEMA_SELECTION_GUIDANCE).toContain( + 'If root resolution or `openspec schemas --json` fails' + );🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@test/core/templates/schema-selection.test.ts` around lines 27 - 58, The test `defines the complete fail-closed selection and confirmation contract` only checks marker phrases and must also assert the required actions. Extend its `SCHEMA_SELECTION_GUIDANCE` expectations to verify ambiguity and rejected recommendations stop before creation, list candidates, and ask the user to choose, while discovery/root-resolution failures are explicitly reported. Preserve the existing assertions for invalid stores, empty results, and no default fallback.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/core/templates/workflows/schema-selection.ts`:
- Line 12: Update SCHEMA_SELECTION_GUIDANCE so the schemas discovery command
executes with its working directory explicitly set to the root.path returned by
openspec context, using a supported safe mechanism rather than relying on Bash
cd or an unconstrained openspec command. Preserve the existing store-selection
and no_openspec_root behavior, and add coverage verifying schema discovery uses
roots from local store: pointers and defaultStore.
---
Nitpick comments:
In `@test/core/templates/schema-selection.test.ts`:
- Around line 27-58: The test `defines the complete fail-closed selection and
confirmation contract` only checks marker phrases and must also assert the
required actions. Extend its `SCHEMA_SELECTION_GUIDANCE` expectations to verify
ambiguity and rejected recommendations stop before creation, list candidates,
and ask the user to choose, while discovery/root-resolution failures are
explicitly reported. Preserve the existing assertions for invalid stores, empty
results, and no default fallback.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: bc1041fa-98d5-49f6-bac8-0f1632aa9ce2
📒 Files selected for processing (15)
openspec/changes/add-workflow-schema-selection/.openspec.yamlopenspec/changes/add-workflow-schema-selection/design.mdopenspec/changes/add-workflow-schema-selection/proposal.mdopenspec/changes/add-workflow-schema-selection/specs/command-generation/spec.mdopenspec/changes/add-workflow-schema-selection/tasks.mdskills/openspec-ff-change/SKILL.mdskills/openspec-new-change/SKILL.mdskills/openspec-propose/SKILL.mdsrc/core/templates/workflows/ff-change.tssrc/core/templates/workflows/new-change.tssrc/core/templates/workflows/propose.tssrc/core/templates/workflows/schema-selection.tstest/core/templates/propose.test.tstest/core/templates/schema-selection.test.tstest/core/templates/skill-templates-parity.test.ts
| Before creating the change, determine the schema as follows: | ||
|
|
||
| - If the user explicitly names a schema, use it and treat that choice as confirmed. If they also explicitly ask you to confirm it, stop and wait for confirmation. | ||
| - Otherwise, resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and inspect each schema's \`name\`, \`description\`, and \`artifacts\`. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; \`schemas\` does not accept \`--store\`. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 4 \
'allowed-tools: Bash\(openspec:\*\)|root\.path|working directory|cwd|cd .*openspec schemas' \
src skills test scriptsRepository: Fission-AI/OpenSpec
Length of output: 50376
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate schema-selection and skill generation files =="
fd -a 'schema-selection|skill|prompts|generat' src test tools scripts | sed 's#^\./##' | head -300
echo
echo "== focused grep for generated skills and allowed tools =="
rg -n --max-count=50 \
'allowed-tools|Bash\(openspec:\*\)|SCHEMA_SELECTION_GUIDANCE|schema-selection|allowedTools|openapi|tools' \
src test tools scripts -g '!node_modules' -g '!dist' -g '!build'
echo
echo "== candidate workflow file first 80 lines =="
sed -n '1,80p' src/core/templates/workflows/schema-selection.tsRepository: Fission-AI/OpenSpec
Length of output: 50375
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== schema-selection guidance =="
sed -n '1,80p' src/core/templates/workflows/schema-selection.ts
echo
echo "== workflow templates that import guidance =="
for f in src/core/templates/workflows/propose.ts src/core/templates/workflows/new-change.ts src/core/templates/workflows/ff-change.ts; do
echo "--- $f"
sed -n '1,70p' "$f"
done
echo
echo "== skill template / generated prefix snippet =="
fd -a 'skill.*\.ts$|skill.*\.mjs$' src | sed 's#^\./##' | head -50
for f in $(fd 'skill.*\.ts$|skill.*\.mjs$' src | head -20); do
if rg -q 'allowed-tools|OPENSPEC_CLI_ALLOWED_TOOLS|generate|bash|Bash' "$f"; then
echo "--- $f"
rg -n -C 5 'allowed-tools|OPENSPEC_CLI_ALLOWED_TOOLS|allowedTools|generate|bash|Bash|mktemp|mkdir|cat|sed|python|node|sh -c|cwd' "$f"
fi
done
echo
echo "== command-generation frontmatter/adapter snippets =="
sed -n '1,90p' src/core/command-generation/adapters/claude.ts
sed -n '120,165p' src/core/shared/skill-generation.tsRepository: Fission-AI/OpenSpec
Length of output: 22079
🌐 Web query:
Claude Code generated skills allowed-tools Bash prefix working directory cwd command option
💡 Result:
In Claude Code, managing the working directory (cwd) for Bash commands and configuring tool permissions (allowed-tools and command prefixes) is handled through a combination of CLI flags, environment variables, and configuration settings. Working Directory (cwd) Behavior By default, Claude Code attempts to maintain the working directory between Bash command executions as long as the directory remains within the project root or an authorized additional directory [1][2]. - When Claude runs a cd command, the new directory carries over to subsequent Bash commands [1][2]. - If a cd command takes the shell outside of the allowed project directories, Claude Code automatically resets the working directory to the project root and returns a message: Shell cwd was reset to... [1][2]. - To disable this carry-over behavior—forcing every individual Bash command to start in the project directory—you can set the environment variable CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 [1][2]. Tool Permissions and Bash Prefixes Claude Code uses a pattern-matching system for tool permissions, which can be managed via the --allowedTools and --disallowedTools CLI flags or within configuration files [1][3][4]. - Bash commands support wildcard matching (*) [3][5]. - A prefix (e.g., Bash(npm run *)) restricts Claude to running only commands that match that specific pattern [3][5]. - When you use a restricted command prefix and select "Yes, don't ask again" in the permission dialog, Claude creates an allowed pattern that acts as a persistent permission rule for that specific command structure [3][5]. - Wildcards can be used at the beginning, middle, or end of a command string [3][5]. For example, Bash(npm *) allows any command starting with npm, while Bash(ls *) requires a space after ls to match, ensuring distinct command boundaries [3][5]. Additional Configuration - Additional Directories: You can authorize Claude Code to access and operate in directories outside the project root using the --add-dir CLI flag or by defining permissions.additionalDirectories in your settings [1][4][6]. - CLI Options: While there is no direct --cwd command-line option to lock the execution directory for all tools at startup, the --add-dir flag is the primary mechanism for extending the accessible file scope [6][7]. - Troubleshooting: If you encounter issues with shell initialization or working directory persistence, setting CLAUDE_BASH_NO_LOGIN=1 may help by skipping standard login shell initialization, which can sometimes interfere with consistent directory management [8].
Citations:
- 1: https://code.claude.com/docs/en/tools
- 2: https://code.claude.com/docs/en/tools-reference
- 3: https://code.claude.com/docs/en/permissions.md
- 4: https://code.claude.com/docs/en/cli-reference
- 5: https://code.claude.com/docs/en/permissions
- 6: https://code.claude.com/docs/en/cli
- 7: https://zenn.dev/daishiro/articles/claude-code-cli-cheatsheet?locale=en
- 8: [BUG] Bash Tool Not Respecting Working Directory anthropics/claude-code#11067
🌐 Web query:
Claude Code agent skill Bash tool parameter cwd working directory
💡 Result:
As of August 9, 2026, the Bash tool in Claude Code does not support a cwd (working directory) parameter [1][2][3]. The tool is designed to execute commands within the environment's current shell session, and directory state persists between consecutive Bash tool invocations by default [4][5][6]. Current Technical Behavior and Constraints: 1. Absence of Parameter: There is no native cwd parameter for the Bash tool [1][2]. Requests to add this feature have been tracked in project issues to facilitate multi-repo workflows and parallel agent execution, but it has not been implemented [1][2][3]. 2. Default Persistence: By default, when Claude runs a command like cd in the main session, the change in the working directory carries over to subsequent Bash tool commands [4][5]. 3. Reset Logic: Claude Code will automatically reset the working directory to the project root if a command attempts to cd outside of the project directory or authorized additional directories (configured via --add-dir or settings) [4][5]. 4. Configuration Override: You can disable the default directory persistence so that every Bash command starts at the project root by setting the environment variable CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 [4][5][7]. 5. Subagent Limitations: Subagents launched by the Agent tool often face challenges inheriting or managing working directories correctly, with some reports indicating they may default to unexpected directories like /root or fail to persist state between tool calls [3][8]. Because there is no direct parameter, the current recommended approach for directory-dependent commands is to use absolute paths or prefix commands with cd /path/to/target && <command>, though this may trigger manual approval prompts depending on your security/permission settings [1][4][5].
Citations:
- 1: [FEATURE] Add cwd parameter to Agent and Bash tools anthropics/claude-code#44143
- 2: [FEATURE] Agent CWD parameter and forwarding agent name to WorktreeCreate hooks anthropics/claude-code#36803
- 3: [BUG] Subagent Bash tool CWD does not inherit from Task launch context AND every workaround is blocked by security checks anthropics/claude-code#53383
- 4: https://code.claude.com/docs/en/tools
- 5: https://code.claude.com/docs/en/tools-reference
- 6: https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool
- 7: [BUG] Bash Tool Not Respecting Working Directory anthropics/claude-code#11067
- 8: [BUG] Sub-agents (Explore, Plan, general-purpose) Bash tool defaults to /root instead of inheriting parent session's working directory anthropics/claude-code#33576
Make the root.path schema-discovery step enforce the correct CWD.
SCHEMA_SELECTION_GUIDANCE requires openspec schemas --json to run with the working directory set to the path returned by openspec context --json, but generated skills only allow Bash(openspec:*). A plain openspec schemas --json command has no cwd argument, and bash cd can be blocked by Claude Code permission dialogs. Change the workflow to invoke schemas from the context root.path via a supported safe mechanism, and add coverage for local store: and defaultStore roots.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/core/templates/workflows/schema-selection.ts` at line 12, Update
SCHEMA_SELECTION_GUIDANCE so the schemas discovery command executes with its
working directory explicitly set to the root.path returned by openspec context,
using a supported safe mechanism rather than relying on Bash cd or an
unconstrained openspec command. Preserve the existing store-selection and
no_openspec_root behavior, and add coverage verifying schema discovery uses
roots from local store: pointers and defaultStore.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/openspec-ff-change/SKILL.md`:
- Around line 34-42: Update the schema-discovery flow in the generated skill to
first run openspec context --json and resolve the authoritative root.path,
matching skills/openspec-propose/SKILL.md. Execute openspec schemas --json from
that resolved root so local store pointers, global defaults, and standalone
stores are honored before recommending a schema. Apply the change to the source
template and regenerate the generated skill.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: a3d57b85-a159-4cc3-85f2-2c5d013f293e
📒 Files selected for processing (10)
openspec/changes/add-workflow-schema-selection/design.mdopenspec/changes/add-workflow-schema-selection/specs/command-generation/spec.mdskills/openspec-ff-change/SKILL.mdskills/openspec-new-change/SKILL.mdskills/openspec-propose/SKILL.mdsrc/core/templates/workflows/propose.tssrc/core/templates/workflows/schema-selection.tstest/core/templates/propose.test.tstest/core/templates/schema-selection.test.tstest/core/templates/skill-templates-parity.test.ts
🚧 Files skipped from review as they are similar to previous changes (8)
- src/core/templates/workflows/schema-selection.ts
- test/core/templates/skill-templates-parity.test.ts
- test/core/templates/propose.test.ts
- skills/openspec-new-change/SKILL.md
- openspec/changes/add-workflow-schema-selection/specs/command-generation/spec.md
- src/core/templates/workflows/propose.ts
- test/core/templates/schema-selection.test.ts
- openspec/changes/add-workflow-schema-selection/design.md
| - Otherwise, run `openspec schemas --json` and inspect each schema's `name`, `description`, and `artifacts`. | ||
| - Use `description` as the authority for matching the request. Use `name` and `artifacts` only to identify, display, and explain candidates. | ||
| - Select a schema only when exactly one is a clear match. | ||
| - Normally, present the recommendation and a concise reason, then stop and wait for confirmation. | ||
| - Skip that confirmation only when the user's current request or the selected schema's description clearly and unambiguously says no further confirmation is needed. | ||
| - If the user explicitly asks for confirmation, always wait even if the selected schema's description waives it. | ||
| - If no unique recommendation is possible, stop before creating the change, list the relevant candidates with their descriptions, and ask the user to choose. Never silently use the default schema. | ||
| - If the user rejects a recommendation, stop and list the relevant candidates so they can choose. | ||
| - If `openspec schemas --json` fails, cannot be parsed, or returns no schemas, stop and report the problem. Do not fall back to the default. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Resolve the authoritative root before schema discovery.
When the user does not provide a schema, Line 34 runs openspec schemas --json from the current directory. A local store: pointer, global default store, or selected standalone store can therefore be ignored. The workflow can recommend a schema from the wrong root before creating the change in the selected store.
Add the same openspec context --json and root.path resolution used by skills/openspec-propose/SKILL.md. Update the source template and regenerate this generated skill.
🧰 Tools
🪛 SkillSpector (2.5.1)
[error] 98: [MP3] Memory Manipulation: Skill manipulates agent memory, state, or stored context. Memory corruption can alter personality, override safety rules, or cause unpredictable behavior.
Remediation: Protect agent memory and state from modification by untrusted content. Use read-only memory for critical instructions and validate all state changes.
(Memory Poisoning (MP3))
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/openspec-ff-change/SKILL.md` around lines 34 - 42, Update the
schema-discovery flow in the generated skill to first run openspec context
--json and resolve the authoritative root.path, matching
skills/openspec-propose/SKILL.md. Execute openspec schemas --json from that
resolved root so local store pointers, global defaults, and standalone stores
are honored before recommending a schema. Apply the change to the source
template and regenerate the generated skill.
Source: Learnings
There was a problem hiding this comment.
@Patodo, acknowledged. The finding remains open until #1616 merges and this branch includes the regenerated generated skills and parity checks. The canonical root behavior and --store support in openspec schemas should resolve the underlying issue.
🧠 Learnings used
Learnt from: clay-good
Repo: Fission-AI/OpenSpec PR: 1357
File: skills/openspec-apply-change/SKILL.md:14-14
Timestamp: 2026-07-17T15:42:00.801Z
Learning: For generated OpenSpec workflow skills in `skills/**/SKILL.md`, treat `--store <id>` as intentionally conditional. Only add `--store <id>` after the agent can confirm a registered standalone store (or when command hints have established the store) and keep it for subsequent store-capable commands. Inline command examples should use the default local-root invocation (resolves against the nearest `openspec/` directory) and should not require an unbound `--store <id>` placeholder in those examples unless the store has already been identified by the user/previous steps.
Learnt from: clay-good
Repo: Fission-AI/OpenSpec PR: 1357
File: skills/openspec-update-change/SKILL.md:20-22
Timestamp: 2026-07-17T15:42:02.318Z
Learning: For generated OpenSpec workflow skill documents under `skills/`, keep the `--store <id>` flag usage conditional: only add and propagate `--store <id>` in command examples when the user’s scope (name/work) is a registered standalone OpenSpec store. If the user is not scoped to such a store, show the default local-root invocation (without a `--store <id>` placeholder). Do not include a literal `--store <id>` placeholder in inline commands for local-root usage, since commands would otherwise target the nearest local `openspec/` root and the placeholder would fail or mislead users.
Learnt from: clay-good
Repo: Fission-AI/OpenSpec PR: 1468
File: skills/openspec-verify-change/SKILL.md:31-31
Timestamp: 2026-07-28T01:26:58.191Z
Learning: In this repo’s OpenSpec “skills” distribution, committed `skills/<skill-name>/SKILL.md` files are the generated output of `scripts/generate-skillssh.mjs`. Reviewers should treat these files as generated artifacts (don’t manually change them unless updating the generator) and must ensure they do not introduce a direct `/opsx:*` command surface. `/opsx:<command>` references (including `/opsx:verify`) should be represented as skill invocations (e.g., `/openspec-verify-change`) via `transformToSkillReferences` from `src/utils/command-references.ts`. The committed skills tree must match the generator output exactly, as enforced by `test/core/templates/skillssh-parity.test.ts`. Exception: command-enabled workflow templates should retain `/opsx:*` references (this rule applies to the committed skills tree).
You are interacting with an AI system.
1 participant
Summary
new,propose, andffskills and slash commands.--schemaargument.Why
Multi-schema projects currently either rely on the configured default or duplicate routing instructions outside schema descriptions. This lets the creation workflows use existing schema metadata while keeping the user in control of inferred choices.
Impact
This changes generated workflow guidance only. The raw CLI behavior, schema model, project defaults, and schema JSON output remain unchanged. No dedicated changeset is included, following the repository's normal release cadence.
OpenSpec
openspec/changes/add-workflow-schema-selection/Validation
pnpm run lintpnpm run buildpnpm test -- --silent=passed-only— 130 files, 3864 tests passednode bin/openspec.js validate add-workflow-schema-selection --strictAI disclosure
Generated with Codex using GPT-5.6 Sol (max reasoning effort).
Summary by CodeRabbit
New Features
Bug Fixes
Tests