specify-cli 1.2.5__tar.gz → 1.2.6__tar.gz

{specify_cli-1.2.5 → specify_cli-1.2.6}/.github/workflows/codeql.yml

@@ -22,11 +22,11 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4
+        uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4
+        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4
         with:
           category: "/language:${{ matrix.language }}"

{specify_cli-1.2.5 → specify_cli-1.2.6}/.github/workflows/lint.yml

@@ -88,7 +88,7 @@ jobs:
           fi
 
       - name: Run markdownlint-cli2
-        uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24.2.0
+        uses: DavidAnson/markdownlint-cli2-action@696eb3f2509270d7b882d2aa68347bc676e7af34 # v25.0.0
         with:
           globs: ${{ env.DOC_GLOBS }}
 

{specify_cli-1.2.5 → specify_cli-1.2.6}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 <!-- insert new changelog below this comment -->
 
+## [1.2.6] - 2026-11-02
+
+### Changed
+
+- feat(droid): add --no-model-invocation integration option (#5116)
+- fix(extensions): make extension add name optional with --from (#5197)
+- fix(extensions): skip non-UTF-8 catalog responses (#5196)
+- feat: add `specify workflow definition` for run-scoped definitions (#4912)
+- fix(integrations): refresh manifest hashes after init --force and switch rollback (#5193)
+- fix(workflows): stop dispatching "None" as command step arguments (#5016)
+- feat(workflows): add opt-in strict shell execution (#5181)
+- chore(deps): bump DavidAnson/markdownlint-cli2-action (#5191)
+- chore(deps): bump the codeql-action group with 2 updates (#5189)
+- fix: reject symlinked integration state (#5176)
+- fix: reject trailing newlines in extension IDs (#5186)
+- fix: reject trailing newlines in preset IDs (#5188)
+- fix(templates): start spec.md from the composed spec-template (#5187)
+- docs: move extension API reference into documentation (#5174)
+- Update iSAQB Architecture Governance preset to v0.2.5 (#5183)
+- fix: reject unsafe self-upgrade installer paths (#5172)
+- fix(bundles): refuse to build when bundle.yml or README.md is a symlink (#5169)
+- docs(assess): clarify README invocation guidance (#5068)
+- fix(integrations): refresh manifest hashes after preset registration on switch and use (#5145)
+- chore: release 1.2.5, begin 1.2.6.dev0 development (#5167)
+
 ## [1.2.5] - 2026-10-28
 
 ### Changed

{specify_cli-1.2.5 → specify_cli-1.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specify-cli
-Version: 1.2.5
+Version: 1.2.6
 Summary: Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD).
 License-File: LICENSE
 Requires-Python: >=3.11

{specify_cli-1.2.5 → specify_cli-1.2.6}/bundles/assess/bundle.yml

@@ -17,7 +17,7 @@ requires:
 provides:
   extensions:
     - id: "assess"
-      version: "1.0.1"
+      version: "1.0.2"
   workflows:
     - id: "assess"
       version: "1.0.0"

{specify_cli-1.2.5 → specify_cli-1.2.6}/bundles/bugfix/bundle.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 bundle:
   id: "bugfix"
   name: "Guided Bug Fix"
-  version: "1.0.1"
+  version: "1.0.2"
   role: "developer"
   description: "Orchestrated bug triage: assess a bug report, review the assessment behind a human gate, apply the fix, and verify it with tests."
   author: "GitHub"
@@ -17,7 +17,7 @@ requires:
 provides:
   extensions:
     - id: "bug"
-      version: "1.0.1"
+      version: "1.0.2"
   workflows:
     - id: "bugfix"
       version: "1.0.0"

{specify_cli-1.2.5 → specify_cli-1.2.6}/bundles/catalog.json

@@ -6,7 +6,7 @@
     "bugfix": {
       "id": "bugfix",
       "name": "Guided Bug Fix",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "role": "developer",
       "description": "Orchestrated bug triage: assess a bug report, review behind a human gate, apply the fix, and verify with tests.",
       "author": "GitHub",

{specify_cli-1.2.5 → specify_cli-1.2.6}/design/file-helper.md

@@ -69,6 +69,16 @@ adapters. Commands using another established root call `project_files` on
 their actually selected root. Retain a helper only for the current operation;
 a later invocation resolves a new helper, so manual edits take effect.
 
+The `specify_cli.integration_state` helpers are an explicit managed-metadata
+exception to this handoff. Their reads and writes of `.specify/integration.json`
+always use deny mode, including contained links when `allow_symlinks` is true.
+This preserves the
+[integration lifecycle's restriction](integration.md#storage-loading-and-lifecycle)
+against symlinked write destinations before snapshotting and mutation.
+This guarantee does not cover unmigrated consumers such as
+`bundles.project.active_integration`, whose containment-checked reads can still
+follow contained state-file links.
+
 Existing Path-returning resolvers preflight policy without changing their return
 type or domain constructors. They do not implicitly equip unmigrated domain
 consumers with an operation helper. Failures are translated into existing

{specify_cli-1.2.5 → specify_cli-1.2.6}/design/workflow-step.md

@@ -43,6 +43,18 @@ automatically validate a definition passed to `execute()`. Guard invalid
 configurations in `execute()` too, returning a failed result rather than a
 successful default or an unhandled exception.
 
+The built-in shell step preserves raw `run` interpolation by default.
+Per-step `strict: true` rejects expression markers in `run` during validation
+and execution. Its optional `env` mapping evaluates string templates separately,
+requires NUL-free string results encodable for the process environment on
+POSIX, and overrides only the child environment.
+`SPECKIT_WORKFLOW_DIR` remains engine-owned. This prevents workflow expression
+values from becoming shell source in strict mode; it is not a sandbox or a
+guarantee that an authored script handles environment data safely.
+Environment bindings and inherited settings can intentionally affect executable
+lookup, module loading, and runtime startup. Strict mode does not filter them;
+workflow source review must cover both `run` and `env` and referenced code.
+
 New runs persist an execution tree. Resume replays completed occurrences into
 their expression contexts without calling their implementations, then continues
 at the unfinished occurrence. Selected branches, custom expansions, loop

{specify_cli-1.2.5 → specify_cli-1.2.6}/docs/community/presets.md

@@ -26,7 +26,7 @@ The following community-contributed presets customize how Spec Kit behaves — o
 | Intake Review Governance | Reviews single, series, campaign, and language-aware requirements collections before Spec Kit execution. | 9 templates, 3 commands, 5 scripts | — | [spec-kit-preset-intake-review-governance](https://github.com/hindermath/spec-kit-preset-intake-review-governance) |
 | Intake Sequencing Governance | Manages language-aware intake-series order, typed dependencies, lifecycle, and authority-neutral next-candidate selection. | 12 templates, 6 commands, 8 scripts | — | [spec-kit-preset-intake-sequencing-governance](https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance) |
 | Inventory Alignment | Classifies each requirement against a read-only inventory of live IDs before writing, so reworded requirements are updated instead of duplicated. | 1 template, 2 commands | speckit-inventory extension | [spec-kit-inventory-alignment](https://github.com/Yash-Chindam/spec-kit-inventory-alignment) |
-| iSAQB Architecture Governance | Adds iSAQB/CPSA-F and arc42 architecture governance, architecture views, quality scenarios, ADRs, risks, technical-debt evidence, and provider-neutral model routing. | 14 templates, 3 commands | — | [spec-kit-preset-isaqb-architecture-governance](https://github.com/hindermath/spec-kit-preset-isaqb-architecture-governance) |
+| iSAQB Architecture Governance | Adds iSAQB/CPSA-F and arc42 architecture governance with Spec-Kit evidence for goals, views, quality scenarios, ADRs, risks, and technical debt. | 14 templates, 3 commands | — | [spec-kit-preset-isaqb-architecture-governance](https://github.com/hindermath/spec-kit-preset-isaqb-architecture-governance) |
 | Jira Issue Tracking | Overrides `speckit.taskstoissues` to create Jira epics, stories, and tasks instead of GitHub Issues via Atlassian MCP tools | 1 command | — | [spec-kit-preset-jira](https://github.com/luno/spec-kit-preset-jira) |
 | Model Driven Engineering | Focuses on streamlined commands, app repository support, cross-spec support, and capability-aware project memory for model-driven engineering workflows | 6 templates, 11 commands | MDE extension | [spec-kit-preset-mde](https://github.com/AI-MDE/spec-kit-preset-mde) |
 | Model Routing Governance | Maps provider-neutral Spec Kit roles to validated harness-local runner profiles without storing model availability, credentials, or machine-specific selections in Git. | 4 templates, 2 commands, 2 scripts | — | [spec-kit-preset-model-routing-governance](https://github.com/hindermath/spec-kit-preset-model-routing-governance) |

specify_cli-1.2.6/docs/integrations/droid.md

@@ -0,0 +1,70 @@
+# Factory Droid
+
+Install [Factory Droid](https://docs.factory.ai/cli/getting-started/overview) before setup.
+The integration key is `droid`.
+
+## Multi-Install Safety
+
+This integration is declared multi-install safe. See the
+[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project).
+
+## Setup
+
+```bash
+specify init my-project --integration droid
+```
+
+For an existing Spec Kit project, use `specify integration install droid`.
+See [integration management](cli.md) for activation, upgrades, and removal.
+
+## Installed Skills
+
+Skills are installed as `.factory/skills/speckit-<command>/SKILL.md`.
+Invoke them in the agent's chat, for example `/speckit-specify` or
+`/speckit-bug-assess` for the installed bug extension.
+
+Generated skills are both user- and model-invocable by default.
+
+## User-Invocable-Only Skills
+
+To stop Droid invoking the core Spec Kit command skills automatically:
+
+```bash
+specify init my-project --integration droid --integration-options="--no-model-invocation"
+```
+
+This writes `disable-model-invocation: true` into the core command skills.
+In Droid 1.0.0 the model no longer lists them among its available skills, so it
+does not run them unprompted, while `/speckit-<command>` and workflow dispatch
+still run them. It is not a hard block: a prompt that names a skill (for
+example "use the speckit-specify skill") still lets the model invoke it through
+its `Skill` tool. Factory's
+[skills documentation](https://docs.factory.com/cli/configuration/skills) does
+not describe this behaviour.
+
+- Extension skills stay model-invocable, because mandatory extension hooks rely
+  on the model invoking them. If an extension's mandatory hook runs a core
+  command (its `command:` is a core `speckit.<command>`), leave this option off:
+  the model cannot run that hook while the core skill is user-invocable only.
+- The option is stored with the integration's other options and reapplied by
+  `specify integration upgrade droid`. Passing `--integration-options` to
+  `upgrade` replaces all stored options; `--integration-options=""` clears
+  them. Re-running `specify init` likewise stores only the options passed to it.
+- Core command skills that a preset overrides, or stops overriding, are reverted
+  to the default by commands that re-register preset skills without reinstalling
+  Droid: commands that install, remove or update presets (including `specify
+  bundle` commands that carry presets), `specify integration use droid`, and
+  `specify integration switch droid` when Droid is installed but not the
+  default. To reapply the option, run `specify integration upgrade droid
+  --force` while Droid is the default integration (`--force` is needed because
+  those commands modify installed skill files, and it overwrites local edits to
+  Spec Kit-managed files).
+
+## Workflow Dispatch
+
+Workflow steps use `droid exec <prompt>`, forwarding `--model` and requesting
+`--output-format json` when appropriate. Spec Kit does not add a
+permission-bypass flag. Operators can explicitly configure permission flags
+through `SPECKIT_INTEGRATION_DROID_EXTRA_ARGS`; those arguments follow Spec
+Kit's model/output flags and may override them under duplicate-flag parsing.
+The only integration-specific setup option is `--no-model-invocation`.

{specify_cli-1.2.5 → specify_cli-1.2.6}/docs/reference/bundles.md

@@ -335,6 +335,11 @@ non-default source.
 
 > **Vet both the bundle source and its component catalogs.** A project can supply its own bundle catalog and `install-allowed` component catalogs (extension, preset, workflow, and step) under `.specify/`; that project configuration existing is not evidence anything in it was reviewed. Before installing a bundle from an unfamiliar project, run `specify bundle catalog list` — and the equivalent `extension`/`preset`/`workflow catalog list` and `specify workflow step catalog list` commands for the components it pulls in — and treat any source you didn't add yourself as unvetted until you've reviewed it.
 
+For workflow components, inspect shell `run` and `env` fields and their
+referenced code, including changes introduced by active overlays. This applies
+even to `strict: true` steps: environment bindings can change executable lookup
+or runtime loading. See [Reviewing shell execution](workflows.md#reviewing-shell-execution).
+
 ### List the Catalog Stack
 
 ```bash

{specify_cli-1.2.5 → specify_cli-1.2.6}/docs/reference/workflows.md

@@ -109,6 +109,56 @@ specify workflow status [<run_id>]
 
 Shows the status of a specific run, or lists all runs if no ID is given. Run states: `created`, `running`, `completed`, `paused`, `failed`, `aborted`.
 
+## Workflow Definition
+
+```bash
+specify workflow definition <run_id> --json
+```
+
+| Option   | Description                                                      |
+| -------- | ---------------------------------------------------------------- |
+| `--json` | Required. Emit the run's workflow definition as a JSON object    |
+
+Returns the workflow definition a run was **started with**, so an integration can render a run (for example the gates it declares and their messages) without drifting from what the engine actually executes. It reads only the run's own persisted data and never the installed workflow: editing or removing the installed workflow does not change the output. Runtime progress and the active gate come from [`specify workflow status --json`](#workflow-status).
+
+Omitting `--json` exits with code `2` and prints a usage message on stderr; no stdout is produced. A text renderer is deferred, so the JSON shape below is the only contract.
+
+```json
+{
+  "run_id": "662bf791",
+  "definition": {
+    "schema_version": "1.0",
+    "workflow": { "id": "spec-review", "name": "Spec review", "version": "1.0.0" },
+    "steps": [
+      { "id": "draft", "type": "command", "command": "speckit.specify" },
+      { "id": "approve", "type": "gate", "message": "Review the specification." }
+    ]
+  },
+  "workflow_scopes": []
+}
+```
+
+- **`definition`** is the workflow as persisted for the run, verbatim and with overlays already applied, so it reflects the steps as executed. Every key is passed through (including `requires`, `outputs` and unknown keys). Nothing is added, renamed or filled in: an omitted field, such as a gate's `options`, means the engine default applies at run time. Expressions (`{{ ... }}`) are not evaluated. The structure follows the [workflow YAML schema](#workflow-yaml-schema), so `schema_version` is the version of this interface and a schema change is a change to it; because `definition` is emitted as authored, an omitted `schema_version` defaults to `"1.0"` and the engine compares `str(schema_version)` (so unquoted `schema_version: 1.0` in YAML appears as the JSON number `1.0`). Keys may be added to the top-level response envelope (`run_id`, `definition`, `workflow_scopes`) in future versions, but existing envelope keys are never removed or renamed.
+- **Plain JSON.** YAML-native values that JSON cannot represent, such as an unquoted date, appear as strings. Binary values (`!!binary`) are not emitted: each appears as a `"<binary: N bytes>"` placeholder, and the value itself stays in the run's snapshot. A set (`!!set`) appears as a list sorted by its JSON form, so the output does not depend on hash randomization. Non-string mapping keys and non-finite numbers are stringified too. Two mapping keys that collapse to the same JSON property name (for example `1` and `"1"`) make the command fail rather than emit lossy JSON. JSON cannot share a reference, so a reused YAML alias (anchor) is duplicated; a recursive alias, or a non-recursive alias graph that expands past a fixed node or output-size budget, fails instead of consuming unbounded CPU, memory and stdout. The budget applies to each definition separately (the root and every entry in `workflow_scopes`), so a run with many bound workflow calls is not rejected for its total size. A separate, much larger limit (32 MiB) caps the whole response, so a loop or fan-out that repeats a large definition fails instead of multiplying it. A non-string mapping key longer than 256 characters once stringified is rejected for the same reason.
+- **`workflow_scopes`** (always present) holds the frozen definition of every [workflow call](#workflow-composition) that has been reached, in execution order. Each entry is `{ "scope_path", "workflow_id", "definition" }`, with `scope_path` and `workflow_id` identical to the values in `status --json`. A call step inside `definition` stays as authored; the callee is never expanded in place. A call that has not been reached yet, or whose target could not be resolved, has no entry, and its definition is never read from the installed workflow. The list grows as calls are reached, and a call inside a loop or fan-out has one entry per iteration or item.
+- **Not included: dynamically generated steps.** The output contains the authored root definition and the frozen definitions of bound workflow calls. Steps that a custom step type generates at run time through `StepResult.next_steps` are persisted in the run's execution state but are not exported, so a gate created that way has no definition in this output. The built-in `if`, `switch`, `while`, `do-while` and `fan-out` steps take their steps from the authored definition and are covered.
+- **`scope_path`** is a list of strings from the root: the authored `id` of every enclosing step (`step-<index>` for a step without an `id`). Containers such as `if`, `switch`, loops and fan-out are elements; each loop iteration and fan-out item adds its index as a string, including the first (`["loop", "0", "call"]`). `workflow_scopes` is always present here, while `status --json` includes it only when the run has workflow calls.
+
+### Matching a gate to its definition
+
+`status --json` reports an active gate as `gate.step_id` and `gate.scope_path`. To find the gate's definition:
+
+1. Read `gate.scope_path` as `[]` when it is missing: `status --json` omits it for a gate directly in the root workflow. Then take the `workflow_scopes` entry with the longest `scope_path` that is a prefix of `gate.scope_path`. If there is none, use the root `definition`. Do not require an exact match: `gate.scope_path` lists every enclosing step, including `if`, `switch`, loops and fan-out containers, while an entry's `scope_path` ends at the call step. A gate in an `if` named `wrap` inside a workflow called by `call`, itself in an `if` named `route`, reports `["route", "call", "wrap"]`, and its entry has `["route", "call"]`.
+2. In that definition, find the step whose `id` equals the authored step ID. In later loop iterations and in fan-out items `step_id` is qualified as `<container>:<id>:<n>` (for example `fan:g:0`); the authored ID is the second-to-last `:`-separated segment, because `:` is not allowed in authored step IDs. Step IDs are unique within a definition except across fan-out templates, which have their own ID namespace: a root step and a fan-out template step may share an ID. If `gate.scope_path` runs through a fan-out step, look only inside that step's `step` template; otherwise ignore fan-out templates. For example, a root shell `g` and a gate `g` in the template of fan-out `fan` both exist, and `fan:g:0` with `scope_path` `["fan", "0"]` is the template's gate, not the root shell.
+
+A gate generated at run time by a custom step has no definition to match; see the note on dynamically generated steps above.
+
+`status --json` does not report per-step status for steps inside called workflows.
+
+### Errors
+
+Failures write a single `{"error": "<message>"}` object to stderr, leave stdout empty and exit with code `1`: not a Spec Kit project, an invalid `SPECIFY_INIT_DIR`, unsafe (including symlinked) workflow storage, an invalid or unknown run ID, an unreadable or too deeply nested run state, a run with no persisted definition (for example one created before definitions were persisted), a corrupt definition or execution state, a definition whose mapping keys collapse to the same JSON property name, and a definition with recursive or too-large-to-expand YAML aliases. Usage errors with `--json` also use this JSON error contract and exit with code `2`.
+
 ## List Installed Workflows
 
 ```bash
@@ -453,7 +503,7 @@ referents, so a pre-existing cache-file symlink can be replaced without changing
 its target. If a cache cannot be safely written, a warning is logged and
 discovery continues using the fetched catalog.
 
-> **A project's `.specify/workflow-catalogs.yml` can point `add` and `search` at a catalog you didn't choose.** Before running a workflow from an unfamiliar project, run `specify workflow catalog list` (and `specify workflow step catalog list` for the step catalogs its steps can pull in) — a project supplying that config is not evidence its workflows or steps were vetted. Maintainers do not audit `run` fields; read a workflow's shell steps yourself before running it (see [Who maintains workflows?](#who-maintains-workflows)).
+> **A project's `.specify/workflow-catalogs.yml` can point `add` and `search` at a catalog you didn't choose.** Before running a workflow from an unfamiliar project, run `specify workflow catalog list` (and `specify workflow step catalog list` for the step catalogs its steps can pull in) — a project supplying that config is not evidence its workflows or steps were vetted. Maintainers do not audit workflow code; review both `run` and `env` in its shell steps yourself, including strict steps (see [Reviewing shell execution](#reviewing-shell-execution) and [Who maintains workflows?](#who-maintains-workflows)).
 
 ### List Catalogs
 
@@ -496,7 +546,7 @@ Catalogs are resolved in this order (first match wins):
 3. **User config** — `~/.specify/workflow-catalogs.yml`
 4. **Built-in defaults** — official catalog + community catalog
 
-## Workflow Definition
+## Workflow YAML Schema
 
 Workflows are defined in YAML files. Here is the built-in **Full SDD Cycle** workflow that ships with Spec Kit:
 
@@ -782,6 +832,32 @@ qualified `step_id`. A step emits completion after its checkpoint; containers
 emit before their children, while replayed completed occurrences emit no step
 events.
 
+### Shell step
+
+`type: shell` executes `run` through the platform shell, retaining support for
+pipes, redirects, and multiple commands. Set `strict: true` to reject `{{`
+expression markers anywhere in `run`, including inside quotes. This is checked
+both during validation and immediately before execution. `strict` must be a
+boolean; omitted or `false` preserves existing raw interpolation behavior.
+
+Use an `env` mapping to bind dynamic values without inserting them into shell
+source. For example, on POSIX:
+
+```yaml
+- id: display-result
+  type: shell
+  strict: true
+  env:
+    RESULT: "{{ steps.plan.output.stdout }}"
+  run: 'printf "%s\n" "$RESULT"'
+```
+
+For cross-platform scripts, read the environment in the program itself, such
+as `os.environ["RESULT"]` in Python. See
+[Shell Step Environment Variables](#shell-step-environment-variables) for the
+binding contract and [Interpolation and shell safety](#interpolation-and-shell-safety)
+for the remaining trust boundary.
+
 > **Security note:** a `shell` step runs a local command with **your** privileges. There is no capability sandbox — `requires` is an advisory pre-condition block (spec-kit version, integrations), not a runtime gate, so it does **not** restrict what a step can do. In particular there is no `requires.permissions` capability gate: it is rejected by validation precisely because it would imply a sandbox that does not exist. Review any catalog or downloaded workflow before running it, and use a `gate` step to require explicit approval before sensitive or destructive shell commands.
 
 ### GitHub step
@@ -1237,9 +1313,11 @@ If an interpolated value can contain characters like `;`, `|`, `&`, `$( )`, back
 - **Workflow `inputs.*`** — supplied by whoever runs the workflow.
 - **A prior step's output**, e.g. `{{ steps.plan.output.stdout }}` — for a `command` or `prompt` step with [`capture: true`](#capturing-command-and-prompt-output) this is **text produced by the AI agent**, which can in turn be influenced by files, tickets, or web content the agent read. Treat agent output as untrusted when it flows into a `shell` step.
 
-There is **no shell-escaping filter** in the expression language and **no sandbox** around a `shell` step, so none of the practices below can be treated as a guarantee that a hostile value is neutralised. The only reliable control is to constrain what an interpolated value *can* be, and to keep values you cannot constrain out of `run` fields entirely. Scrutinise every `run` field that interpolates a value you do not control, and at minimum:
+There is **no shell-escaping filter** in the expression language and **no sandbox** around a `shell` step. Prefer [`strict: true`](#shell-step) with `env` bindings to keep dynamic values out of shell source. Strict mode does not sanitise data, inspect commands, or prevent an authored script from interpreting data as code. Do not use `eval`, build another `sh -c` command from a variable, or pass untrusted values through shell startup variables such as `BASH_ENV`. On Windows, `cmd.exe` expansion of `%VALUE%` can introduce shell syntax; read untrusted values inside a program instead. On POSIX, quote variable expansions and use the target program's argument validation or `--` where appropriate to prevent option injection.
 
-- **Constrain the value at the source with `enum`/an allowlist.** When `inputs.*` feeds a `run` field, restrict it to a fixed set of known-safe values so a caller cannot supply arbitrary shell text at all. This is the strongest control the engine offers — prefer it over any downstream mitigation.
+For compatibility, raw interpolation remains enabled when `strict` is omitted or `false`. Its injection risk remains unchanged. Keep values you cannot constrain out of `run` fields entirely. Scrutinise every non-strict `run` field that interpolates a value you do not control, and at minimum:
+
+- **Constrain the value at the source with `enum`/an allowlist.** When `inputs.*` feeds a non-strict `run` field, restrict it to a fixed set of known-safe values so a caller cannot supply arbitrary shell text at all.
 
   ```yaml
   inputs:
@@ -1262,6 +1340,60 @@ Shell steps automatically receive the following environment variables:
 | -------- | ----------- |
 | `SPECKIT_WORKFLOW_DIR` | Resolved absolute path to the workflow source directory (same value as `{{ context.workflow_dir }}`). Not set when the workflow has no source path. |
 
+An optional per-step `env` mapping is available in both strict and non-strict
+mode. Names must match `[A-Za-z_][A-Za-z0-9_]*`; names are literal, not
+expressions. Values must be strings and may contain workflow expressions.
+Each value is evaluated once and must resolve to a string without NUL
+characters. On POSIX, the string must also be encodable for the process
+environment using the filesystem encoding and its error handler.
+Invalid bindings fail the step before launching a process.
+
+Single-expression bindings preserve the expression's result type:
+`COUNT: "{{ inputs.count }}"` rejects a number, boolean, null, list, or mapping
+instead of converting it to text. Mixed templates use standard expression
+interpolation: `COUNT: "n={{ inputs.count }}"` produces `n=42` for integer
+`42`; embedded null becomes empty text, and other values use their string
+representation. To serialize structured data explicitly, use `to_json`.
+
+Bindings override inherited environment values for that subprocess only;
+they do not modify the parent process or subsequent steps. An empty string is
+valid. `SPECKIT_WORKFLOW_DIR` is reserved (case-insensitively) and cannot be
+overridden. Keep environment names and executable-loading settings under the
+workflow author's control: environment binding is a data channel, not a sandbox.
+
+### Reviewing shell execution
+
+Before installing or running an unfamiliar workflow, audit each shell step's
+`run` **and** `env`, including nested branches and fan-out templates. Review
+referenced scripts and resources, called workflows, and active overlay YAML
+that can replace or insert steps. Apply the same review to workflow components
+of bundles, and repeat it when definitions, overlays, or referenced code change.
+Custom step packages require their own source review because loading them
+executes Python code.
+
+An environment value can control execution rather than merely supply data.
+For example, `PATH` selects executables, `PYTHONPATH` affects Python imports,
+`BASH_ENV` can select Bash startup code, and `NODE_OPTIONS` can change Node.js
+startup behavior. Native loaders and other programs have their own settings;
+these examples are not an exhaustive list. A fixed `run` can therefore execute
+different code even with `strict: true` and no `eval`. Strict mode neither
+filters execution-controlling bindings nor cleans the inherited environment.
+Keep those settings literal and author-vetted, or constrain dynamic values to
+an approved set of trusted paths/options. Use unconstrained input or agent
+output only for application-data variables whose consumers handle it as data.
+
+When a shell step invokes Specify itself, catalog overrides such as
+`SPECKIT_WORKFLOW_CATALOG_URL` can also change where child commands discover
+or install components. Vet those bindings alongside the
+[active catalog sources](catalogs.md#discovery-and-trust).
+
+Workflow validation checks configuration, not whether environment settings or
+commands are safe. `specify workflow info` shows metadata and step identities;
+`specify workflow resolve` shows layer and step attribution. Neither displays
+the complete `run`/`env` configuration or replaces reading the contributing
+source files. Catalog install permission, bundle installation, and strict mode
+are not security endorsements.
+
 ## Input Types
 
 | Type      | Coercion                                          |

{specify_cli-1.2.5 → specify_cli-1.2.6}/docs/toc.yml

@@ -143,6 +143,8 @@
       href: extensions/overview.md
     - name: Developing
       href: extensions/developing.md
+    - name: API Reference
+      href: extensions/api.md
     - name: Publishing
       href: extensions/publishing.md
 

{specify_cli-1.2.5 → specify_cli-1.2.6}/extensions/assess/README.md

@@ -2,7 +2,7 @@
 
 A five-stage assessment pipeline for Spec Kit that turns **any idea** into a defensible **go / needs-clarification / kill** decision *before* it enters Spec-Driven Development. It is the missing **discovery track** that sits in front of the SDD **delivery track** (`specify → clarify → plan → tasks → analyze → implement`).
 
-Discovery answers *"is this worth building?"* Delivery answers *"how do we build it?"* Only ideas that survive assessment hand off to `/speckit.specify`.
+Discovery answers *"is this worth building?"* Delivery answers *"how do we build it?"* Only ideas that survive assessment hand off to `/speckit-specify`.
 
 ## Overview
 
@@ -12,11 +12,11 @@ Each idea lives in its own directory under `.specify/assessments/<slug>/`, with
 
 ```
 .specify/assessments/<slug>/
-├── intake.md      # speckit.assess.intake   — capture the raw idea
-├── research.md    # speckit.assess.research — gather (and challenge with) evidence
-├── problem.md     # speckit.assess.define   — define the problem, goals, metrics
-├── concept.md     # speckit.assess.shape    — shape solution options + appetite
-└── decision.md    # speckit.assess.decide   — go / needs-clarification / kill → handoff
+├── intake.md      # /speckit-assess-intake   — capture the raw idea
+├── research.md    # /speckit-assess-research — gather (and challenge with) evidence
+├── problem.md     # /speckit-assess-define   — define the problem, goals, metrics
+├── concept.md     # /speckit-assess-shape    — shape solution options + appetite
+└── decision.md    # /speckit-assess-decide   — go / needs-clarification / kill → handoff
 ```
 
 The pipeline is a **funnel**: most ideas should be killed or parked before `shape`. Killing an idea with a documented reason is a successful outcome, not a failure.
@@ -24,7 +24,7 @@ The pipeline is a **funnel**: most ideas should be killed or parked before `shap
 ```mermaid
 flowchart LR
     A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}
-    C -->|go| SPEC[/speckit.specify/]
+    C -->|go| SPEC[/"/speckit-specify"/]
     C -->|kill| X[closed, recorded]
     C -.->|needs-clarification| F[refine named artifact in place]
     F -.->|then revise decision.md| C
@@ -32,13 +32,17 @@ flowchart LR
 
 ## Commands
 
+Slash commands in this README use GitHub Copilot's default skills syntax.
+For another agent, use its
+[equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation).
+
 | Command | Stage | Output |
 |---------|-------|--------|
-| `speckit.assess.intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |
-| `speckit.assess.research` | Gather users/market/prior-art/data evidence — and evidence *against* the idea. | `research.md` |
-| `speckit.assess.define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |
-| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |
-| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |
+| `/speckit-assess-intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |
+| `/speckit-assess-research` | Gather users/market/prior-art/data evidence — and evidence *against* the idea. | `research.md` |
+| `/speckit-assess-define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |
+| `/speckit-assess-shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |
+| `/speckit-assess-decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit-specify`. | `decision.md` |
 
 Stages are meant to run in order but are not rigidly gated:
 
@@ -65,14 +69,14 @@ Then ask whether the new information clears the blocker and to update any downst
 
 When you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.
 
-Rerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
+Rerunning an earlier assessment command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
 
 ## Slug Conventions
 
 A *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.
 
 - **User-provided**: normalized to lowercase kebab-case (e.g. `offline-mode`, `cut-onboarding-friction`). Preserved verbatim after normalization — no timestamps or numbers appended.
-- **Asked for**: in interactive use, `speckit.assess.intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.
+- **Asked for**: in interactive use, `/speckit-assess-intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.
 - **Automated**: when no human is available, the agent generates a unique slug and never overwrites an existing assessment directory (appending `-2`, `-3`, … or a short date as needed).
 - **Reuse from context**: later stages reuse the slug reported earlier in the same session, confirmed by the presence of the assessment directory.
 
@@ -91,31 +95,37 @@ specify extension enable assess
 
 ## Typical Flow
 
-```bash
+Run these skills in your agent's chat, not your terminal, one at a time,
+reviewing each result before continuing.
+
+This example uses GitHub Copilot's default skills syntax. For another agent,
+use its [equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation).
+
+```text
 # 1. Capture an idea (pasted text, a URL, or "assess this repo")
-/speckit.assess.intake "Let users work offline and sync when they reconnect" slug=offline-mode
+/speckit-assess-intake "Let users work offline and sync when they reconnect" slug=offline-mode
 
 # 2. Gather evidence — and reasons it might not be worth it
-/speckit.assess.research slug=offline-mode
+/speckit-assess-research slug=offline-mode
 
 # 3. Define the actual problem
-/speckit.assess.define slug=offline-mode
+/speckit-assess-define slug=offline-mode
 
 # 4. Shape 2–3 concept options with appetites
-/speckit.assess.shape slug=offline-mode
+/speckit-assess-shape slug=offline-mode
 
 # 5. Decide — go, clarify, or kill
-/speckit.assess.decide slug=offline-mode
-# → on "go", hand the decision.md handoff summary to /speckit.specify
+/speckit-assess-decide slug=offline-mode
+# → on "go", optionally pass the decision.md handoff summary to /speckit-specify
 ```
 
 ## Handoff
 
-`assess` is a **standalone pipeline you enter deliberately** — it registers no lifecycle hooks and never inserts itself into `/speckit.specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit.assess.decide` hands its `decision.md` summary to `/speckit.specify`. Discovery and specification stay separate processes.
+`assess` is a **standalone pipeline you enter deliberately** — it registers no lifecycle hooks and never inserts itself into `/speckit-specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit-assess-decide` hands its `decision.md` summary to `/speckit-specify`. Discovery and specification stay separate processes.
 
 ## Guardrails
 
-- Only `speckit.assess.*` commands write, and only inside `.specify/assessments/<slug>/`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).
+- Only the five assessment commands write, and only inside `.specify/assessments/<slug>/`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit-specify` onward).
 - Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).
 - Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.
 - Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.
@@ -124,4 +134,4 @@ specify extension enable assess
 
 ## Relationship to Other Extensions
 
-`assess` is deliberately the **generic, role-neutral** discovery track — usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit.specify` handoff.
+`assess` is deliberately the **generic, role-neutral** discovery track — usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit-specify` handoff.

{specify_cli-1.2.5 → specify_cli-1.2.6}/extensions/assess/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: assess
   name: "Idea Assessment Pipeline"
-  version: "1.0.1"
+  version: "1.0.2"
   description: "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/"
   category: "process"
   effect: "read-write"

{specify_cli-1.2.5 → specify_cli-1.2.6}/extensions/bug/README.md

@@ -99,4 +99,4 @@ hooks:
       description: Collect evidence in the resolved bug directory
 ```
 
-Mandatory hooks are invoked and awaited; optional hooks are presented for the user to run. Disabled hooks and hooks with non-empty conditions are skipped by the command templates. With no registered hooks, the workflow proceeds as before. See the [Extension API Reference](../EXTENSION-API-REFERENCE.md#hook-events) for the shared hook contract.
+Mandatory hooks are invoked and awaited; optional hooks are presented for the user to run. Disabled hooks and hooks with non-empty conditions are skipped by the command templates. With no registered hooks, the workflow proceeds as before. See the [Extension API Reference](https://github.github.io/spec-kit/extensions/api.html#hook-events) for the shared hook contract.

{specify_cli-1.2.5 → specify_cli-1.2.6}/extensions/bug/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: bug
   name: "Bug Triage Workflow"
-  version: "1.0.1"
+  version: "1.0.2"
   description: "Assess, fix, and validate bug reports against the codebase with per-bug reports stored under .specify/bugs/<slug>/"
   author: spec-kit-core
   repository: https://github.com/github/spec-kit