[Feature]: Let extensions contribute always-on instructions (not just on-demand commands + hooks)
- 主要言語
- Python
- スター
- 137k
- フォーク
- 12.3k
- 平均マージ
- 2日 12時間
- マージ済み PR(30日)
- 159
説明
### 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.
コントリビューションガイド
調査の方向性
まず拡張機能マニフェストのスキーマと、`specify extension add` およびアンインストール/更新のエントリポイントを追跡し、次に既存の `speckit.json` のマージマーカーと `.specify/memory/constitution.md` の扱いを比較します。`.github/copilot-instructions.md`、`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.cursor/rules/` を含む、提案されたエージェントの対象を確認します。完了とは、指示がスキーマ検証され、安全にルーティングおよびマージされ、削除可能で、オプトアウト可能であり、サポート対象のすべてのエージェントについて文書化されていることを意味します。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- python, yaml
- 領域
- cli, documentation, tooling
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 活発
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 38/100