Skip to content

[Feature]: Let extensions contribute always-on instructions (not just on-demand commands + hooks) #4200

Description

@TheovanKraay

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

  1. A domain extension (e.g. Azure Cosmos DB) wants its few mandatory best-practices followed even when an autonomous agent never runs a command.
  2. A security / hardening extension wants "always apply these secure-coding rules" in context for every generation.
  3. An IaC / framework / accessibility extension wants its house style enforced across a whole session without the user or agent invoking anything.
  4. A team installs several extensions and wants each one's key rules merged, attributed, and cleanly removable, alongside their own project constitution.

Acceptance Criteria

  • provides: instructions: is accepted in the extension manifest schema.
  • specify extension add installs each instructions file into the correct always-on location for the active integration.
  • Content is written as a delimited, attributed block that merges safely with user content and with other extensions.
  • Uninstall / update cleanly removes or replaces the extension's block.
  • Users can disable extension-provided instructions (globally or per extension).
  • Works across supported agents (or a documented no-op where an agent has no always-on file).
  • Documentation updated.

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementfeature-assessRun the Spec Kit idea-assessment pipeline on this feature requestfeature-needs-clarificationFeature assessment verdict: needs clarification

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions