Fix remaining agent-context review findings

Author: Copilot

AGENTS.md

@@ -399,7 +399,7 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):
 ## 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/init-options.json`. New integrations only need to set `context_file` on the class — markers and dispatcher scripts are managed centrally.
+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.
 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.

extensions/agent-context/README.md

@@ -35,6 +35,7 @@ context_markers:
 
 - `context_file` — the project-relative path to the coding agent context file, written by `specify init` and `specify integration install`.
 - `context_markers.start` / `.end` — the delimiters around the managed section. Edit these to use custom markers.
+- Runtime note: the bundled update scripts require Python 3 for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).
 
 ## Disable
 

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

@@ -35,8 +35,8 @@ elif command -v python >/dev/null 2>&1 && python --version 2>&1 | grep -q "^Pyth
 fi
 
 if [[ -z "$_python" ]]; then
-  echo "agent-context: Python 3 not found on PATH; cannot parse extension config." >&2
-  exit 1
+  echo "agent-context: Python 3 not found on PATH; skipping update." >&2
+  exit 0
 fi
 
 # Parse extension config once; emit three newline-separated fields:

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

@@ -30,25 +30,49 @@ if (-not (Test-Path -LiteralPath $ExtConfig)) {
 try {
     $Options = Get-Content -LiteralPath $ExtConfig -Raw | ConvertFrom-Yaml -ErrorAction Stop
 } catch {
-    # ConvertFrom-Yaml may not be available on all systems; fall back to a
-    # simple line-by-line YAML parser for the keys we need.
-    $Options = @{}
-    $inMarkers = $false
-    foreach ($line in Get-Content -LiteralPath $ExtConfig) {
-        if ($line -match '^context_file:\s*(.*)$') {
-            $Options['context_file'] = $Matches[1].Trim().Trim('"').Trim("'")
-        } elseif ($line -match '^context_markers:') {
-            $inMarkers = $true
-        } elseif ($inMarkers -and $line -match '^\s+start:\s*(.+)$') {
-            if (-not $Options.ContainsKey('context_markers')) { $Options['context_markers'] = @{} }
-            $Options['context_markers']['start'] = $Matches[1].Trim().Trim('"').Trim("'")
-        } elseif ($inMarkers -and $line -match '^\s+end:\s*(.+)$') {
-            if (-not $Options.ContainsKey('context_markers')) { $Options['context_markers'] = @{} }
-            $Options['context_markers']['end'] = $Matches[1].Trim().Trim('"').Trim("'")
-        } elseif ($inMarkers -and $line -match '^[a-z]') {
-            $inMarkers = $false
+    # ConvertFrom-Yaml may not be available on all systems.
+    # Fall back to Python+PyYAML for consistent parsing semantics.
+    $pythonCmd = $null
+    foreach ($candidate in @('python3', 'python')) {
+        if (Get-Command $candidate -ErrorAction SilentlyContinue) {
+            $pythonCmd = $candidate
+            break
         }
     }
+
+    if ($pythonCmd) {
+        try {
+            $jsonOut = & $pythonCmd -c @'
+import json
+import sys
+try:
+    import yaml
+except Exception:
+    yaml = None
+
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) if yaml else {}
+except Exception:
+    data = {}
+
+if not isinstance(data, dict):
+    data = {}
+
+print(json.dumps(data))
+'@ $ExtConfig
+            if ($LASTEXITCODE -eq 0 -and $jsonOut) {
+                $Options = $jsonOut | ConvertFrom-Json -AsHashtable -ErrorAction Stop
+            }
+        } catch {
+            $Options = $null
+        }
+    }
+
+    if (-not $Options) {
+        Write-Warning "agent-context: unable to parse $ExtConfig; skipping update."
+        exit 0
+    }
 }
 
 $ContextFile = $Options['context_file']
@@ -70,11 +94,14 @@ if ($cm) {
 }
 
 if (-not $PlanPath) {
-    # Discover plan.md one level deep (specs/<feature>/plan.md), matching the
-    # bash glob specs/*/plan.md. Wrap in try/catch so access errors under
+    # Discover plan.md exactly one level deep (specs/<feature>/plan.md),
+    # matching the bash glob specs/*/plan.md. Wrap in try/catch so access errors under
     # $ErrorActionPreference = 'Stop' don't abort the script.
     try {
-        $candidate = Get-ChildItem -Path (Join-Path $ProjectRoot 'specs') -Filter 'plan.md' -Recurse -Depth 1 -ErrorAction SilentlyContinue |
+        $specsDir = Join-Path $ProjectRoot 'specs'
+        $candidate = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |
+            ForEach-Object { Get-Item -LiteralPath (Join-Path $_.FullName 'plan.md') -ErrorAction SilentlyContinue } |
+            Where-Object { $_ } |
             Sort-Object LastWriteTime -Descending |
             Select-Object -First 1
         if ($candidate) {

src/specify_cli/integrations/base.py

@@ -579,7 +579,8 @@ def upsert_context_section(
         managed section.  If it exists, the content between the configured
         start/end markers (default ``<!-- SPECKIT START -->`` /
         ``<!-- SPECKIT END -->``) is replaced, or appended when no markers
-        are found.  Markers are read from ``.specify/init-options.json``
+        are found. Markers are read from the agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
         when present, falling back to the class-level constants.
 
         Returns the path to the context file, or ``None`` when
@@ -656,8 +657,9 @@ def remove_context_section(self, project_root: Path) -> bool:
         """Remove the managed section from the agent context file.
 
         Returns ``True`` if the section was found and removed.  If the
-        file becomes empty (or whitespace-only) after removal it is
-        deleted.  Markers are read from ``.specify/init-options.json``
+        file becomes empty (or whitespace-only) after removal it is deleted.
+        Markers are read from the agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
         when present, falling back to the class-level constants.
         """
         if not self.context_file: