github / github/spec-kit

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

Đang mở
#4,200 11 bình luận 0 reaction 0 người được giao Xem trên GitHub
enhancement feature-assess feature-needs-clarification triage-can-wait
Ngôn ngữ chính
Python
Star
137k
Fork
12.3k
Merge trung bình
2 ngày 12 giờ
Pull request đã merge (30 ngày)
159

Mô tả

### 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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu bằng cách truy vết schema của extension manifest và các entry point `specify extension add` cùng các entry point gỡ cài đặt/cập nhật, sau đó so sánh các merge marker hiện có trong `speckit.json` và cách xử lý `.specify/memory/constitution.md`. Xem xét các đích agent được đề xuất, bao gồm `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` và `.cursor/rules/`. Được xem là hoàn tất khi các instruction được xác thực theo schema, được định tuyến và merge an toàn, có thể gỡ bỏ, hỗ trợ opt-out và được ghi lại tài liệu cho tất cả agent được hỗ trợ.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python, yaml
Lĩnh vực
cli, documentation, tooling
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
38/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.