From 18ce4a715da47c25476af31f405be18fcf4827e5 Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Tue, 7 Jul 2026 10:35:33 +0530 Subject: [PATCH 1/7] docs(extensions): clarify agent-context README and add config examples Rewrite the agent-context extension README to read as plain prose instead of a bullet dump, and add the missing install/disable commands (specify extension add/disable/enable agent-context). Add inline example comments to agent-context-config.yml for context_file/context_files. --- extensions/agent-context/README.md | 55 ++++++++++++------- .../agent-context/agent-context-config.yml | 5 ++ 2 files changed, 41 insertions(+), 19 deletions(-) diff --git a/extensions/agent-context/README.md b/extensions/agent-context/README.md index adc13e31e2..7289de1a87 100644 --- a/extensions/agent-context/README.md +++ b/extensions/agent-context/README.md @@ -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: `` / ``). +It owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `` / ``). 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 @@ -42,15 +63,15 @@ context_markers: 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 @@ -58,10 +79,6 @@ pip install pyyaml /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). diff --git a/extensions/agent-context/agent-context-config.yml b/extensions/agent-context/agent-context-config.yml index e73f8c7c50..275bb617b5 100644 --- a/extensions/agent-context/agent-context-config.yml +++ b/extensions/agent-context/agent-context-config.yml @@ -6,11 +6,16 @@ # 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. +# EXAMPLE: context_file: CLAUDE.md 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. +# EXAMPLE: +# context_files: +# - AGENTS.md +# - CLAUDE.md context_files: [] # Delimiters for the managed Spec Kit section. From 3379a458528b4188aadd408b13c441b997930e0f Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Wed, 8 Jul 2026 12:39:57 +0530 Subject: [PATCH 2/7] docs(agent-context): clarify config documentation - Reformat comments to flow as single-line paragraphs instead of multi-line breaks - Add "WHAT" sections describing each configuration option's purpose - Add "REQUIREMENT" sections specifying if options are optional or required - Add explicit EXAMPLE sections for context_markers configuration - Improve clarity of context_file and context_files option descriptions --- .../agent-context/agent-context-config.yml | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/extensions/agent-context/agent-context-config.yml b/extensions/agent-context/agent-context-config.yml index 275bb617b5..71078cb6db 100644 --- a/extensions/agent-context/agent-context-config.yml +++ b/extensions/agent-context/agent-context-config.yml @@ -1,25 +1,25 @@ # Coding Agent Context Extension Configuration -# These values are populated automatically by `specify init` and -# `specify integration use` / `specify integration install`. +# 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. If you leave this entry blank, the bundled update scripts will automatically fill this in based on the active integration's key. # EXAMPLE: context_file: CLAUDE.md 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 coding agent context file paths managed by this extension. If you have both `context_file` and `context_files`, then `context_files` takes precedence. +# REQUIREMENT: OPTIONAL. Use this if your project requires you to keep multiple agent 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: "" +# end: "" context_markers: start: "" end: "" From d73fc9fd73c09dcca7b2fa954bb9220ce5ba892f Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Wed, 8 Jul 2026 20:28:00 +0530 Subject: [PATCH 3/7] docs(agent-context): fix GitHub casing, clarify config - Fix "Github" -> "GitHub" casing in README issues link - Clarify agent-context-config.yml comments on context_file/context_files behavior and precedence --- extensions/agent-context/README.md | 2 +- extensions/agent-context/agent-context-config.yml | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/extensions/agent-context/README.md b/extensions/agent-context/README.md index 7289de1a87..74406f2e12 100644 --- a/extensions/agent-context/README.md +++ b/extensions/agent-context/README.md @@ -81,4 +81,4 @@ pip install pyyaml ## Issues -For any other issues, please create an issue in the [official Github repo](https://github.com/github/spec-kit/issues). +For any other issues, please create an issue in the [official GitHub repo](https://github.com/github/spec-kit/issues). diff --git a/extensions/agent-context/agent-context-config.yml b/extensions/agent-context/agent-context-config.yml index 71078cb6db..9adec6b6fd 100644 --- a/extensions/agent-context/agent-context-config.yml +++ b/extensions/agent-context/agent-context-config.yml @@ -1,13 +1,12 @@ # Coding Agent Context Extension Configuration -# These values are populated automatically by `specify init` and `specify integration use` / `specify integration install`. -# WHAT: Single Project-relative path to the main coding agent context file. -# REQUIREMENT: OPTIONAL. If you leave this entry blank, the bundled update scripts will automatically fill this in based on the active integration's key. +# 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 context_file: "" -# WHAT: List of project-relative coding agent context file paths managed by this extension. If you have both `context_file` and `context_files`, then `context_files` takes precedence. -# REQUIREMENT: OPTIONAL. Use this if your project requires you to keep multiple agent files 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 From deeb7184974219b580bc07bab16798fe3b09e1e7 Mon Sep 17 00:00:00 2001 From: YASHURA Date: Thu, 16 Jul 2026 15:51:47 +0530 Subject: [PATCH 4/7] YAML indentation fix for context markers Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- extensions/agent-context/agent-context-config.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/agent-context/agent-context-config.yml b/extensions/agent-context/agent-context-config.yml index 9adec6b6fd..292bde3329 100644 --- a/extensions/agent-context/agent-context-config.yml +++ b/extensions/agent-context/agent-context-config.yml @@ -17,8 +17,8 @@ context_files: [] # REQUIREMENT: REQUIRED. Only change if you wish to have a custom marker name. # EXAMPLE: # context_markers: -# start: "" -# end: "" +# start: "" +# end: "" context_markers: start: "" end: "" From 7cc772f04fcec7776306fc2f760de9b7ca028575 Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Thu, 16 Jul 2026 15:56:57 +0530 Subject: [PATCH 5/7] docs(agent-context): simplify README config section - Clarify config file path reference (.specify/extensions path vs repo path) - Remove duplicated YAML example/field docs from README, point to config file directly - Minor spacing fix in agent-context-config.yml comment --- extensions/agent-context/README.md | 25 ++----------------- .../agent-context/agent-context-config.yml | 2 +- 2 files changed, 3 insertions(+), 24 deletions(-) diff --git a/extensions/agent-context/README.md b/extensions/agent-context/README.md index 74406f2e12..8d0c11b858 100644 --- a/extensions/agent-context/README.md +++ b/extensions/agent-context/README.md @@ -11,7 +11,7 @@ It owns the lifecycle of the managed section delimited by the configurable start 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 (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. +- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in this repo) - 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](./extension.yml) (`after_specify`, `after_plan`). @@ -44,28 +44,7 @@ While this extension is disabled (or not installed), nothing in Spec Kit creates ## Configuration -All configuration flows through the extension's own config file at -[agent-context-config.yml](./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: "" - 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. +All configuration flows through the extension's own config file at [agent-context-config.yml](./agent-context-config.yml). ## Requirements diff --git a/extensions/agent-context/agent-context-config.yml b/extensions/agent-context/agent-context-config.yml index 292bde3329..f20c4c17bc 100644 --- a/extensions/agent-context/agent-context-config.yml +++ b/extensions/agent-context/agent-context-config.yml @@ -5,7 +5,7 @@ # EXAMPLE: context_file: CLAUDE.md context_file: "" -# 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. +# 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: From 902e4ba457e83442a500e0e6757fcbfa86d34b99 Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Thu, 16 Jul 2026 15:59:28 +0530 Subject: [PATCH 6/7] docs(agent-context): clarify config file path in README - Reference the installed .specify config path alongside the repo-relative link --- extensions/agent-context/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/agent-context/README.md b/extensions/agent-context/README.md index 8d0c11b858..e47a95e143 100644 --- a/extensions/agent-context/README.md +++ b/extensions/agent-context/README.md @@ -44,7 +44,7 @@ While this extension is disabled (or not installed), nothing in Spec Kit creates ## Configuration -All configuration flows through the extension's own config file at [agent-context-config.yml](./agent-context-config.yml). +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) in the repo). ## Requirements From ce351f89c932ef4b50f79412f4bfc2347b2cc83a Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Thu, 16 Jul 2026 18:20:47 +0530 Subject: [PATCH 7/7] docs(agent-context): clarify install and marker requirement - README: clarify install command must be run from an initialized Spec Kit project root - config: correct context_markers requirement from REQUIRED to OPTIONAL --- extensions/agent-context/README.md | 2 +- extensions/agent-context/agent-context-config.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/agent-context/README.md b/extensions/agent-context/README.md index e47a95e143..6578330744 100644 --- a/extensions/agent-context/README.md +++ b/extensions/agent-context/README.md @@ -17,7 +17,7 @@ Not every Spec Kit user wants Spec Kit to write into the coding agent's context ## Installation -To install the extension, run the following command after installing Spec Kit. +To install the extension, from the root of an initialized Spec Kit project, run: ```bash specify extension add agent-context diff --git a/extensions/agent-context/agent-context-config.yml b/extensions/agent-context/agent-context-config.yml index f20c4c17bc..1af43a7922 100644 --- a/extensions/agent-context/agent-context-config.yml +++ b/extensions/agent-context/agent-context-config.yml @@ -14,7 +14,7 @@ context_file: "" context_files: [] # 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. +# REQUIREMENT: OPTIONAL. Only change if you wish to have a custom marker name. # EXAMPLE: # context_markers: # start: ""