[Feature]: Let extensions contribute always-on instructions (not just on-demand commands + hooks)
- Lenguaje dominante
- Python
- Estrellas
- 137k
- Forks
- 12.3k
- Merge medio
- 2 d 12 h
- PR fusionados (30 d)
- 159
Descripción
### 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:
```yaml
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.
Guía de contribución
Línea de trabajo
Start by tracing the extension manifest schema and the `specify extension add` and uninstall/update entry points, then compare the existing `speckit.json` merge markers and `.specify/memory/constitution.md` handling. Review the proposed agent targets, including `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `.cursor/rules/`. Done means instructions are schema-validated, routed and merged safely, removable, opt-out capable, and documented across supported agents.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- python, yaml
- Área
- cli, documentation, tooling
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 38/100