Files

T

History

Quratulain-bilal 4a465431b8 fix: use missing_ok for temp file cleanup to avoid masking errors (#3803 )

* fix(agent-context): recurse for nested plans in Python mtime fallback

The Python port's mtime fallback discovered plans with a one-level
specs/*/plan.md glob, so a scoped layout created via
SPECIFY_FEATURE_DIRECTORY (specs/<scope>/<feature>/plan.md) was missed when
feature.json is absent — the fallback returned no plan and the managed
context section omitted the 'at <plan>' line. The bash and PowerShell twins
were already fixed to recurse (#3024); the Python twin was left behind.

Switch to specs.rglob('plan.md') with the same symlink-safe containment check
the bash twin uses (resolve each candidate and confirm it stays within the
project root before ranking by mtime), so a plan reached through a specs/
symlink pointing outside the project is not selected.

Adds parity regression tests (vs bash and vs PowerShell) covering a nested
specs/<scope>/<feature>/plan.md; both fail on the pre-fix one-level glob.

Fixes #3733

* test(agent-context): cover symlink containment in the mtime fallback

The recursive fallback resolves each candidate before the relative_to()
containment check, but nothing exercised that path. Add a parity test for a
plan reachable only through a specs/ symlink pointing outside the project:
relative_to() is lexical and would accept it, emitting an in-project-looking
path for an out-of-project file. Both the bash twin and the Python port skip
it, so the "at <plan>" line is omitted.

Also correct the module docstring, which still described the fallback as
scanning specs/*/plan.md one level deep.

* fix: use missing_ok for temp file cleanup to avoid masking errors

2026-08-06 09:58:19 -05:00

commands

fix(agent-context): discover nested plan.md in scoped layouts (#3024 ) (#3301 )

2026-07-10 14:21:43 -05:00

scripts

fix: use missing_ok for temp file cleanup to avoid masking errors (#3803 )

2026-08-06 09:58:19 -05:00

agent-context-config.yml

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

2026-07-23 09:06:51 -05:00

agent-context-defaults.json

feat: Add Alquimia AI integration (#2734 )

2026-07-28 07:54:13 -05:00

extension.yml

Extract agent context updates into bundled agent-context extension (#2546 )

2026-05-30 06:37:18 -05:00

README.md

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

2026-07-23 09:06:51 -05:00

README.md

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:  / ). For .mdc files, it also ensures the YAML frontmatter (the metadata block at the top of the file) contains alwaysApply: true. Otherwise, everything outside the managed section 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; when it is absent, the file is never modified, and when it is disabled, its automatic hooks do not run.
Customize the markers by editing .specify/extensions/agent-context/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 (after_specify, after_plan).

Installation

To install the extension, from the root of an initialized Spec Kit project, run:

specify extension add agent-context

Disabling

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. Invoke it using the syntax for your integration: /speckit.agent-context.update for dot-command integrations; /speckit-agent-context-update for hyphen/skills integrations (including Forge and Cline); $speckit-agent-context-update for Codex or ZCode in skills mode; or /skill:speckit-agent-context-update for Kimi.

Configuration

All configuration flows through the extension's own config file at .specify/extensions/agent-context/agent-context-config.yml (agent-context-config.yml in the repo).

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:

pip install pyyaml
# or target the specific interpreter Spec Kit uses:
/path/to/speckit-python -m pip install pyyaml

Issues

For any other issues, please create an issue in the official GitHub repo.