github · amirreza225 · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026
@@ -10,9 +10,9 @@
 #
 # Usage: update-agent-context.sh [plan_path]
 #
-# When `plan_path` is omitted, the script picks the most recently modified
-# `specs/*/plan.md` if any exist, otherwise emits the section without a
-# concrete plan path.
+# When `plan_path` is omitted, the script derives it from `.specify/feature.json`
+# (written by /speckit-specify). Falls back to the most recently modified
+# `specs/*/plan.md` only when feature.json is absent or its plan does not exist yet.
 
 set -euo pipefail
 
@@ -202,23 +202,78 @@ unset _cf_parts _seg
 
 PLAN_PATH="${1:-}"
 if [[ -z "$PLAN_PATH" ]]; then
-  # Pick the most recently modified plan.md one level deep (specs/<feature>/plan.md).
-  # Use find + sort by modification time to avoid ls/head fragility with
-  # spaces in paths or SIGPIPE from pipefail.
-  _plan_abs="$("$_python" - "$PROJECT_ROOT" <<'PY'
-import sys, os
-from pathlib import Path
-specs = Path(sys.argv[1]) / "specs"
+  # Prefer .specify/feature.json (written by /speckit-specify) over mtime heuristic.
+  _feature_json="$PROJECT_ROOT/.specify/feature.json"
+  if [[ -f "$_feature_json" ]]; then
+    _feature_dir="$("$_python" - "$_feature_json" <<'PY'
+import sys, json
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        d = json.load(fh)
+    val = d.get("feature_directory", "")
+    print(val if isinstance(val, str) else "")
+except Exception:
+    print("")
+PY
+)"
+    # Normalize backslashes (written by PS on Windows) to forward slashes before path ops.
+    _feature_dir="$(printf '%s' "$_feature_dir" | tr '\\' '/')"
+    _feature_dir="${_feature_dir%/}"
+    if [[ -n "$_feature_dir" ]]; then
+      # feature_directory may be relative or absolute (absolute paths outside PROJECT_ROOT
+      # are preserved as-is by _persist_feature_json in common.sh).
+      # Also match drive-qualified paths (C:/...) written by PowerShell on Windows.
+      if [[ "$_feature_dir" == /* ]] || [[ "$_feature_dir" =~ ^[A-Za-z]:/ ]]; then
+        _candidate="$_feature_dir/plan.md"
+      else
+        _candidate="$PROJECT_ROOT/$_feature_dir/plan.md"
+      fi
+      if [[ -f "$_candidate" ]]; then
+        # Resolve symlinks before comparing so paths like /var/… vs /private/var/…
+        # (macOS) are treated as equivalent. Mirrors the mtime-fallback approach.
+        PLAN_PATH="$("$_python" - "$PROJECT_ROOT" "$_candidate" <<'PY'
+import sys
+from pathlib import Path, PurePosixPath
+root = Path(sys.argv[1]).resolve()
+cand = Path(sys.argv[2]).resolve()
+try:
+    print(cand.relative_to(root).as_posix())
+except ValueError:
+    # Outside project root: use the bash-side path (already forward-slash
+    # normalised via tr), not cand which may be a WindowsPath with backslashes.
+    print(sys.argv[2])
+PY
+)"
+      fi
+    fi
+  fi
+
+  # Fall back to mtime only when feature.json is absent or its plan does not exist yet.
+  # Python emits a project-relative POSIX path directly to avoid bash prefix-strip
+  # issues with backslash paths on Windows (Git bash / MSYS2).
+  if [[ -z "$PLAN_PATH" ]]; then
+    _plan_rel="$("$_python" - "$PROJECT_ROOT" <<'PY'
+import sys
+from pathlib import Path, PurePosixPath
+root = Path(sys.argv[1]).resolve()
+specs = root / "specs"
 plans = sorted(
     specs.glob("*/plan.md"),
     key=lambda p: p.stat().st_mtime,
     reverse=True,
 )
-print(plans[0] if plans else "")
+if plans:
+    try:
+        print(plans[0].relative_to(root).as_posix())
+    except ValueError:
+        print("")
+else:
+    print("")
 PY
 )"
-  if [[ -n "$_plan_abs" ]]; then
-    PLAN_PATH="${_plan_abs#"$PROJECT_ROOT/"}"
+    if [[ -n "$_plan_rel" ]]; then
+      PLAN_PATH="$_plan_rel"
+    fi
   fi
 fi
 

@@ -9,6 +9,10 @@
 #   .specify/extensions/agent-context/agent-context-config.yml
 #
 # Usage: update-agent-context.ps1 [plan_path]
