[Feature]: Let extensions contribute always-on instructions (not just on-demand commands + hooks)
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 38/100
- Issue 类型
- 功能
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- python, yaml
- 领域
- cli, documentation, tooling
调研方向
首先追踪扩展清单的 schema 以及 specify extension add 和卸载/更新入口,然后比较 speckit.json 中现有的合并标记与 .specify/memory/constitution.md 的处理方式。审查提议的 agent 目标,包括 .github/copilot-instructions.md、AGENTS.md、CLAUDE.md、GEMINI.md 和 .cursor/rules/。当指令经过 schema 验证、被安全地路由和合并、可移除、支持选择退出,并且已针对所有受支持的 agent 编写文档时,即视为完成。
由索引模型根据 Issue 内容生成。
描述
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
- A domain extension (e.g. Azure Cosmos DB) wants its few mandatory best-practices followed even when an autonomous agent never runs a command.
- A security / hardening extension wants "always apply these secure-coding rules" in context for every generation.
- An IaC / framework / accessibility extension wants its house style enforced across a whole session without the user or agent invoking anything.
- 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 addinstalls 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.
- 主要语言
- Python
- 星标
- 138k
- 派生
- 12.4k
- 平均合并
- 3 天 2 小时
- 30 天内合并 PR
- 169
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
github/spec-kit 的其他 Issue
-
enhancement needs-triage triage-can-wait
难度 2/5 1-3 小时 新手友好度 65/100
-
preset-submission triage-must-have validation-passed
难度 2/5 1-3 小时 新手友好度 75/100
-
extension-submission triage-must-have validation-passed
难度 2/5 1-3 小时 新手友好度 70/100
-
extension-submission triage-can-wait validation-passed
难度 2/5 1-3 小时 新手友好度 76/100
-
enhancement needs-triage triage-can-wait
难度 2/5 1-3 小时 新手友好度 65/100
相似的 Issue
-
bug
难度 2/5 1-3 小时 新手友好度 75/100
stephrobert/dsoxlab#238 ·
-
难度 2/5 1-3 小时 新手友好度 75/100
-
难度 2/5 1-3 小时 新手友好度 75/100
sublimehq/package_control#1780 ·
-
难度 2/5 1-3 小时 新手友好度 65/100
-
难度 2/5 1-3 小时 新手友好度 70/100
nwg-piotr/nwg-displays#145 ·