feat: make agent-context extension a full opt-in

AGENTS.md

@@ -175,9 +175,11 @@ def _register_builtins() -> None:
 
 ### 4. Context file behavior
 
-Set `context_file` on the integration class. The base integration setup creates or updates the managed Spec Kit section in that file, and uninstall removes the managed section when appropriate.
+Set `context_file` on the integration class. This is **inert metadata only**: it declares which context/instruction file a given agent uses (for example `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`) so templates and the extension can consume it. The Specify CLI itself never creates, updates, or removes a managed section in that file.
 
-The managed section is owned by the bundled `agent-context` extension (`extensions/agent-context/`). All configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml`:
+Managing the "Spec Kit" section in the context file is fully owned by the bundled `agent-context` extension (`extensions/agent-context/`), which is a **full opt-in**: `specify init` does not install it. A user adds/enables it through the standard extension verbs, after which the extension's own bundled scripts maintain the context section. When the extension is absent or disabled, nothing in Spec Kit touches the context file.
+
+The extension reads its own config file at `.specify/extensions/agent-context/agent-context-config.yml`:
 
 ```yaml
 # Path to the coding agent context file managed by this extension
@@ -189,10 +191,10 @@ context_markers:
   end: "<!-- SPECKIT END -->"
 ```
 
-- `context_file` is written automatically from the integration's class attribute when `specify init` or `specify integration use` is run.
-- `context_markers.{start,end}` defaults to `IntegrationBase.CONTEXT_MARKER_START` / `CONTEXT_MARKER_END`. Users who want custom markers edit `agent-context-config.yml` directly — both the Python layer (`upsert_context_section()` / `remove_context_section()`) and the bundled scripts (`extensions/agent-context/scripts/bash/update-agent-context.sh` and `.ps1`) read from this single source of truth.
+- The Specify CLI does **not** write this config. When `context_file` is empty, the extension's bundled scripts self-seed it by resolving the active integration's declared `context_file` metadata from the registry (`extensions/agent-context/scripts/bash/update-agent-context.sh` and `.ps1`).
+- `context_markers.{start,end}` are read solely by the extension's scripts; they default to the Spec Kit markers shown above and can be customized by editing `agent-context-config.yml` directly.
 
-Users can opt out entirely with `specify extension disable agent-context`; while disabled, Spec Kit skips context-file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
+Existing projects created by older Spec Kit versions keep working: any previously written managed section or extension config is left intact and is only ever updated by the extension when run.
 
 Only add custom setup logic when the agent needs non-standard behavior. Integrations no longer require per-agent thin wrapper scripts or shared context-update dispatcher scripts — the `agent-context` extension is fully generic.
 
@@ -466,7 +468,7 @@ Disclosure is **continuous**, not a one-time event. A single AI-disclosure parag
 ## Common Pitfalls
 
 1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), the `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks — mismatches require special-case mappings. IDE-based integrations (`requires_cli: False`) are not subject to this constraint.
-2. **Forgetting context configuration**: The bundled `agent-context` extension reads from `.specify/extensions/agent-context/agent-context-config.yml`. New integrations only need to set `context_file` on the class — markers and dispatcher scripts are managed centrally.
+2. **Forgetting context configuration**: The opt-in `agent-context` extension reads from `.specify/extensions/agent-context/agent-context-config.yml`. New integrations only need to set `context_file` on the class as inert metadata — the CLI never manages the context section, and the extension's bundled scripts own markers and context-file updates.
 3. **Incorrect `requires_cli` value**: Set to `True` only for agents that have a CLI tool; set to `False` for IDE-based agents.
 4. **Wrong argument format**: Use `$ARGUMENTS` for Markdown agents, `{{args}}` for TOML agents.
 5. **Skipping registration**: The import and `_register()` call in `_register_builtins()` must both be added.

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 <!-- insert new changelog below this comment -->
 
