mirror of
https://github.com/github/spec-kit.git
synced 2026-07-06 22:32:13 +08:00
bbdf1b8f40
* fix(agent-context): support multiple context files safely * fix(agent-context): harden context file validation * fix(agent-context): preserve disabled context target * fix(agent-context): address review follow-ups * fix(agent-context): dedupe PowerShell context files * fix(agent-context): align context file dedupe * fix(agent-context): align bash context file dedupe * fix(agent-context): preserve disabled display target * fix(agent-context): require yaml-capable updater python * fix(agent-context): preserve context files config * fix(agent-context): align context file fallbacks * fix(agent-context): share context file resolution --------- Co-authored-by: AustinZ21 <AustinZ21@users.noreply.github.com>
67 lines
3.3 KiB
Markdown
67 lines
3.3 KiB
Markdown
# Coding Agent Context Extension
|
|
|
|
This bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.
|
|
|
|
It owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `<!-- SPECKIT START -->` / `<!-- SPECKIT END -->`).
|
|
|
|
## Why an extension?
|
|
|
|
Not every Spec Kit user wants Spec Kit to write into the coding agent's context file. Extracting this behavior into a dedicated extension lets users:
|
|
|
|
- **Opt out** entirely with `specify extension disable agent-context` — Spec Kit will then never create or modify the agent context file.
|
|
- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` — both the Python layer and the bundled scripts honor the same `context_markers` value.
|
|
- **Synchronize multiple agent anchors** by setting `context_files` when a project intentionally uses more than one coding agent context file, such as `AGENTS.md` and `CLAUDE.md`.
|
|
- **Refresh on demand** with `/speckit.agent-context.update`, or automatically through the hooks declared in `extension.yml` (`after_specify`, `after_plan`).
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |
|
|
|
|
## Configuration
|
|
|
|
All configuration flows through the extension's own config file at
|
|
`.specify/extensions/agent-context/agent-context-config.yml`:
|
|
|
|
```yaml
|
|
# Path to the coding agent context file managed by this extension
|
|
context_file: CLAUDE.md
|
|
|
|
# Optional list of coding agent context files to manage together.
|
|
# When non-empty, this takes precedence over context_file.
|
|
context_files:
|
|
- AGENTS.md
|
|
- CLAUDE.md
|
|
|
|
# Delimiters for the managed Spec Kit section
|
|
context_markers:
|
|
start: "<!-- SPECKIT START -->"
|
|
end: "<!-- SPECKIT END -->"
|
|
```
|
|
|
|
- `context_file` — the project-relative path to the coding agent context file, written by `specify init` and `specify integration install`.
|
|
- `context_files` — optional project-relative paths to multiple coding agent context files. When non-empty, the list takes precedence over `context_file`. Absolute paths, backslash separators, and `..` path segments are rejected.
|
|
- `context_markers.start` / `.end` — the delimiters around the managed section. Edit these to use custom markers.
|
|
|
|
## Requirements
|
|
|
|
The bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).
|
|
|
|
PyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports *"PyYAML is required … not available in the current Python environment"*, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:
|
|
|
|
```bash
|
|
pip install pyyaml
|
|
# or target the specific interpreter Spec Kit uses:
|
|
/path/to/speckit-python -m pip install pyyaml
|
|
```
|
|
|
|
## Disable
|
|
|
|
```bash
|
|
specify extension disable agent-context
|
|
```
|
|
|
|
When disabled, Spec Kit skips context file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
|
|
Disabled projects also ignore stale `context_files` values during command rendering so disabling the extension remains a complete opt-out.
|