[Bug]: agent-context extension ignores scoped/nested spec directories (SPECIFY_FEATURE_DIRECTORY), so plan auto-discovery finds nothing

[athemelis]

Bug Description

The agent-context extension's plan auto-discovery uses a one-level glob (specs/*/plan.md). Repos that organize specs in nested/scoped directories via SPECIFY_FEATURE_DIRECTORY (e.g. specs///plan.md) never match, so the SPECKIT block is refreshed without a plan path even when a plan exists. The command doc states the one-level assumption.

Steps to Reproduce

1. Set SPECIFY_FEATURE_DIRECTORY=specs// and run speckit.specify / speckit.plan so a plan lands at specs///plan.md.
2. Let the agent-context after_specify/after_plan hook fire (or run speckit.agent-context.update directly).
3. Inspect the updated SPECKIT block.

Expected Behavior

The extension finds the most-recent plan anywhere under specs/ (including nested specs///plan.md) and includes its path.

Actual Behavior

The one-level glob specs/*/plan.md matches nothing in scoped layouts; the block updates with no plan path.

Specify CLI Version

0.11.0

AI Agent

GitHub Copilot

Operating System

macOS Tahoe 26.5.1

Python Version

3.11.15 (uv-managed standalone CPython, cpython-3.11-macos-aarch64-none — uv installs specify under its own Python, not the system CLT 3.9.6 or Homebrew 3.13/3.14)

Error Logs

none (silent; no error raised, plan path simply absent)

Additional Context

Files: .specify/extensions/agent-context/scripts/bash/update-agent-context.sh (glob specs.glob("*/plan.md")), .../powershell/update-agent-context.ps1, .../commands/speckit.agent-context.update.md (docs). Suggested fix: recurse (specs/**/plan.md) and pick the most-recently-modified match. Related to two sibling issues filed alongside (feature.json write side-effect; empty CURRENT_BRANCH).

[github-actions]

Bug assessment — plan-discovery-nested-specs: Valid · severity medium

---

Bug Assessment: agent-context Plan Auto-Discovery Misses Nested Spec Dirs

• Slug: plan-discovery-nested-specs
• Created: 2026-06-17T22:19:48Z
• Source: issue [Bug]: agent-context extension ignores scoped/nested spec directories (SPECIFY_FEATURE_DIRECTORY), so plan auto-discovery finds nothing #3024
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @athemelis (v0.11.0, macOS, Python 3.11.15, GitHub Copilot integration).

When SPECIFY_FEATURE_DIRECTORY points to a scoped/nested path (e.g. specs/sub/feature/), the speckit.agent-context.update command (and its backing after_specify/after_plan hooks) silently refreshes the SPECKIT block with no plan path. No error is raised. The issue cites three files and a suggested fix: widen the glob from specs/*/plan.md to specs/**/plan.md.

Symptom

When a project uses a nested feature directory (specs/<scope>/<feature>/plan.md), the SPECKIT managed block is updated without a plan reference because the one-level glob specs/*/plan.md never matches the deeper path. The expected behavior is that the most recently modified plan.md anywhere under specs/ is found and included.

Reproduction

1. In a Specify-initialized project, set SPECIFY_FEATURE_DIRECTORY=specs/scope/feature and run speckit.specify or speckit.plan so a plan is created at specs/scope/feature/plan.md.
2. Allow the after_specify/after_plan hook to fire (or run speckit.agent-context.update directly).
3. Inspect the updated SPECKIT block in the agent context file (e.g. CLAUDE.md).
4. Observe that the at specs/... line is absent.

Suspected Code Paths

• extensions/agent-context/scripts/bash/update-agent-context.sh:133 — Python inline script uses specs.glob("*/plan.md"), a one-level glob that skips any plan.md more than one directory deep.
• extensions/agent-context/scripts/bash/update-agent-context.sh:14,125 — Comments explicitly document the one-level assumption (specs/*/plan.md), confirming intentional (now incorrect) design.
• extensions/agent-context/scripts/powershell/update-agent-context.ps1:172-178 — PowerShell version uses Get-ChildItem -Path $specsDir -Directory (non-recursive) followed by Join-Path $_.FullName 'plan.md', which checks only immediate children of specs/, mirroring the same limitation.
• extensions/agent-context/commands/speckit.agent-context.update.md:17,26 — Documentation states the one-level specs/<feature>/plan.md assumption, which is now incorrect for scoped layouts.

Root Cause Hypothesis

The auto-discovery was implemented with the default single-level layout (specs/<feature>/plan.md) in mind and was never updated to handle the scoped/nested layout enabled by SPECIFY_FEATURE_DIRECTORY. The Python pathlib.Path.glob("*/plan.md") pattern and its PowerShell equivalent each enumerate exactly one directory level below specs/, so plans at depth ≥ 2 are invisible. The bug is silent: no exception is thrown, the script simply finds zero candidates and writes the block without a plan reference. Confidence: high — the code and the symptom align exactly.

Proposed Remediation

Preferred: Replace the one-level glob with a recursive one in both scripts, then update the documentation.

• Bash script (update-agent-context.sh, line 133): change specs.glob("*/plan.md") to specs.glob("**/plan.md"). The ** pattern in pathlib recurses into all subdirectories. The rest of the logic (sort by st_mtime, pick index 0) is unchanged.
• PowerShell script (update-agent-context.ps1, lines 172–178): replace the two-step Get-ChildItem -Directory | ForEach-Object { Get-Item plan.md } with a single Get-ChildItem -Path $specsDir -Recurse -Filter "plan.md" -File -ErrorAction SilentlyContinue, then sort by LastWriteTime descending and take the first result — same algorithm, recursive traversal.
• Command doc (speckit.agent-context.update.md, lines 17 and 26): update prose from specs/<feature>/plan.md / specs/*/plan.md to specs/**/plan.md (or "most recently modified plan.md anywhere under specs/").

Alternatives:

• Limit recursion depth (e.g. specs/*/*/plan.md for exactly two levels). Trade-off: still fragile if nesting goes deeper; the ** approach is more future-proof with negligible performance cost on typical project sizes.
• Require an explicit plan_path argument when SPECIFY_FEATURE_DIRECTORY is nested, and document this. Trade-off: worsens DX and doesn't solve the hook-invocation case where the argument is always omitted.

Files likely to change:

• extensions/agent-context/scripts/bash/update-agent-context.sh
• extensions/agent-context/scripts/powershell/update-agent-context.ps1
• extensions/agent-context/commands/speckit.agent-context.update.md
• tests/extensions/test_extension_agent_context.py (new test cases)

Tests to add or update:

• Add a test in tests/extensions/test_extension_agent_context.py that creates a specs/scope/feature/plan.md (depth 2) and verifies the bash/PowerShell scripts (or the Python integration layer upsert_context_section) find it — analogous to the existing test_upsert_replaces_existing_custom_section fixture.
• Add a test asserting that when multiple nested plans exist, the most recently modified one wins.
• Update the docstring/comment in update-agent-context.sh to reflect the new recursive behavior.

Risks & Considerations

• Performance: **/plan.md will recurse the entire specs/ tree. On very large repos with many specs this adds marginal I/O overhead, but plan files are few and specs/ is typically shallow — negligible in practice.
• Disambiguation: With **/plan.md, multiple plans at different depths may all match. The tie-breaking rule (most recently modified) already exists and remains correct; no API change needed.
• No API breakage: The change is purely internal to the discovery logic. The script's public interface (optional plan_path argument) and output format are unchanged.
• PowerShell Get-ChildItem -Recurse: available in all supported PowerShell versions (5.1+, PS Core 7+); no compatibility risk.

Generated by 🐛 Assess Bug from Labeled Issue for issue #3024 · 172.9 AIC · ⌖ 13.6 AIC · ⊞ 32.7K · ◷