From 18ce4a715da47c25476af31f405be18fcf4827e5 Mon Sep 17 00:00:00 2001 From: Yanuka Deneth Date: Tue, 7 Jul 2026 10:35:33 +0530 Subject: [PATCH 1/3] 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/3] 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/3] 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