[Feature]: Let extensions contribute always-on instructions (not just on-demand commands + hooks)
- Langage dominant
- Python
- Étoiles
- 137k
- Forks
- 12.3k
- Merge moyen
- 2 j 12 h
- PR mergées (30 j)
- 159
Description
### 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.
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
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.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- python, yaml
- Domaine
- cli, documentation, tooling
- Type d'issue
- Fonctionnalité
- Difficulté
- 5/5
- Temps estimé
- Plus d'une semaine
- Activité
- Active
- Clarté
- Plutôt claire
- Accessibilité débutants
- 38/100