+### Changed
+
+- feat!: make the `agent-context` extension a full opt-in. `specify init` no longer installs the extension or writes `agent-context-config.yml`, and the Specify CLI no longer creates, updates, or removes the managed Spec Kit section in agent context files (e.g. `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`). The bundled `agent-context` extension now fully owns this lifecycle — install/enable it to manage the context section. Integration `context_file` declarations are retained as inert metadata. Removed the obsolete inline agent-context deprecation warning. Existing projects keep working: previously written sections and config files are left intact and only updated by the extension.
+
 ## [0.11.4] - 2026-06-22
 
 ### Changed

extensions/agent-context/README.md

@@ -6,10 +6,10 @@ It owns the lifecycle of the managed section delimited by the configurable start
 
 ## Why an extension?
 
-Not every Spec Kit user wants Spec Kit to write into the coding agent's context file. Extracting this behavior into a dedicated extension lets users:
+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:
 
-- **Opt out** entirely with `specify extension disable agent-context` — Spec Kit will then never create or modify the agent context file.
-- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` — both the Python layer and the bundled scripts honor the same `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.
+- **Customize the markers** by editing `.specify/extensions/agent-context/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** with `/speckit.agent-context.update`, or automatically through the hooks declared in `extension.yml` (`after_specify`, `after_plan`).
 
@@ -40,7 +40,7 @@ context_markers:
   end: "<!-- SPECKIT END -->"
 ```
 
-- `context_file` — the project-relative path to the coding agent context file, written by `specify init` and `specify integration install`.
+- `context_file` — the project-relative path to the coding agent context file. When empty, the bundled update scripts self-seed it by resolving the active integration's declared context file from the registry.
 - `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.
 
@@ -62,5 +62,5 @@ pip install pyyaml
 specify extension disable agent-context
 ```
 
-When disabled, Spec Kit skips context file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
+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.
 Disabled projects also ignore stale `context_files` values during command rendering so disabling the extension remains a complete opt-out.

extensions/agent-context/scripts/bash/update-agent-context.sh

@@ -59,7 +59,7 @@ case "$(uname -s 2>/dev/null || true)" in
 esac
 
 # Parse extension config once; emit context files as JSON, followed by marker strings.
-if ! _raw_opts="$("$_python" - "$EXT_CONFIG" "$_case_insensitive_context_files" <<'PY'
+if ! _raw_opts="$("$_python" - "$EXT_CONFIG" "$_case_insensitive_context_files" "$PROJECT_ROOT" <<'PY'
 import json
 import sys
 try:
@@ -95,24 +95,53 @@ def get_str(obj, *keys):
 context_files = []
 seen_context_files = set()
 case_insensitive = sys.argv[2] == "1" or sys.platform.startswith(("win32", "cygwin"))
+def add_context_file(value):
+    if not isinstance(value, str):
+        return
+    candidate = value.strip()
+    if not candidate:
+        return
+    key = candidate.casefold() if case_insensitive else candidate
+    if key in seen_context_files:
+        return
+    context_files.append(candidate)
+    seen_context_files.add(key)
 raw_files = data.get("context_files")
 if isinstance(raw_files, list):
     for value in raw_files:
-        if not isinstance(value, str):
-            continue
-        candidate = value.strip()
-        if not candidate:
-            continue
-        key = candidate.casefold() if case_insensitive else candidate
-        if key in seen_context_files:
-            continue
-        context_files.append(candidate)
-        seen_context_files.add(key)
+        add_context_file(value)
 if not context_files:
