Skip to content

docs(extensions): clarify agent-context README and add config examples #3389

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yanukadeneth99 wants to merge 3 commits into
base: main
Choose a base branch
from
+51 −30
Open

docs(extensions): clarify agent-context README and add config examples #3389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
18ce4a7
docs(extensions): clarify agent-context README and add config examples
yanukadeneth99 Jul 7, 2026
3379a45
docs(agent-context): clarify config documentation
yanukadeneth99 Jul 8, 2026
d73fc9f
docs(agent-context): fix GitHub casing, clarify config
yanukadeneth99 Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 36 additions & 19 deletions extensions/agent-context/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,50 @@

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 -->`).
It owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `<!-- SPECKIT START -->` / `<!-- SPECKIT END -->`). Everything else is untouched.

> NOTE: Spec Kit itself never touches your agent context file. This extension is the only thing that does, and it's opt-in: install it if you want the block kept in sync, skip it if you'd rather manage that file yourself.

## Why an extension?

Not every Spec Kit user wants Spec Kit to write into the coding agent's context file. Keeping this behavior in a dedicated, **opt-in** extension lets users:

- **Choose whether to install it at all** — `specify init` does not install it. Add it explicitly when you want Spec Kit to manage the agent context file; if it is absent or disabled, Spec Kit never creates or modifies that file.
- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` — the bundled scripts honor the `context_markers` value.
- **Choose whether to install it at all** - `specify init` does **NOT** install it. Add it explicitly when you want Spec Kit to manage the agent context file; if it is absent or disabled, Spec Kit never creates or modifies that file (the AI context file).
- **Customize the markers** by editing [agent-context-config.yml](./agent-context-config.yml) - the bundled scripts honor the `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** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in `extension.yml` (`after_specify`, `after_plan`). Invoke it using your agent's slash-command separator — `/speckit.agent-context.update` for dot-separator agents or `/speckit-agent-context-update` for hyphen-separator agents (e.g. Forge, Cline).
- **Refresh on demand** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in [extension.yml](./extension.yml) (`after_specify`, `after_plan`).

## Commands
## Installation

To install the extension, run the following command after installing Spec Kit.

```bash
specify extension add agent-context
```

The command ID below is canonical. When invoking it as a slash command, use your agent's separator: `/speckit.agent-context.update` for dot-separator agents or `/speckit-agent-context-update` for hyphen-separator agents (e.g. Forge, Cline).
## Disabling

| Command | Description |
|---------|-------------|
```bash
specify extension disable agent-context

# Re-enable it
specify extension enable agent-context
```

While this extension is disabled (or not installed), nothing in Spec Kit creates, updates, or removes the managed block - the `__CONTEXT_FILE__` placeholder in any template is left as-is, and the extension's own config is never read.

## Commands

| Command | Description |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |

> NOTE: The command ID above is canonical. When invoking it as a slash command, use your agent's separator: `/speckit.agent-context.update` for dot-separator agents or `/speckit-agent-context-update` for hyphen-separator agents (e.g. Forge, Cline).

## Configuration

All configuration flows through the extension's own config file at
`.specify/extensions/agent-context/agent-context-config.yml`:
[agent-context-config.yml](./agent-context-config.yml):

```yaml
# Path to the coding agent context file managed by this extension
Comment on lines 47 to 51
Expand All @@ -42,26 +63,22 @@ context_markers:
end: "<!-- SPECKIT END -->"
```

- `context_file` — the project-relative path to the coding agent context file. When empty, the bundled update scripts self-seed it by looking up the active integration's key in this extension's own `agent-context-defaults.json` map. The Specify CLI is never consulted.
- `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.
- `context_file` - the project-relative path to the coding agent context file. When empty, the bundled update scripts self-seed it by looking up the active integration's key in this extension's own `agent-context-defaults.json` map. The Specify CLI is never consulted.
- `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:
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
```
## Issues

When disabled (or never installed), Spec Kit performs no agent context file creation, updates, or removal — the extension's bundled scripts are the only code that ever touches the managed section. The Specify CLI carries no agent-context state at all: it never reads this config, never resolves a context file, and the `__CONTEXT_FILE__` placeholder (if present in any template) is left untouched. All context-file knowledge — including the per-agent default mapping in `agent-context-defaults.json` — lives entirely within this extension, so disabling it is a complete opt-out.
For any other issues, please create an issue in the [official GitHub repo](https://github.com/github/spec-kit/issues).
26 changes: 15 additions & 11 deletions extensions/agent-context/agent-context-config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,24 @@
# Coding Agent Context Extension Configuration
# These values are populated automatically by `specify init` and
# `specify integration use` / `specify integration install`.

# Path (relative to the project root) to the default coding agent context file
# managed by this extension (e.g. CLAUDE.md, AGENTS.md,
# .github/copilot-instructions.md). Set automatically from the active
# integration and regenerated during `specify init` or integration switches.
# WHAT: Single project relative path to the main coding agent context file.
# REQUIREMENT: OPTIONAL. Use this if you want to manually specify a single context file. If you leave this entry blank, it will use the default context file for the coding agent you picked when you set up Spec Kit. See `agent-context-defaults.json` for the defaults.
# EXAMPLE: context_file: CLAUDE.md

@mnriem mnriem Jul 7, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The # EXAMPLE: context_file: CLAUDE.md here reads as if context_file is something you're expected to fill in. But empty is the intended default — that's what triggers the self-seed from agent-context-defaults.json based on the active integration. If someone copies the example and pins CLAUDE.md, they've overridden the auto-resolution, so switching agents later (e.g. to Copilot) will keep writing the managed block to CLAUDE.md instead of .github/copilot-instructions.md.

Could we reframe it so it's clear this is an override, not a required value? Something like:

# Leave empty to auto-resolve from the active integration (recommended).
# Only set this to override the auto-detected file, e.g.:
#   context_file: CLAUDE.md
context_file: ""

The context_files example below is fine as-is, since multi-anchor sync genuinely requires the user to list paths explicitly.

@yanukadeneth99 yanukadeneth99 Jul 8, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, and that makes sense.

I updated the whole document to make things clearer. Hope this is all good @mnriem

Let me know if you want me to take a look again.

context_file: ""

# Optional list of project-relative coding agent context files managed by this
# extension. When non-empty, this list takes precedence over `context_file`.
# Use this for projects that intentionally keep multiple agent anchors in sync.
# WHAT: List of project relative paths to the coding agent context files. If you have both `context_file` and `context_files` filled, then this(`context_files`) takes precedence.
# REQUIREMENT: OPTIONAL. Use this if your project requires you to keep multiple agent context files in sync.
# EXAMPLE:
# context_files:
# - AGENTS.md
# - CLAUDE.md
context_files: []

# Delimiters for the managed Spec Kit section.
# Edit these to use custom markers.
# WHAT: Markers (Delimiters) for the managed Spec Kit section. All information injected by this extension will only be done in between these markers.
# REQUIREMENT: REQUIRED. Only change if you wish to have a custom marker name.
# EXAMPLE:
# context_markers:
# start: "<!-- AGENT SPEC KIT CONTEXT START -->"
# end: "<!-- AGENT SPEC KIT CONTEXT END -->"
Comment on lines +18 to +21
context_markers:
start: "<!-- SPECKIT START -->"
end: "<!-- SPECKIT END -->"
Loading