+#
+# When `plan_path` is omitted, the script derives it from `.specify/feature.json`
+# (written by /speckit-specify). Falls back to the most recently modified
+# `specs/*/plan.md` only when feature.json is absent or its plan does not exist yet.
 
 [CmdletBinding()]
 param(
@@ -126,14 +130,26 @@ if (-not (Test-Path -LiteralPath $ExtConfig)) {
 $Options = $null
 if (Get-Command ConvertFrom-Yaml -ErrorAction SilentlyContinue) {
     try {
-        $Options = Get-Content -LiteralPath $ExtConfig -Raw | ConvertFrom-Yaml -ErrorAction Stop
+        $Options = Get-Content -LiteralPath $ExtConfig -Raw -Encoding UTF8 | ConvertFrom-Yaml -ErrorAction Stop
     } catch {
         # fall through to Python fallback
     }
 }
 
 if ($null -eq $Options) {
-    # ConvertFrom-Yaml unavailable or failed; fall back to Python+PyYAML.
+    # ConvertFrom-Yaml unavailable or failed; try ConvertFrom-Json (no external deps,
+    # works when the config file is valid JSON, which is a subset of YAML).
+    try {
+        $raw = Get-Content -LiteralPath $ExtConfig -Raw -Encoding UTF8
+        $Options = $raw | ConvertFrom-Json -ErrorAction Stop
+        if (-not (Test-ConfigObject -Object $Options)) { $Options = $null }
+    } catch {
+        $Options = $null
+    }
+}
+
+if ($null -eq $Options) {
+    # ConvertFrom-Yaml/Json unavailable or failed; fall back to Python+PyYAML.
     $pythonCmd = $null
     $pythonCandidates = @()
     if ($env:SPECKIT_PYTHON) {
@@ -280,21 +296,69 @@ if ($cm) {
 }
 
 if (-not $PlanPath) {
-    # 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 {
-        $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) {
-            $PlanPath = [System.IO.Path]::GetRelativePath($ProjectRoot, $candidate.FullName).Replace('\','/')
+    # Prefer .specify/feature.json (written by /speckit-specify) over mtime heuristic.
+    $FeatureJson = Join-Path $ProjectRoot '.specify/feature.json'
+    if (Test-Path -LiteralPath $FeatureJson) {
+        try {
+            $fj = Get-Content -LiteralPath $FeatureJson -Raw -Encoding UTF8 | ConvertFrom-Json
+            $featureDir = $fj.feature_directory
+            if ($featureDir -isnot [string] -or -not $featureDir) {
+                $featureDir = $null
+            } else {
+                $featureDir = $featureDir.TrimEnd('\', '/')
+            }
+            if ($featureDir) {
+                # Join-Path on Unix does not treat absolute ChildPath as "wins"; check explicitly.
+                if ([System.IO.Path]::IsPathRooted($featureDir)) {
+                    $candidatePlan = Join-Path $featureDir 'plan.md'
+                } else {
+                    $candidatePlan = Join-Path (Join-Path $ProjectRoot $featureDir) 'plan.md'
+                }
+                if (Test-Path -LiteralPath $candidatePlan) {
+                    # Resolve ./ .. segments before relativizing (mirrors bash Path.resolve()).
+                    # GetFullPath is available in .NET Framework 4.x (PS 5.1 compatible).
+                    $resolvedPlan = [System.IO.Path]::GetFullPath($candidatePlan)
+                    $resolvedDir  = [System.IO.Path]::GetDirectoryName($resolvedPlan)
+                    $normRoot = $ProjectRoot.TrimEnd('\', '/') + [System.IO.Path]::DirectorySeparatorChar
+                    $normDir  = $resolvedDir.TrimEnd('\', '/') + [System.IO.Path]::DirectorySeparatorChar
+                    $cmp = if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal }
+                    if ($normDir.StartsWith($normRoot, $cmp)) {
+                        $relDir = $normDir.Substring($normRoot.Length).TrimEnd('\', '/')
+                        $PlanPath = if ($relDir) { $relDir.Replace('\', '/') + '/plan.md' } else { 'plan.md' }
+                    } else {
+                        $PlanPath = $resolvedPlan.Replace('\', '/')
+                    }
+                }
+            }
+        } catch {
+            # Non-fatal: fall through to mtime heuristic.
+        }
+    }
+
+    # Fall back to mtime only when feature.json is absent or its plan does not exist yet.
+    if (-not $PlanPath) {
+        try {
+            $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) {
+                # GetRelativePath is .NET 5+ only; strip prefix manually for PS 5.1 compat.
+                # Use case-insensitive comparison on Windows only (matches common.ps1 pattern).
+                $fullPath = $candidate.FullName.Replace('\', '/')
+                $normRoot = $ProjectRoot.Replace('\', '/').TrimEnd('/') + '/'
+                $cmp = if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal }
+                if ($fullPath.StartsWith($normRoot, $cmp)) {
+                    $PlanPath = $fullPath.Substring($normRoot.Length)
+                } else {
+                    $PlanPath = $fullPath
+                }
+            }
+        } catch {
+            # Non-fatal: continue without a plan path.
         }
-    } catch {
-        # Non-fatal: continue without a plan path.
     }
 }