-    raw_file = get_str(data, "context_file")
-    candidate = raw_file.strip()
-    if candidate:
-        context_files.append(candidate)
+    add_context_file(get_str(data, "context_file"))
+if not context_files:
+    # Self-seed: the agent-context extension owns its lifecycle, so when its
+    # own config declares no target it derives one from the active integration
+    # recorded in init-options.json via the Spec Kit integration registry.
+    # This is best-effort — when the registry is unavailable the script simply
+    # reports nothing to do.
+    project_root = sys.argv[3] if len(sys.argv) > 3 else "."
+    integration_key = ""
+    for candidate_path in (
+        f"{project_root}/.specify/init-options.json",
+    ):
+        try:
+            with open(candidate_path, "r", encoding="utf-8") as fh:
+                opts = json.load(fh)
+        except Exception:
+            continue
+        if isinstance(opts, dict):
+            integration_key = (
+                opts.get("integration") or opts.get("ai") or ""
+            )
+            if integration_key:
+                break
+    if integration_key:
+        try:
+            from specify_cli.integrations import INTEGRATION_REGISTRY
+
+            integration = INTEGRATION_REGISTRY.get(integration_key)
+            add_context_file(getattr(integration, "context_file", "") or "")
+        except Exception:
+            pass
 print(json.dumps(context_files))
 print(get_str(data, "context_markers", "start"))
 print(get_str(data, "context_markers", "end"))

extensions/agent-context/scripts/powershell/update-agent-context.ps1

@@ -234,6 +234,49 @@ foreach ($ContextFile in $ContextFiles) {
     }
 }
 $ContextFiles = $dedupedContextFiles
