From 31e5f5aa1bbe1b018a3505b0dcdb287403a9761c Mon Sep 17 00:00:00 2001 From: Pepijn Schoen Date: Sun, 12 Apr 2026 10:20:28 +0200 Subject: [PATCH 1/3] feat(openspec): propose add-skill-guidance change Co-Authored-By: Claude Sonnet 4.6 --- .../changes/add-skill-guidance/.openspec.yaml | 2 + .../changes/add-skill-guidance/proposal.md | 45 +++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 openspec/changes/add-skill-guidance/.openspec.yaml create mode 100644 openspec/changes/add-skill-guidance/proposal.md diff --git a/openspec/changes/add-skill-guidance/.openspec.yaml b/openspec/changes/add-skill-guidance/.openspec.yaml new file mode 100644 index 000000000..33d01f784 --- /dev/null +++ b/openspec/changes/add-skill-guidance/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-12 diff --git a/openspec/changes/add-skill-guidance/proposal.md b/openspec/changes/add-skill-guidance/proposal.md new file mode 100644 index 000000000..c3a797d58 --- /dev/null +++ b/openspec/changes/add-skill-guidance/proposal.md @@ -0,0 +1,45 @@ +## Why + +`openspec/config.yaml` lets teams inject project context and per-artifact rules into artifact generation, but there is no equivalent mechanism for workflow skills (explore, propose, apply, etc.). Teams have no way to pass project-specific conventions into skill behaviour without editing the seeded skill files directly — which get overwritten on `openspec update`. + +## What Changes + +- **New CLI command** `openspec guidance [--json]`: reads `openspec/config.yaml` and returns the shared project `context` plus any skill-specific instruction string from a new `skills:` key. +- **New `skills:` key in `config.yaml`**: a free-form map of skill name → instruction string. All keys are accepted without validation. +- **Guidance step in all seeded workflow templates**: every workflow skill (explore, propose, apply, archive, verify, onboard, continue, ff-change) calls `openspec guidance --json` as Step 1. The returned `context` is applied as binding project constraints throughout the session; the returned `instructions` override or extend the skill's default behaviour for the session. If the command fails or returns null fields, the skill continues normally. +- **Updated seeded `config.yaml` template**: the scaffold from `openspec init` gains a commented-out `skills:` section so the feature is discoverable on first setup. +- **Updated user-facing docs**: `docs/customization.md` documents the `skills:` config key; `docs/cli.md` documents the `openspec guidance` command. +- **Updated specs**: `skill-guidance-command`, `config-loading`, `explore-skill-workflow`, and `propose-skill-workflow` specs updated to reflect OpenSpec CLI identity and precise field roles. + +## Capabilities + +### New Capabilities + +- `skill-guidance-command`: The `openspec guidance ` CLI command — reads `openspec/config.yaml` and returns `{ skill, context, instructions }`. `context` is the shared project context field; `instructions` is the value of `skills.` if present, null otherwise. +- `explore-skill-workflow`: Guidance fetch as Step 1 in the numbered Steps sequence, before document creation or any other action. `context` = binding project constraints applied throughout the session (not written to the exploration document); `instructions` = workflow-specific overrides for the session. +- `propose-skill-workflow`: Guidance fetch as Step 1, before flag parsing, exploration doc scanning, or any other action. `context` = binding project constraints; `instructions` = workflow-specific overrides. Includes requirements for OpenSpec branding in generated templates (CLI binary, display names, skill metadata). + +### Modified Capabilities + +- `config-loading`: `ProjectConfigSchema` and `readProjectConfig` gain a `skills` field — a `Record` map of skill name to instruction string. Unknown keys accepted without validation. + +## Impact + +- `src/commands/guidance.ts` — new command, wired into CLI +- `src/core/project-config.ts` — schema and parser updated for `skills:` field +- `src/core/templates/workflows/explore.ts` — guidance as Step 1 (skill + command templates) +- `src/core/templates/workflows/propose.ts` — guidance as Step 1 (skill + command templates) +- `src/core/templates/workflows/apply-change.ts` — guidance as Step 1 +- `src/core/templates/workflows/archive-change.ts` — guidance as Step 1 +- `src/core/templates/workflows/verify-change.ts` — guidance as Step 1 +- `src/core/templates/workflows/onboard.ts` — guidance as Step 1 +- `src/core/templates/workflows/continue-change.ts` — guidance as Step 1 +- `src/core/templates/workflows/ff-change.ts` — guidance as Step 1 +- `src/core/init.ts` — seeded `config.yaml` template updated with commented `skills:` section +- `docs/customization.md` — new "Skill-Specific Instructions" section documenting `skills:` key +- `docs/cli.md` — new entry for `openspec guidance` command +- `openspec/specs/skill-guidance-command/spec.md` — new spec +- `openspec/specs/explore-skill-workflow/spec.md` — new spec +- `openspec/specs/propose-skill-workflow/spec.md` — new spec +- `openspec/specs/config-loading/spec.md` — delta: `skills:` field requirement +- No breaking changes to existing config files; `skills:` is optional and additive From d671a50c310ac8edd8f1a5728beaed9b3db7dc02 Mon Sep 17 00:00:00 2001 From: Pepijn Schoen Date: Sun, 12 Apr 2026 12:57:03 +0200 Subject: [PATCH 2/3] fix(openspec): revise add-skill-guidance proposal based on review - Clarify failure/null handling: explicit failures log a warning, partial null fields silently apply non-null fields only - Remove allowlist warning for unknown skills: keys - Drop branding requirements from propose-skill-workflow capability - Use short skill names (apply, archive, verify, continue, ff-change) - Add concrete examples for context vs instructions distinction - Clarify skill field is an echo of the input argument Co-Authored-By: Claude Sonnet 4.6 --- openspec/changes/add-skill-guidance/proposal.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openspec/changes/add-skill-guidance/proposal.md b/openspec/changes/add-skill-guidance/proposal.md index c3a797d58..23d749f0d 100644 --- a/openspec/changes/add-skill-guidance/proposal.md +++ b/openspec/changes/add-skill-guidance/proposal.md @@ -6,7 +6,7 @@ - **New CLI command** `openspec guidance [--json]`: reads `openspec/config.yaml` and returns the shared project `context` plus any skill-specific instruction string from a new `skills:` key. - **New `skills:` key in `config.yaml`**: a free-form map of skill name → instruction string. All keys are accepted without validation. -- **Guidance step in all seeded workflow templates**: every workflow skill (explore, propose, apply, archive, verify, onboard, continue, ff-change) calls `openspec guidance --json` as Step 1. The returned `context` is applied as binding project constraints throughout the session; the returned `instructions` override or extend the skill's default behaviour for the session. If the command fails or returns null fields, the skill continues normally. +- **Guidance step in all seeded workflow templates**: every workflow skill (explore, propose, apply, archive, verify, onboard, continue, ff-change) calls `openspec guidance --json` as Step 1. If the command exits non-zero, cannot be found, or its output cannot be parsed, the skill logs a warning with the command, skill name, and error details and continues without applying any guidance. If the command succeeds but one or both fields are null, the skill silently applies only the non-null field(s). - **Updated seeded `config.yaml` template**: the scaffold from `openspec init` gains a commented-out `skills:` section so the feature is discoverable on first setup. - **Updated user-facing docs**: `docs/customization.md` documents the `skills:` config key; `docs/cli.md` documents the `openspec guidance` command. - **Updated specs**: `skill-guidance-command`, `config-loading`, `explore-skill-workflow`, and `propose-skill-workflow` specs updated to reflect OpenSpec CLI identity and precise field roles. @@ -15,13 +15,13 @@ ### New Capabilities -- `skill-guidance-command`: The `openspec guidance ` CLI command — reads `openspec/config.yaml` and returns `{ skill, context, instructions }`. `context` is the shared project context field; `instructions` is the value of `skills.` if present, null otherwise. -- `explore-skill-workflow`: Guidance fetch as Step 1 in the numbered Steps sequence, before document creation or any other action. `context` = binding project constraints applied throughout the session (not written to the exploration document); `instructions` = workflow-specific overrides for the session. -- `propose-skill-workflow`: Guidance fetch as Step 1, before flag parsing, exploration doc scanning, or any other action. `context` = binding project constraints; `instructions` = workflow-specific overrides. Includes requirements for OpenSpec branding in generated templates (CLI binary, display names, skill metadata). +- `skill-guidance-command`: The `openspec guidance ` CLI command — reads `openspec/config.yaml` and returns `{ skill, context, instructions }`. `skill` is an echo of the input argument. `context` is the shared project context field (e.g. "Always use TypeScript strict mode; follow the Google Style Guide"); `instructions` is the value of `skills.` if present, null otherwise. +- `explore-skill-workflow`: Guidance fetch as Step 1 in the numbered Steps sequence, before document creation or any other action. `context` = persistent project-level constraints applied throughout the session, never written to the exploration document (e.g. "All code must target Node.js ≥20"); `instructions` = session overrides specific to the explore workflow (e.g. "always create a decision log entry for each Q&A round"). +- `propose-skill-workflow`: Guidance fetch as Step 1, before flag parsing, exploration doc scanning, or any other action. `context` = persistent project-level constraints; `instructions` = session overrides specific to the propose workflow (e.g. "include cost estimates in every proposal"; "tag proposals affecting the public API with `api-impact: true`"). ### Modified Capabilities -- `config-loading`: `ProjectConfigSchema` and `readProjectConfig` gain a `skills` field — a `Record` map of skill name to instruction string. Unknown keys accepted without validation. +- `config-loading`: `ProjectConfigSchema` and `readProjectConfig` gain a `skills` field — a `Record` map of skill name to instruction string. All keys are accepted without validation. ## Impact From 33c3d41cfc4723681e0c368c8e4ed832eb9b20ec Mon Sep 17 00:00:00 2001 From: Pepijn Schoen Date: Sun, 12 Apr 2026 13:08:46 +0200 Subject: [PATCH 3/3] fix(openspec): add missing workflow specs to add-skill-guidance proposal All 8 workflow skills get guidance specs: new specs for apply, continue, and ff-change; delta specs for archive, verify, and onboard. Co-Authored-By: Claude Sonnet 4.6 --- openspec/changes/add-skill-guidance/proposal.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/openspec/changes/add-skill-guidance/proposal.md b/openspec/changes/add-skill-guidance/proposal.md index 23d749f0d..dd7bebab3 100644 --- a/openspec/changes/add-skill-guidance/proposal.md +++ b/openspec/changes/add-skill-guidance/proposal.md @@ -9,7 +9,7 @@ - **Guidance step in all seeded workflow templates**: every workflow skill (explore, propose, apply, archive, verify, onboard, continue, ff-change) calls `openspec guidance --json` as Step 1. If the command exits non-zero, cannot be found, or its output cannot be parsed, the skill logs a warning with the command, skill name, and error details and continues without applying any guidance. If the command succeeds but one or both fields are null, the skill silently applies only the non-null field(s). - **Updated seeded `config.yaml` template**: the scaffold from `openspec init` gains a commented-out `skills:` section so the feature is discoverable on first setup. - **Updated user-facing docs**: `docs/customization.md` documents the `skills:` config key; `docs/cli.md` documents the `openspec guidance` command. -- **Updated specs**: `skill-guidance-command`, `config-loading`, `explore-skill-workflow`, and `propose-skill-workflow` specs updated to reflect OpenSpec CLI identity and precise field roles. +- **New and updated specs**: guidance fetch requirement added to all workflow skill specs — new specs for `explore-skill-workflow`, `propose-skill-workflow`, `apply-skill-workflow`, `continue-skill-workflow`, and `ff-change-skill-workflow` (none existed in OpenSpec); delta specs for `opsx-archive-skill`, `opsx-verify-skill`, and `opsx-onboard-skill` (guidance step added to existing specs); delta spec for `config-loading` (`skills:` field); new spec for `skill-guidance-command`. ## Capabilities @@ -18,10 +18,16 @@ - `skill-guidance-command`: The `openspec guidance ` CLI command — reads `openspec/config.yaml` and returns `{ skill, context, instructions }`. `skill` is an echo of the input argument. `context` is the shared project context field (e.g. "Always use TypeScript strict mode; follow the Google Style Guide"); `instructions` is the value of `skills.` if present, null otherwise. - `explore-skill-workflow`: Guidance fetch as Step 1 in the numbered Steps sequence, before document creation or any other action. `context` = persistent project-level constraints applied throughout the session, never written to the exploration document (e.g. "All code must target Node.js ≥20"); `instructions` = session overrides specific to the explore workflow (e.g. "always create a decision log entry for each Q&A round"). - `propose-skill-workflow`: Guidance fetch as Step 1, before flag parsing, exploration doc scanning, or any other action. `context` = persistent project-level constraints; `instructions` = session overrides specific to the propose workflow (e.g. "include cost estimates in every proposal"; "tag proposals affecting the public API with `api-impact: true`"). +- `apply-skill-workflow`: Guidance fetch as Step 1. +- `continue-skill-workflow`: Guidance fetch as Step 1. +- `ff-change-skill-workflow`: Guidance fetch as Step 1. ### Modified Capabilities - `config-loading`: `ProjectConfigSchema` and `readProjectConfig` gain a `skills` field — a `Record` map of skill name to instruction string. All keys are accepted without validation. +- `opsx-archive-skill`: Guidance fetch added as Step 1. +- `opsx-verify-skill`: Guidance fetch added as Step 1. +- `opsx-onboard-skill`: Guidance fetch added as Step 1. ## Impact @@ -41,5 +47,11 @@ - `openspec/specs/skill-guidance-command/spec.md` — new spec - `openspec/specs/explore-skill-workflow/spec.md` — new spec - `openspec/specs/propose-skill-workflow/spec.md` — new spec +- `openspec/specs/apply-skill-workflow/spec.md` — new spec +- `openspec/specs/continue-skill-workflow/spec.md` — new spec +- `openspec/specs/ff-change-skill-workflow/spec.md` — new spec - `openspec/specs/config-loading/spec.md` — delta: `skills:` field requirement +- `openspec/specs/opsx-archive-skill/spec.md` — delta: guidance step requirement +- `openspec/specs/opsx-verify-skill/spec.md` — delta: guidance step requirement +- `openspec/specs/opsx-onboard-skill/spec.md` — delta: guidance step requirement - No breaking changes to existing config files; `skills:` is optional and additive