docs(extensions): clarify agent-context README and add config examples by yanukadeneth99 · Pull Request #3389 · github/spec-kit

yanukadeneth99 · 2026-07-07T05:10:34Z

Description

Edited the agent-context README.md and agent-context-config.yml for clarity. Added the missing install command.

Testing

Ran the commands on a project to ensure it's correct. No other testing are required for this.

AI Disclosure

I did not use AI assistance for this contribution
I did use AI assistance

AI was used to check whether there were any active PRs/issues related to this, and then to create a suggested fix for the README. However, I only used that file as a reference and made the changes to the README.md myself.

Please do let me know if there are changes/suggestions to be done.

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.

mnriem · 2026-07-07T19:23:55Z

 # 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


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.

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.

- 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

Copilot

Pull request overview

This PR updates the bundled agent-context extension documentation to better explain its opt-in behavior and configuration, and adds an explicit install command to the README.

Changes:

Expanded extensions/agent-context/README.md with installation/disabling instructions and clearer “opt-in” explanation.
Added more descriptive inline documentation and examples to extensions/agent-context/agent-context-config.yml.

Show a summary per file

File	Description
extensions/agent-context/README.md	Clarifies extension behavior and adds install/disable instructions; includes an Issues section link.
extensions/agent-context/agent-context-config.yml	Adds more explicit WHAT/REQUIREMENT/EXAMPLE guidance for config fields.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 2/2 changed files
Comments generated: 2
Review effort level: Low

yanukadeneth99 · 2026-07-08T14:58:46Z

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


yanukadeneth99 · 2026-07-08T14:58:55Z

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


mnriem

Please address feedback

mnriem · 2026-07-08T14:36:28Z

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


We should remove this line as the extension does the work. Not the CLI commands mentioned

Done @mnriem. I think the latest updated file should be clearer. I verified this as well.

- Fix "Github" -> "GitHub" casing in README issues link - Clarify agent-context-config.yml comments on context_file/context_files behavior and precedence

Copilot

Review details

Files reviewed: 2/2 changed files
Comments generated: 4
Review effort level: Low

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


+# EXAMPLE:
+# context_markers:
+#  start: "<!-- AGENT SPEC KIT CONTEXT START -->"
+#  end: "<!-- AGENT SPEC KIT CONTEXT END -->"


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


 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


yanukadeneth99 requested a review from mnriem as a code owner July 7, 2026 05:10

mnriem reviewed Jul 7, 2026

View reviewed changes

mnriem requested a review from Copilot July 8, 2026 14:32

Copilot started reviewing on behalf of mnriem July 8, 2026 14:33 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

mnriem requested changes Jul 8, 2026

View reviewed changes

docs(agent-context): fix GitHub casing, clarify config

d73fc9f

- Fix "Github" -> "GitHub" casing in README issues link - Clarify agent-context-config.yml comments on context_file/context_files behavior and precedence

mnriem requested a review from Copilot July 9, 2026 16:08

Copilot started reviewing on behalf of mnriem July 9, 2026 16:09 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

docs(extensions): clarify agent-context README and add config examples#3389
yanukadeneth99 wants to merge 3 commits into
github:mainfrom
yanukadeneth99:docs/agent-context-readme

yanukadeneth99 commented Jul 7, 2026

Uh oh!

mnriem Jul 7, 2026

Uh oh!

yanukadeneth99 Jul 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

yanukadeneth99 Jul 8, 2026

Uh oh!

yanukadeneth99 Jul 8, 2026

Uh oh!

mnriem left a comment

Uh oh!

mnriem Jul 8, 2026

Uh oh!

yanukadeneth99 Jul 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

yanukadeneth99 commented Jul 7, 2026

Description

Testing

AI Disclosure

Uh oh!

mnriem Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

yanukadeneth99 Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

yanukadeneth99 Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

yanukadeneth99 Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

mnriem Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

yanukadeneth99 Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yanukadeneth99 Jul 8, 2026 •

edited

Loading