feat: make agent-context extension a full opt-in#3097
Conversation
Use Spec Kit's own specify workflow to author the spec that makes the agent-context extension a full opt-in, removing all agent-context configuration/support from the Python codebase and removing the deprecation message. Force-added despite specs/ being gitignored; the generated artifact will be purged prior to merge. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Phase 0/1 of the SDD plan workflow: plan.md, research.md, data-model.md, quickstart.md, and contracts/cli-behavior.md. Constitution Check is a documented no-op (repo has no ratified constitution). Force-added despite specs/ being gitignored; generated artifacts will be purged prior to merge. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Earlier draft wrongly treated the gate as a no-op; the fork's main is 16 commits behind upstream/main, which carries .specify/memory/constitution.md. Re-evaluate the feature against Principles I-V (all PASS) and note that Principle I mandates keeping context_file as a declared class attribute, validating the R1 metadata decision. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
After syncing fork main to upstream and rebasing, re-scan the current agent-context surface. Upstream generalized the single context_file into a plural context_files concept with new resolver helpers (_resolve_context_files, _resolve_context_file_values, _format_context_file_values) and upsert/remove now loop over multiple files. Update research.md, data-model.md, contracts, quickstart grep guards, and the plan summary to cover the expanded removal scope. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Phase 2 of SDD: dependency-ordered tasks.md (30 tasks) organized by the three user stories, with mandatory test tasks (Constitution Principle II) and a foundational phase decoupling __CONTEXT_FILE__ resolution from the extension config. Includes the extension self-seeding task (T015) and a static guard test (T002) enforcing zero agent-context references in the CLI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Make the agent-context extension a full opt-in. The CLI no longer installs the extension during init, writes agent-context-config.yml, or creates/updates/removes the managed Spec Kit section in agent context files. Context-section upsert/remove, marker resolution, extension-enabled gating, the config helpers, and the obsolete inline deprecation warning are all removed. Integration context_file stays as inert metadata; __CONTEXT_FILE__ now resolves from registry metadata. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When agent-context-config.yml has no context_file/context_files, the bundled bash and PowerShell update scripts now resolve the context file from the active integration in .specify/init-options.json via the integration registry, so the extension no longer depends on the CLI writing its config. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update integration/extension tests to expect no agent-context install, config, or context-section writes during init. Add a static guard test (test_agent_context_cli_free.py) asserting the CLI source is free of agent-context lifecycle symbols, plus backward-compatibility tests for legacy projects. Refresh AGENTS.md, the extension README, and add a CHANGELOG entry describing the opt-in behavior change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR makes the bundled agent-context extension fully opt-in by removing all CLI-side (Python) ownership of agent context/instruction files. Context file lifecycle (create/update/remove + config/markers) is now extension-owned; the CLI retains context_file only as inert metadata for template substitution.
Changes:
- Removed CLI code paths that auto-install
agent-context, writeagent-context-config.yml, or upsert/remove managed context sections during integration setup/teardown/init/switch. - Updated
__CONTEXT_FILE__placeholder rendering to resolve purely from integration metadata (no extension-config reads). - Refactored and expanded tests to assert “CLI does not touch context files/config”, added a static guard test, and updated extension scripts to self-seed when config targets are empty.
Show a summary per file
| File | Description |
|---|---|
| tests/integrations/test_integration_rovodev.py | Updates expectations: skills inventory is core-only (no extension auto-install). |
| tests/integrations/test_integration_generic.py | Removes assertions about context section/config being created; updates file inventories accordingly. |
| tests/integrations/test_integration_forge.py | Asserts setup does not create/touch context files. |
| tests/integrations/test_integration_cursor_agent.py | Removes .mdc context upsert/remove/frontmatter tests tied to CLI lifecycle. |
| tests/integrations/test_integration_copilot.py | Removes agent-context command/context/config expectations across default + skills modes. |
| tests/integrations/test_integration_codex.py | Updates plan skill tests to resolve context file from metadata and ignore extension config. |
| tests/integrations/test_integration_cline.py | Removes bundled extension/context file expectations from inventory helper. |
| tests/integrations/test_integration_claude.py | Removes upsert/remove/BOM tests; adds teardown “leave user context intact” assertion. |
| tests/integrations/test_integration_base_yaml.py | Reworks base integration tests to ensure setup/teardown do not manage context files/config. |
| tests/integrations/test_integration_base_toml.py | Same as above for TOML-based integrations. |
| tests/integrations/test_integration_base_skills.py | Ensures init doesn’t create agent-context config; inventories drop agent-context artifacts. |
| tests/integrations/test_integration_base_markdown.py | Ensures markdown integrations do not create/touch context files/config. |
| tests/integrations/test_cli.py | Updates init test: no agent-context config or context file created. |
| tests/extensions/test_extension_agent_context.py | Prunes CLI-side marker/gating/config-writer coverage; adds metadata-only resolution + self-seed/back-compat checks. |
| tests/extensions/test_agent_context_cli_free.py | Adds static guard ensuring CLI source contains no agent-context lifecycle/config symbols. |
| src/specify_cli/integrations/hermes/init.py | Stops calling CLI upsert/remove and switches to metadata-only context display. |
| src/specify_cli/integrations/generic/init.py | Stops calling CLI upsert/remove; metadata-only context display. |
| src/specify_cli/integrations/forge/init.py | Stops calling CLI upsert/remove; metadata-only context display. |
| src/specify_cli/integrations/copilot/init.py | Removes CLI upsert call from default setup; metadata-only context display. |
| src/specify_cli/integrations/base.py | Deletes context section lifecycle machinery and replaces display helper with metadata-only accessor. |
| src/specify_cli/integrations/_helpers.py | Removes extension-config write/clear side effects from init-options update/clear helpers. |
| src/specify_cli/commands/init.py | Removes bundled agent-context auto-install step and config write during init. |
| src/specify_cli/agents.py | Resolves __CONTEXT_FILE__ from integration metadata (registry), not extension config. |
| src/specify_cli/init.py | Removes agent-context extension config helper functions/constants from the CLI package. |
| specs/001-agent-context-full-optin/tasks.md | Adds tasks doc for the opt-in refactor (intended temporary artifact per PR description). |
| specs/001-agent-context-full-optin/spec.md | Feature spec describing requirements/acceptance criteria for opt-in boundary. |
| specs/001-agent-context-full-optin/research.md | Documents design decisions and rationale for removing CLI lifecycle/config I/O. |
| specs/001-agent-context-full-optin/quickstart.md | Adds validation steps (tests/grep/init/extension update/back-compat). |
| specs/001-agent-context-full-optin/plan.md | Implementation plan outlining code/test removals and checkpoints. |
| specs/001-agent-context-full-optin/data-model.md | Captures ownership boundary + artifacts and what’s removed from CLI. |
| specs/001-agent-context-full-optin/contracts/cli-behavior.md | Defines behavioral contracts mapped to tests. |
| specs/001-agent-context-full-optin/checklists/requirements.md | Spec-quality checklist artifact (temporary per PR description). |
| extensions/agent-context/scripts/powershell/update-agent-context.ps1 | Adds self-seeding from init-options via integration registry when config targets are empty. |
| extensions/agent-context/scripts/bash/update-agent-context.sh | Same self-seeding behavior for bash script; refactors config parsing helpers. |
| extensions/agent-context/README.md | Updates docs to reflect opt-in behavior and extension-owned lifecycle. |
| CHANGELOG.md | Adds breaking-change entry explaining opt-in shift and removal of CLI lifecycle/deprecation warning. |
| AGENTS.md | Updates integration documentation: context_file is inert metadata; extension fully owns lifecycle. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 37/37 changed files
- Comments generated: 4
… guard test Address PR review feedback: - Self-seed scripts (bash + PowerShell) now emit an actionable warning when an active integration is configured but specify_cli cannot be imported by the chosen Python (e.g. pipx installs), or when the integration declares no context file, instead of silently falling through to 'nothing to do'. - Correct the extension README disable note: command rendering never reads the extension config; __CONTEXT_FILE__ is always substituted from integration metadata, so a stale context_files value cannot affect rendering. - Cache CLI source reads in the static guard test via a module-scoped fixture so the directory walk happens once instead of once per forbidden symbol. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Thanks for the review — addressed all four findings in 56ee0df.
Were these "gaps we missed"? Mostly minor: #1 was a genuine doc-accuracy miss (a carried-over sentence that's no longer true), and #4 is a test-efficiency nit. #2/#3 aren't functional bugs — the spec treats self-seed as best-effort — but the warnings make the best-effort path diagnosable, which is a fair improvement. No correctness gaps in the feature itself. Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). |
The extension now bundles agent-context-defaults.json (key→context_file map) and self-seeds from it, dropping any dependency on the Specify CLI registry. Both the bash and PowerShell update scripts read the bundled JSON map keyed by the active integration from init-options.json. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Strip every context_file reference from the CLI: the field on all 35 integration classes, the IntegrationBase plumbing (process_template param/step, _context_file_display, docstrings), the __CONTEXT_FILE__ resolution in agents.py, the legacy context_file/context_markers popping in _helpers.py, and the context_file template in integration_scaffold.py. Also drop the Agent context update step and __CONTEXT_FILE__ placeholder from templates/commands/plan.md. The agent-context extension now solely owns all context-file knowledge, including the per-agent default mapping. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove CONTEXT_FILE attrs and context_file assertions across the base mixins, all 35 per-integration test files, shared integration tests, and conftest stubs. Rewrite the base-mixin context tests to assert no managed section is written and no __CONTEXT_FILE__ placeholder survives. Extend the CLI-free static guard to forbid context_file, __CONTEXT_FILE__, and _context_file_display in src/specify_cli, and have the extension tests copy the bundled defaults JSON so self-seed runs without the CLI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update AGENTS.md (integration examples, required-fields table, context behavior section, pitfalls), CHANGELOG, and the SDD spec artifacts (FR-007, SC-002, data-model) to state that the CLI carries no context_file and the extension fully owns the per-agent default mapping via agent-context-defaults.json. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Pushed Phase 2 (commits What changed:
Full suite: 3818 passed, 4 skipped; ruff clean on Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). |
Update research.md (R1, R2, R4, summary table), contracts/cli-behavior.md (C3, C5), tasks.md (Phase 2, T026, notes), plan.md (Principle I, source map), and checklists/requirements.md so the spec artifacts reflect the implemented decision: the CLI carries no context_file attribute or __CONTEXT_FILE__ resolution, and the per-agent defaults map lives in the extension. Resolves PR review #4548130110. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Both findings were real spec/implementation inconsistencies — fixed in The flagged sections were holdovers from the earlier Phase 1 "keep
No code changes in this round — spec-artifact alignment only. Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). |
Update the multi_install_safe docstring (drop the removed "context file" invariant), the RovoDev setup docstring (no longer upserts a context section), the Copilot module docstring (drop the context-file line), and tighten the _update_init_options_for_integration note. Pure docstring changes — no behavioral impact. Resolves PR review #4548237085. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Fixed in While in there I swept the rest of
Pure docstring changes, no behavioral impact. Targeted tests (copilot, rovodev, registry, CLI-free guard) pass; ruff clean. Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). |
…t-optin-spec Reconcile the agent-context full opt-in branch with upstream/main. Apply this branch's contract (the CLI carries no agent-context state) to code that landed upstream after the branch point: - codex/kimi: keep upstream's new features (dev_no_symlink, .kimi-code rename, /skill: invocation, skills-dir migration) but drop context_file and the KIMI.md -> AGENTS.md context-file migration that called now-removed base methods; remove the orphaned tests. - firebender/omp (new upstream integrations): drop their context_file declarations and add their context targets to the extension's own agent-context-defaults.json (also update kimi -> AGENTS.md). - CHANGELOG: keep the unreleased entry above upstream's 0.11.7 section. Full suite: 3947 passed, 4 skipped. ruff clean. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
CHANGELOG.md is auto-generated at release time, so the branch should not carry a manual entry. Restore it to match upstream/main exactly. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The bundled agent-context updater scripts wrote the managed section as plain text. For Cursor-style `.mdc` targets this dropped the required `---\nalwaysApply: true\n---` frontmatter, reintroducing the rule-loading bug originally fixed in github#1699. Port the `_ensure_mdc_frontmatter` logic into both the bash and PowerShell updaters: prepend frontmatter when missing, repair `alwaysApply` when set to the wrong value, and leave non-`.mdc` targets untouched. Add regression tests covering both shells. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Drop the bare "context_file" substring from FORBIDDEN_SYMBOLS so the guard no longer fails on unrelated future CLI fields named context_file. The list still covers agent-context-specific identifiers (__CONTEXT_FILE__, _context_file_display, _resolve_context_files, _resolve_context_file_values). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Two robustness fixes in the embedded Python self-seed logic: - Coerce the integration value from init-options.json to a string only when it is actually a string; otherwise treat it as unset so a corrupted dict/list value degrades to the existing nothing-to-do behavior instead of breaking the agents-map lookup. - Normalize agent-context-defaults.json: only use 'agents' when both the JSON root and the 'agents' value are dicts, so a wrong-shaped (but valid) JSON falls back to the warning path instead of raising on .get. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Self-seed now reads the defaults mapping via $defaults.agents.PSObject.Properties[$integrationKey].Value instead of member access ($defaults.agents.$integrationKey), which parsed hyphenated keys like 'cursor-agent'/'kiro-cli' as subtraction and failed to resolve. - Replace the static [regex]::Replace(..., 1) call, whose trailing 1 was interpreted as RegexOptions.IgnoreCase rather than a replacement count, with an instance Regex whose Replace(input, replacement, 1) limits to the first match as intended. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The bash updater only injected Cursor .mdc frontmatter when ctx_path ended in lowercase '.mdc', so a mixed/upper-case extension (e.g. specify-rules.MDC) was skipped and Cursor would not auto-load the rule file. Compare against the casefolded path. The PowerShell variant already uses -match, which is case-insensitive by default, so no change is needed there. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The README hard-coded the dot-notation slash command (/speckit.agent-context.update), which hyphen-separator agents like Forge and Cline do not recognize. Document the canonical command ID plus both slash invocations so users copy the form their agent accepts. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Summary
Makes the bundled
agent-contextextension a full opt-in and removes every agent-context concern from the Specify CLI (Python). The extension now fully owns the agent context/instruction file lifecycle; the CLI does nothing to it.Concretely, the CLI no longer:
agent-contextextension duringspecify init,agent-context-config.yml,CLAUDE.md,AGENTS.md,.github/copilot-instructions.md, …),context_fileconfig plumbing,v0.12.0message).Integration
context_filedeclarations are removed from the registry, and the CLI no longer resolves the__CONTEXT_FILE__placeholder at all — it carries no agent-context state whatsoever. Instead, the bundled bash/PowerShell update scripts self-seed the context file from the active integration recorded in.specify/init-options.json, using the extension's own bundled integration→context-file mapping, so the extension is fully self-contained.Built with Spec Kit (dogfooding)
This change was produced end-to-end with the Spec Kit SDD pipeline: specify → plan → tasks → implement → converge. The
specs/001-agent-context-full-optin/artifacts (spec, plan, research, data-model, contracts, quickstart, tasks) were force-added earlier purely to show "Spec Kit for Spec Kit"; sincespecs/is gitignored and they were always meant to be purged before merge, they have now been removed from the branch.Verification
ruff check src/clean; changed docs lint-clean.tests/extensions/test_agent_context_cli_free.pyasserts the CLI source contains zero agent-context lifecycle symbols.specify initthat creates no agent-context files, no config, and no context file.Requirements coverage
FR-001–FR-010 and SC-001–SC-006 from the spec all map to concrete evidence; convergence assessment found no remaining gaps.
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com