github / github/spec-kit

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

オープン
#4,200 コメント 11 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement feature-assess feature-needs-clarification triage-can-wait
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。