Problem Statement
Spec Kit extensions can deliver knowledge only two ways today: commands (on-demand prompts/skills the agent must choose to invoke) and hooks (fire around /speckit.implement). Both are opt-in by the agent. So in autonomous / hands-off workflows - increasingly the common case - an extension's guidance often never reaches the model: the agent is given a task, writes code directly, and never invokes the commands, so the extension has no effect.
We hit this building the Azure Cosmos DB Spec Kit extension (pre-release, still in active development). In autonomous agent runs where it was installed exactly as intended, the agent invoked its commands in 0 of 30 runs and the before_implement/after_implement hooks fired 0 times - net effect ≈ zero. There is currently no way for an extension to contribute always-on guidance (a few "always apply this while you work" rules in the agent's persistent context) the way the project constitution does.
Proposed Solution
Add an optional provides: instructions: capability to the extension manifest, so an extension can ship a compact always-on rule block that specify extension add installs into the agent-native always-on file for the active integration:
provides:
commands: [ ... ] # unchanged
hooks: [ ... ] # unchanged
instructions: # NEW
- file: instructions/best-practices.md
Install it as a delimited, per-extension block so it is merge-safe (multiple extensions coexist; user-authored content preserved), idempotent, removable on uninstall, and routed per agent (.github/copilot-instructions.md for Copilot; AGENTS.md / CLAUDE.md / GEMINI.md; .cursor/rules/…) - or appended to .specify/memory/constitution.md if a single canonical target is preferred.
This looks very feasible because Spec Kit already has the building blocks and would reuse all three rather than invent a subsystem: an always-on context concept (the constitution), per-agent routing, and merge-with-markers for extension content (hooks -> speckit.json).
Evidence it matters: delivering the same guidance as an always-on rule block instead of commands improved a best-practice conformance score by +0.16 mean (vs +0.10 as commands), with better determinism and improvement in every measured cell (2 models × 4 languages × 3 complexity levels) - because always-on context can't be bypassed.
Alternatives Considered
- A hook that writes the always-on file at
before_implement. Unreliable: agents load instruction files at session start, so writing mid-session isn't picked up; also couples always-on context to the implement step.
- Docs-only ("paste these rules into your copilot-instructions.md"). Manual, easily skipped, not portable across agents, and defeats the point of an extension.
- Status quo (everything as commands/hooks). Proven not to reach autonomous agents (the 0/30 invocation above).
Component
Specify CLI (initialization, commands)
AI Agent (if applicable)
All agents
Use Cases
- A domain extension (e.g. Azure Cosmos DB) wants its few mandatory best-practices followed even when an autonomous agent never runs a command.
- A security / hardening extension wants "always apply these secure-coding rules" in context for every generation.
- An IaC / framework / accessibility extension wants its house style enforced across a whole session without the user or agent invoking anything.
- A team installs several extensions and wants each one's key rules merged, attributed, and cleanly removable, alongside their own project constitution.
Acceptance Criteria
Additional Context
- General gap, not Cosmos-specific. Any extension whose value is best-practice guidance (security, IaC, API-design, framework, accessibility, …) hits the same wall - commands only help if the agent opts to run them. Azure Cosmos DB is just where we measured it.
- Design notes (input welcome): keep instructions compact — always-on text costs tokens on every request, so a soft size cap / lint is worth considering; user-authored instructions and the constitution should take precedence over extension blocks; ensure deterministic ordering; support opt-out.
- Forward-looking: the extension that surfaced this is still pre-release; we want to align its delivery model with Spec Kit's direction before shipping broadly - this is not a report of a regression in a shipped extension.
- We have the full delivery-mechanism A/B data (models × languages × complexity) and a reference compact rule block, and are happy to share or prototype the capability.
Problem Statement
Spec Kit extensions can deliver knowledge only two ways today: commands (on-demand prompts/skills the agent must choose to invoke) and hooks (fire around
/speckit.implement). Both are opt-in by the agent. So in autonomous / hands-off workflows - increasingly the common case - an extension's guidance often never reaches the model: the agent is given a task, writes code directly, and never invokes the commands, so the extension has no effect.We hit this building the Azure Cosmos DB Spec Kit extension (pre-release, still in active development). In autonomous agent runs where it was installed exactly as intended, the agent invoked its commands in 0 of 30 runs and the
before_implement/after_implementhooks fired 0 times - net effect ≈ zero. There is currently no way for an extension to contribute always-on guidance (a few "always apply this while you work" rules in the agent's persistent context) the way the project constitution does.Proposed Solution
Add an optional
provides: instructions:capability to the extension manifest, so an extension can ship a compact always-on rule block thatspecify extension addinstalls into the agent-native always-on file for the active integration:Install it as a delimited, per-extension block so it is merge-safe (multiple extensions coexist; user-authored content preserved), idempotent, removable on uninstall, and routed per agent (
.github/copilot-instructions.mdfor Copilot;AGENTS.md/CLAUDE.md/GEMINI.md;.cursor/rules/…) - or appended to.specify/memory/constitution.mdif a single canonical target is preferred.This looks very feasible because Spec Kit already has the building blocks and would reuse all three rather than invent a subsystem: an always-on context concept (the constitution), per-agent routing, and merge-with-markers for extension content (hooks ->
speckit.json).Evidence it matters: delivering the same guidance as an always-on rule block instead of commands improved a best-practice conformance score by +0.16 mean (vs +0.10 as commands), with better determinism and improvement in every measured cell (2 models × 4 languages × 3 complexity levels) - because always-on context can't be bypassed.
Alternatives Considered
before_implement. Unreliable: agents load instruction files at session start, so writing mid-session isn't picked up; also couples always-on context to the implement step.Component
Specify CLI (initialization, commands)
AI Agent (if applicable)
All agents
Use Cases
Acceptance Criteria
provides: instructions:is accepted in the extension manifest schema.specify extension addinstalls each instructions file into the correct always-on location for the active integration.Additional Context