+if ($ContextFiles.Count -eq 0) {
+    # Self-seed: the agent-context extension owns its lifecycle, so when its
+    # own config declares no target it derives one from the active integration
+    # recorded in init-options.json via the Spec Kit integration registry.
+    # Best-effort — when the registry is unavailable the script reports nothing
+    # to do below.
+    $initOptionsPath = Join-Path $ProjectRoot '.specify/init-options.json'
+    if (Test-Path -LiteralPath $initOptionsPath) {
+        try {
+            $initOpts = Get-Content -LiteralPath $initOptionsPath -Raw | ConvertFrom-Json -ErrorAction Stop
+            $integrationKey = $null
+            if ($initOpts.PSObject.Properties['integration'] -and $initOpts.integration) {
+                $integrationKey = [string]$initOpts.integration
+            } elseif ($initOpts.PSObject.Properties['ai'] -and $initOpts.ai) {
+                $integrationKey = [string]$initOpts.ai
+            }
+            if ($integrationKey) {
+                $pythonForRegistry = $null
+                foreach ($candidate in @($env:SPECKIT_PYTHON, 'python3', 'python')) {
+                    if ($candidate -and (Get-Command $candidate -ErrorAction SilentlyContinue)) {
+                        $pythonForRegistry = $candidate
+                        break
+                    }
+                }
+                if ($pythonForRegistry) {
+                    $registryScript = 'import sys' + "`n" +
+                        'try:' + "`n" +
+                        '    from specify_cli.integrations import INTEGRATION_REGISTRY' + "`n" +
+                        '    integration = INTEGRATION_REGISTRY.get(sys.argv[1])' + "`n" +
+                        '    sys.stdout.write(getattr(integration, "context_file", "") or "")' + "`n" +
+                        'except Exception:' + "`n" +
+                        '    pass'
+                    $derived = & $pythonForRegistry -c $registryScript $integrationKey 2>$null
+                    if ($LASTEXITCODE -eq 0 -and $derived -and -not [string]::IsNullOrWhiteSpace($derived)) {
+                        $ContextFiles += $derived.Trim()
+                    }
+                }
+            }
+        } catch {
+            # Non-fatal: fall through to the nothing-to-do guard below.
+        }
+    }
+}
 if ($ContextFiles.Count -eq 0) {
     Write-Warning 'agent-context: context_files/context_file not set in extension config; nothing to do.'
     exit 0

specs/001-agent-context-full-optin/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Agent-Context Extension Full Opt-In
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-06-22
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`.
+- The spec intentionally keeps file/symbol-level removals out of the requirements; those belong to the planning phase. FR-007 and the Assumptions section bound the one genuine design choice (keep `context_file` as inert metadata vs. remove it entirely) so planning can decide without reopening scope.

specs/001-agent-context-full-optin/contracts/cli-behavior.md

@@ -0,0 +1,91 @@
+# Phase 1 Contracts: CLI Behavioral Contracts
+
+**Feature**: 001-agent-context-full-optin | **Date**: 2026-06-22
+
+This is a CLI tool, so the externally observable "contract" is the behavior of `specify` commands with respect to agent context files and the extension config. Each contract below is a testable assertion that the implementation and test suite must satisfy.
+
+## C1: `specify init` — extension absent/not selected
+
+**Given** a user runs `specify init` with an integration and does not select the `agent-context` extension
+**When** initialization and integration setup complete
+**Then**:
+- No managed Spec Kit section is created in the agent context file by the CLI.
+- `.specify/extensions/agent-context/agent-context-config.yml` is not created or written by the CLI.
+- No deprecation message is printed.
+
+*Maps to*: FR-001, FR-002, FR-005, FR-006 · SC-001, SC-003
+
+## C2: `specify init` — extension selected (opt-in)
+
+**Given** a user runs `specify init` and opts into the `agent-context` extension
+**When** initialization completes
+**Then**:
+- The extension is installed via the normal extension mechanism.
+- Any seeding of `agent-context-config.yml` is performed by the extension's own install logic, not by CLI agent-context helpers.
+- Running the extension's update command produces a correct managed section.
+
+*Maps to*: FR-004, FR-005 · SC-005
+
+## C3: Integration setup never writes the context section
+
+**Given** any integration's `setup()` runs (regardless of extension state)
+**When** command files are installed
+**Then**:
+- `__CONTEXT_FILE__` placeholders in rendered templates are substituted from the integration's declared `context_file` metadata.
+- No call creates, updates, or removes a managed section in the agent context file.
+
+*Maps to*: FR-001, FR-003, FR-007
+
+## C4: Integration teardown/uninstall never touches the context file or ext config
+
+**Given** an integration is uninstalled or switched
+**When** the operation completes
+**Then**:
+- The CLI does not remove or rewrite any managed section.
+- The CLI does not clear or rewrite `agent-context-config.yml`.
+
+*Maps to*: FR-001, FR-002
+
+## C5: No agent-context logic remains in the base/init/switch layers
+
+**Given** the Specify CLI source after this feature
+**When** inspected (e.g. by grep/CI check)
+**Then** there are zero references to:
+- `upsert_context_section`, `remove_context_section`
+- `_agent_context_extension_enabled`, `_resolve_context_markers`
+- `_resolve_context_files`, and any extension-config-reading branch of `_resolve_context_file_values` / `_format_context_file_values`
+- the plural `context_files` config-key consumption
+- `_AGENT_CTX_EXT_CONFIG`, `_load_agent_context_config`, `_save_agent_context_config`, `_update_agent_context_config_file`
+- the v0.12.0 deprecation string
+
+(outside the `extensions/agent-context/` directory and this `specs/` artifact).
+
+*Maps to*: FR-002, FR-003, FR-006 · SC-002, SC-003
+
+## C6: Backward compatibility
+
+**Given** a project created by a previous Spec Kit version (already has a managed section and/or `agent-context-config.yml`)
+**When** the user runs `specify init`, an integration switch, or an uninstall
+**Then** the commands complete without error and leave the pre-existing files intact (unmanaged by the CLI).
+
+*Maps to*: FR-008 · SC-006
+
+## C7: Extension remains self-contained
+
+**Given** the `extensions/agent-context/` directory
+**When** the extension's update command/script runs in an opt-in project
+**Then** it reads its own `agent-context-config.yml` and updates the context file independently of any CLI agent-context code.
+
+*Maps to*: FR-004 · SC-005
+
+## Contract Test Matrix
+
+| Contract | Test location (target) | Type |
+|----------|------------------------|------|
+| C1 | `tests/integrations/` + init tests | integration |
+| C2 | `tests/extensions/test_extension_agent_context.py` | integration |
+| C3 | `tests/integrations/test_integration_base_*.py` | unit |
+| C4 | `tests/integrations/` switch/uninstall tests | unit/integration |
+| C5 | new static/grep guard test (or CI check) | static |
+| C6 | new backward-compat test | integration |
+| C7 | `tests/extensions/test_extension_agent_context.py` (layout/script) | integration |