chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,67 @@
|
||||
# Coding Agent Context Extension
|
||||
|
||||
This bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.
|
||||
|
||||
It owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `<!-- SPECKIT START -->` / `<!-- SPECKIT END -->`).
|
||||
|
||||
## Why an extension?
|
||||
|
||||
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:
|
||||
|
||||
- **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** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in `extension.yml` (`after_specify`, `after_plan`). Invoke it using your agent's slash-command separator — `/speckit.agent-context.update` for dot-separator agents or `/speckit-agent-context-update` for hyphen-separator agents (e.g. Forge, Cline).
|
||||
|
||||
## Commands
|
||||
|
||||
The command ID below is canonical. When invoking it as a slash command, use your agent's separator: `/speckit.agent-context.update` for dot-separator agents or `/speckit-agent-context-update` for hyphen-separator agents (e.g. Forge, Cline).
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |
|
||||
|
||||
## Configuration
|
||||
|
||||
All configuration flows through the extension's own config file at
|
||||
`.specify/extensions/agent-context/agent-context-config.yml`:
|
||||
|
||||
```yaml
|
||||
# Path to the coding agent context file managed by this extension
|
||||
context_file: CLAUDE.md
|
||||
|
||||
# Optional list of coding agent context files to manage together.
|
||||
# When non-empty, this takes precedence over context_file.
|
||||
context_files:
|
||||
- AGENTS.md
|
||||
- CLAUDE.md
|
||||
|
||||
# Delimiters for the managed Spec Kit section
|
||||
context_markers:
|
||||
start: "<!-- SPECKIT START -->"
|
||||
end: "<!-- SPECKIT END -->"
|
||||
```
|
||||
|
||||
- `context_file` — the project-relative path to the coding agent context file. When empty, the bundled update scripts self-seed it by looking up the active integration's key in this extension's own `agent-context-defaults.json` map. The Specify CLI is never consulted.
|
||||
- `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.
|
||||
|
||||
## Requirements
|
||||
|
||||
The bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).
|
||||
|
||||
PyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports *"PyYAML is required … not available in the current Python environment"*, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:
|
||||
|
||||
```bash
|
||||
pip install pyyaml
|
||||
# or target the specific interpreter Spec Kit uses:
|
||||
/path/to/speckit-python -m pip install pyyaml
|
||||
```
|
||||
|
||||
## Disable
|
||||
|
||||
```bash
|
||||
specify extension disable agent-context
|
||||
```
|
||||
|
||||
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. The Specify CLI carries no agent-context state at all: it never reads this config, never resolves a context file, and the `__CONTEXT_FILE__` placeholder (if present in any template) is left untouched. All context-file knowledge — including the per-agent default mapping in `agent-context-defaults.json` — lives entirely within this extension, so disabling it is a complete opt-out.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Coding Agent Context Extension Configuration
|
||||
# These values are populated automatically by `specify init` and
|
||||
# `specify integration use` / `specify integration install`.
|
||||
|
||||
# Path (relative to the project root) to the default coding agent context file
|
||||
# managed by this extension (e.g. CLAUDE.md, AGENTS.md,
|
||||
# .github/copilot-instructions.md). Set automatically from the active
|
||||
# integration and regenerated during `specify init` or integration switches.
|
||||
context_file: ""
|
||||
|
||||
# Optional list of project-relative coding agent context files managed by this
|
||||
# extension. When non-empty, this list takes precedence over `context_file`.
|
||||
# Use this for projects that intentionally keep multiple agent anchors in sync.
|
||||
context_files: []
|
||||
|
||||
# Delimiters for the managed Spec Kit section.
|
||||
# Edit these to use custom markers.
|
||||
context_markers:
|
||||
start: "<!-- SPECKIT START -->"
|
||||
end: "<!-- SPECKIT END -->"
|
||||
@@ -0,0 +1,40 @@
|
||||
{
|
||||
"_comment": "Default coding agent context file per integration, owned by the agent-context extension. Used to self-seed agent-context-config.yml when it declares no context_file/context_files. Keyed by the Spec Kit integration key recorded in .specify/init-options.json. This mapping is independent of the Specify CLI by design.",
|
||||
"agents": {
|
||||
"agy": "AGENTS.md",
|
||||
"amp": "AGENTS.md",
|
||||
"auggie": ".augment/rules/specify-rules.md",
|
||||
"bob": "AGENTS.md",
|
||||
"claude": "CLAUDE.md",
|
||||
"cline": ".clinerules/specify-rules.md",
|
||||
"codebuddy": "CODEBUDDY.md",
|
||||
"codex": "AGENTS.md",
|
||||
"copilot": ".github/copilot-instructions.md",
|
||||
"cursor-agent": ".cursor/rules/specify-rules.mdc",
|
||||
"devin": "AGENTS.md",
|
||||
"firebender": ".firebender/rules/specify-rules.mdc",
|
||||
"forge": "AGENTS.md",
|
||||
"gemini": "GEMINI.md",
|
||||
"generic": "AGENTS.md",
|
||||
"goose": "AGENTS.md",
|
||||
"hermes": "AGENTS.md",
|
||||
"junie": ".junie/AGENTS.md",
|
||||
"kilocode": ".kilocode/rules/specify-rules.md",
|
||||
"kimi": "AGENTS.md",
|
||||
"kiro-cli": "AGENTS.md",
|
||||
"lingma": ".lingma/rules/specify-rules.md",
|
||||
"omp": "AGENTS.md",
|
||||
"opencode": "AGENTS.md",
|
||||
"pi": "AGENTS.md",
|
||||
"qodercli": "QODER.md",
|
||||
"qwen": "QWEN.md",
|
||||
"rovodev": "AGENTS.md",
|
||||
"shai": "SHAI.md",
|
||||
"tabnine": "TABNINE.md",
|
||||
"trae": ".trae/rules/project_rules.md",
|
||||
"vibe": "AGENTS.md",
|
||||
"windsurf": ".windsurf/rules/specify-rules.md",
|
||||
"zcode": "ZCODE.md",
|
||||
"zed": "AGENTS.md"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
description: "Refresh the managed Spec Kit section in coding agent context file(s)"
|
||||
---
|
||||
|
||||
# Update Coding Agent Context
|
||||
|
||||
Refresh the managed Spec Kit section inside the active coding agent's context/instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`).
|
||||
|
||||
## Behavior
|
||||
|
||||
The script reads the agent-context extension config at
|
||||
`.specify/extensions/agent-context/agent-context-config.yml` to discover:
|
||||
|
||||
- `context_file` — the path of the coding agent context file to manage.
|
||||
- `context_files` — optional project-relative paths for multiple coding agent context files. When non-empty, the script updates each listed file and the list takes precedence over `context_file`.
|
||||
- `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` when the field is missing.
|
||||
|
||||
It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (any `plan.md` under `specs/`, including nested scoped layouts such as `specs/<scope>/<feature>/plan.md`).
|
||||
|
||||
If `context_files` and `context_file` are empty, the command reports nothing to do and exits successfully. Context file paths must stay project-relative; absolute paths, Windows drive paths, backslash separators, and `..` path segments are rejected.
|
||||
|
||||
## Execution
|
||||
|
||||
- **Bash**: `.specify/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]`
|
||||
- **PowerShell**: `.specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]`
|
||||
|
||||
When `plan_path` is omitted, the script auto-detects the most recently modified `specs/**/plan.md` (searched recursively, so nested scoped layouts are discovered).
|
||||
@@ -0,0 +1,34 @@
|
||||
schema_version: "1.0"
|
||||
|
||||
extension:
|
||||
id: agent-context
|
||||
name: "Coding Agent Context"
|
||||
version: "1.0.0"
|
||||
description: "Manages coding agent context/instruction files (e.g., CLAUDE.md, copilot-instructions.md) with project-specific plan references and configurable markers"
|
||||
author: spec-kit-core
|
||||
repository: https://github.com/github/spec-kit
|
||||
license: MIT
|
||||
|
||||
requires:
|
||||
speckit_version: ">=0.2.0"
|
||||
|
||||
provides:
|
||||
commands:
|
||||
- name: speckit.agent-context.update
|
||||
file: commands/speckit.agent-context.update.md
|
||||
description: "Refresh the managed Spec Kit section in the coding agent context file"
|
||||
|
||||
hooks:
|
||||
after_specify:
|
||||
command: speckit.agent-context.update
|
||||
optional: true
|
||||
description: "Refresh agent context after specification"
|
||||
after_plan:
|
||||
command: speckit.agent-context.update
|
||||
optional: true
|
||||
description: "Refresh agent context after planning"
|
||||
|
||||
tags:
|
||||
- "agent"
|
||||
- "context"
|
||||
- "core"
|
||||
@@ -0,0 +1,448 @@
|
||||
#!/usr/bin/env bash
|
||||
# update-agent-context.sh
|
||||
#
|
||||
# Refresh the managed Spec Kit section in the coding agent's context file(s)
|
||||
# (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md).
|
||||
#
|
||||
# Reads `context_files` or `context_file`, plus `context_markers.{start,end}`, from the
|
||||
# agent-context extension config:
|
||||
# .specify/extensions/agent-context/agent-context-config.yml
|
||||
#
|
||||
# Usage: update-agent-context.sh [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
|
||||
|
||||
PROJECT_ROOT="$(pwd)"
|
||||
EXT_CONFIG="$PROJECT_ROOT/.specify/extensions/agent-context/agent-context-config.yml"
|
||||
DEFAULT_START="<!-- SPECKIT START -->"
|
||||
DEFAULT_END="<!-- SPECKIT END -->"
|
||||
|
||||
if [[ ! -f "$EXT_CONFIG" ]]; then
|
||||
echo "agent-context: $EXT_CONFIG not found; nothing to do." >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Locate a Python 3 interpreter with PyYAML available.
|
||||
_python=""
|
||||
_python_candidates=()
|
||||
[[ -n "${SPECKIT_PYTHON:-}" ]] && _python_candidates+=("$SPECKIT_PYTHON")
|
||||
_python_candidates+=("python3" "python")
|
||||
for _candidate in "${_python_candidates[@]}"; do
|
||||
if command -v "$_candidate" >/dev/null 2>&1 \
|
||||
&& "$_candidate" - <<'PY' >/dev/null 2>&1
|
||||
import sys
|
||||
try:
|
||||
import yaml # noqa: F401
|
||||
except ImportError:
|
||||
sys.exit(1)
|
||||
sys.exit(0 if sys.version_info[0] == 3 else 1)
|
||||
PY
|
||||
then
|
||||
_python="$_candidate"
|
||||
break
|
||||
fi
|
||||
done
|
||||
unset _candidate _python_candidates
|
||||
|
||||
if [[ -z "$_python" ]]; then
|
||||
echo "agent-context: Python 3 with PyYAML not found on PATH; skipping update." >&2
|
||||
echo " To resolve: pip install pyyaml (or install it into the environment used by python3)." >&2
|
||||
exit 0
|
||||
fi
|
||||
_case_insensitive_context_files=0
|
||||
case "$(uname -s 2>/dev/null || true)" in
|
||||
MINGW*|MSYS*|CYGWIN*) _case_insensitive_context_files=1 ;;
|
||||
esac
|
||||
|
||||
# Parse extension config once; emit context files as JSON, followed by marker strings.
|
||||
#
|
||||
# NOTE (bash 3.2 / macOS portability): the embedded Python heredocs below run
|
||||
# inside $(...) command substitution. bash 3.2 (the system /bin/bash on macOS)
|
||||
# mis-parses a single-quote/apostrophe in a heredoc body nested in $(...),
|
||||
# failing with "unexpected EOF while looking for matching `''". Keep these
|
||||
# $(...)-nested heredoc bodies free of apostrophes (use double quotes in Python
|
||||
# string literals and avoid contractions in comments).
|
||||
if ! _raw_opts="$("$_python" - "$EXT_CONFIG" "$_case_insensitive_context_files" "$PROJECT_ROOT" <<'PY'
|
||||
import json
|
||||
import sys
|
||||
try:
|
||||
import yaml
|
||||
except ImportError:
|
||||
print(
|
||||
"agent-context: PyYAML is required to parse extension config but is not available "
|
||||
"in the current Python environment.\n"
|
||||
" To resolve: pip install pyyaml (or install it into the environment used by python3).\n"
|
||||
" Context file will not be updated until PyYAML is importable.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
sys.exit(2)
|
||||
try:
|
||||
with open(sys.argv[1], "r", encoding="utf-8") as fh:
|
||||
data = yaml.safe_load(fh)
|
||||
except Exception as exc:
|
||||
print(
|
||||
f"agent-context: unable to parse {sys.argv[1]} ({exc}); cannot update context.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
sys.exit(2)
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
def get_str(obj, *keys):
|
||||
node = obj
|
||||
for k in keys:
|
||||
if isinstance(node, dict) and k in node:
|
||||
node = node[k]
|
||||
else:
|
||||
return ""
|
||||
return node if isinstance(node, str) else ""
|
||||
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:
|
||||
add_context_file(value)
|
||||
if not context_files:
|
||||
add_context_file(get_str(data, "context_file"))
|
||||
if not context_files:
|
||||
# Self-seed: the agent-context extension manages its own lifecycle, so when
|
||||
# its config declares no target, it derives one from the active integration
|
||||
# recorded in init-options.json, mapped through the bundled
|
||||
# agent-context-defaults.json file. This is independent of the Specify CLI
|
||||
# by design; nothing here imports specify_cli.
|
||||
project_root = sys.argv[3] if len(sys.argv) > 3 else "."
|
||||
integration_key = ""
|
||||
try:
|
||||
with open(
|
||||
f"{project_root}/.specify/init-options.json", "r", encoding="utf-8"
|
||||
) as fh:
|
||||
opts = json.load(fh)
|
||||
if isinstance(opts, dict):
|
||||
value = opts.get("integration") or opts.get("ai") or ""
|
||||
integration_key = value if isinstance(value, str) else ""
|
||||
except Exception:
|
||||
integration_key = ""
|
||||
if integration_key:
|
||||
defaults_path = (
|
||||
f"{project_root}/.specify/extensions/agent-context/"
|
||||
"agent-context-defaults.json"
|
||||
)
|
||||
mapping = {}
|
||||
try:
|
||||
with open(defaults_path, "r", encoding="utf-8") as fh:
|
||||
loaded = json.load(fh)
|
||||
agents = loaded.get("agents", {}) if isinstance(loaded, dict) else {}
|
||||
mapping = agents if isinstance(agents, dict) else {}
|
||||
except Exception:
|
||||
print(
|
||||
"agent-context: unable to read %s; cannot self-seed the context "
|
||||
"file. Set context_file in the extension config." % defaults_path,
|
||||
file=sys.stderr,
|
||||
)
|
||||
mapping = {}
|
||||
add_context_file(mapping.get(integration_key, "") or "")
|
||||
if not context_files:
|
||||
print(
|
||||
"agent-context: no default context file is known for integration "
|
||||
"%s. Set context_file in the extension config to choose one."
|
||||
% integration_key,
|
||||
file=sys.stderr,
|
||||
)
|
||||
print(json.dumps(context_files))
|
||||
print(get_str(data, "context_markers", "start"))
|
||||
print(get_str(data, "context_markers", "end"))
|
||||
PY
|
||||
)"; then
|
||||
echo "agent-context: skipping update (see above for details)." >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
_opts_lines=()
|
||||
while IFS= read -r _line || [[ -n "$_line" ]]; do
|
||||
_opts_lines+=("$_line")
|
||||
done < <(printf '%s\n' "$_raw_opts")
|
||||
if (( ${#_opts_lines[@]} < 3 )); then
|
||||
echo "agent-context: malformed config parser output; expected 3 lines (context_files, marker_start, marker_end), got ${#_opts_lines[@]}; skipping update." >&2
|
||||
exit 0
|
||||
fi
|
||||
CONTEXT_FILES_JSON="${_opts_lines[0]}"
|
||||
MARKER_START="${_opts_lines[1]}"
|
||||
MARKER_END="${_opts_lines[2]}"
|
||||
|
||||
if ! _context_files_raw="$("$_python" - "$CONTEXT_FILES_JSON" <<'PY'
|
||||
import json
|
||||
import sys
|
||||
try:
|
||||
data = json.loads(sys.argv[1])
|
||||
except Exception:
|
||||
data = []
|
||||
if not isinstance(data, list):
|
||||
data = []
|
||||
for value in data:
|
||||
if isinstance(value, str) and value:
|
||||
print(value)
|
||||
PY
|
||||
)"; then
|
||||
echo "agent-context: malformed context_files parser output; skipping update." >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
CONTEXT_FILES=()
|
||||
while IFS= read -r _line || [[ -n "$_line" ]]; do
|
||||
[[ -n "$_line" ]] && CONTEXT_FILES+=("$_line")
|
||||
done < <(printf '%s\n' "$_context_files_raw")
|
||||
|
||||
if (( ${#CONTEXT_FILES[@]} == 0 )); then
|
||||
echo "agent-context: context_files/context_file not set in extension config; nothing to do." >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
for CONTEXT_FILE in "${CONTEXT_FILES[@]}"; do
|
||||
# Reject absolute paths, backslash separators, and '..' path segments in context files
|
||||
if [[ "$CONTEXT_FILE" == /* ]] || [[ "$CONTEXT_FILE" =~ ^[A-Za-z]: ]]; then
|
||||
echo "agent-context: context files must be project-relative paths; got '$CONTEXT_FILE'." >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ "$CONTEXT_FILE" == *\\* ]]; then
|
||||
echo "agent-context: context files must not contain backslash separators; got '$CONTEXT_FILE'." >&2
|
||||
exit 1
|
||||
fi
|
||||
IFS='/' read -ra _cf_parts <<< "$CONTEXT_FILE"
|
||||
for _seg in "${_cf_parts[@]}"; do
|
||||
if [[ "$_seg" == ".." ]]; then
|
||||
echo "agent-context: context files must not contain '..' path segments; got '$CONTEXT_FILE'." >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
if ! "$_python" - "$PROJECT_ROOT" "$CONTEXT_FILE" <<'PY'
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
root = Path(sys.argv[1]).resolve()
|
||||
target = (root / sys.argv[2]).resolve(strict=False)
|
||||
try:
|
||||
target.relative_to(root)
|
||||
except ValueError:
|
||||
sys.exit(1)
|
||||
PY
|
||||
then
|
||||
echo "agent-context: context file path resolves outside the project root; got '$CONTEXT_FILE'." >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
unset _cf_parts _seg
|
||||
|
||||
[[ -z "$MARKER_START" ]] && MARKER_START="$DEFAULT_START"
|
||||
[[ -z "$MARKER_END" ]] && MARKER_END="$DEFAULT_END"
|
||||
|
||||
PLAN_PATH="${1:-}"
|
||||
if [[ -z "$PLAN_PATH" ]]; then
|
||||
# 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
|
||||
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: emit the resolved path in POSIX form.
|
||||
# as_posix() converts backslashes correctly on native Windows Python.
|
||||
print(cand.as_posix())
|
||||
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
|
||||
root = Path(sys.argv[1]).resolve()
|
||||
specs = root / "specs"
|
||||
|
||||
def _resolved_rel(p):
|
||||
# Resolve symlinks before checking containment: relative_to() is lexical
|
||||
# and would otherwise accept a plan reached through a specs/ symlink that
|
||||
# points outside the project, emitting an in-project-looking path for an
|
||||
# out-of-project file (or picking it as "most recent").
|
||||
try:
|
||||
return p.resolve().relative_to(root)
|
||||
except (OSError, ValueError):
|
||||
return None
|
||||
|
||||
# Recurse (rather than the old one-level specs/*/plan.md glob) so scoped layouts
|
||||
# created via SPECIFY_FEATURE_DIRECTORY, e.g. specs/<scope>/<feature>/plan.md,
|
||||
# are still discovered when feature.json is absent (#3024).
|
||||
candidates = []
|
||||
for p in specs.rglob("plan.md"):
|
||||
rel = _resolved_rel(p)
|
||||
if rel:
|
||||
candidates.append((p, rel))
|
||||
candidates.sort(key=lambda pr: pr[0].stat().st_mtime, reverse=True)
|
||||
if candidates:
|
||||
print(candidates[0][1].as_posix())
|
||||
else:
|
||||
print("")
|
||||
PY
|
||||
)"
|
||||
if [[ -n "$_plan_rel" ]]; then
|
||||
PLAN_PATH="$_plan_rel"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Build the managed section
|
||||
TMP_SECTION="$(mktemp)"
|
||||
trap 'rm -f "$TMP_SECTION"' EXIT
|
||||
{
|
||||
echo "$MARKER_START"
|
||||
echo "For additional context about technologies to be used, project structure,"
|
||||
echo "shell commands, and other important information, read the current plan"
|
||||
if [[ -n "$PLAN_PATH" ]]; then
|
||||
echo "at $PLAN_PATH"
|
||||
fi
|
||||
echo "$MARKER_END"
|
||||
} > "$TMP_SECTION"
|
||||
|
||||
for CONTEXT_FILE in "${CONTEXT_FILES[@]}"; do
|
||||
CTX_PATH="$PROJECT_ROOT/$CONTEXT_FILE"
|
||||
mkdir -p "$(dirname "$CTX_PATH")"
|
||||
|
||||
"$_python" - "$CTX_PATH" "$MARKER_START" "$MARKER_END" "$TMP_SECTION" <<'PY'
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
|
||||
ctx_path, start, end, section_path = sys.argv[1:5]
|
||||
with open(section_path, "r", encoding="utf-8") as fh:
|
||||
section = fh.read().rstrip("\n") + "\n"
|
||||
|
||||
|
||||
def ensure_mdc_frontmatter(content):
|
||||
"""Ensure ``.mdc`` content has YAML frontmatter with ``alwaysApply: true``.
|
||||
|
||||
Cursor only auto-loads ``.mdc`` rule files that carry frontmatter with
|
||||
``alwaysApply: true``. Prepend it when missing, or repair the value while
|
||||
preserving any existing frontmatter comments/formatting.
|
||||
"""
|
||||
leading_ws = len(content) - len(content.lstrip())
|
||||
leading = content[:leading_ws]
|
||||
stripped = content[leading_ws:]
|
||||
|
||||
if not stripped.startswith("---"):
|
||||
return "---\nalwaysApply: true\n---\n\n" + content
|
||||
|
||||
match = re.match(
|
||||
r"^(---[ \t]*\r?\n)(.*?)(\r?\n---[ \t]*)(\r?\n|$)(.*)",
|
||||
stripped,
|
||||
re.DOTALL,
|
||||
)
|
||||
if not match:
|
||||
return "---\nalwaysApply: true\n---\n\n" + content
|
||||
|
||||
opening, fm_text, closing, sep, rest = match.groups()
|
||||
newline = "\r\n" if "\r\n" in opening else "\n"
|
||||
|
||||
if re.search(r"(?m)^[ \t]*alwaysApply[ \t]*:[ \t]*true[ \t]*(?:#.*)?$", fm_text):
|
||||
return content
|
||||
|
||||
if re.search(r"(?m)^[ \t]*alwaysApply[ \t]*:", fm_text):
|
||||
fm_text = re.sub(
|
||||
r"(?m)^([ \t]*)alwaysApply[ \t]*:.*?([ \t]*(?:#.*)?)$",
|
||||
r"\1alwaysApply: true\2",
|
||||
fm_text,
|
||||
count=1,
|
||||
)
|
||||
elif fm_text.strip():
|
||||
fm_text = fm_text + newline + "alwaysApply: true"
|
||||
else:
|
||||
fm_text = "alwaysApply: true"
|
||||
|
||||
return f"{leading}{opening}{fm_text}{closing}{sep}{rest}"
|
||||
|
||||
|
||||
if os.path.exists(ctx_path):
|
||||
with open(ctx_path, "r", encoding="utf-8-sig") as fh:
|
||||
content = fh.read()
|
||||
s = content.find(start)
|
||||
e = content.find(end, s if s != -1 else 0)
|
||||
if s != -1 and e != -1 and e > s:
|
||||
end_of_marker = e + len(end)
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\r":
|
||||
end_of_marker += 1
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\n":
|
||||
end_of_marker += 1
|
||||
new_content = content[:s] + section + content[end_of_marker:]
|
||||
elif s != -1:
|
||||
new_content = content[:s] + section
|
||||
elif e != -1:
|
||||
end_of_marker = e + len(end)
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\r":
|
||||
end_of_marker += 1
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\n":
|
||||
end_of_marker += 1
|
||||
new_content = section + content[end_of_marker:]
|
||||
else:
|
||||
if content and not content.endswith("\n"):
|
||||
content += "\n"
|
||||
new_content = (content + "\n" + section) if content else section
|
||||
else:
|
||||
new_content = section
|
||||
|
||||
new_content = new_content.replace("\r\n", "\n").replace("\r", "\n")
|
||||
if ctx_path.casefold().endswith(".mdc"):
|
||||
new_content = ensure_mdc_frontmatter(new_content)
|
||||
with open(ctx_path, "wb") as fh:
|
||||
fh.write(new_content.encode("utf-8"))
|
||||
PY
|
||||
|
||||
echo "agent-context: updated $CONTEXT_FILE"
|
||||
done
|
||||
@@ -0,0 +1,509 @@
|
||||
#!/usr/bin/env pwsh
|
||||
# update-agent-context.ps1
|
||||
#
|
||||
# Refresh the managed Spec Kit section in the coding agent's context file(s)
|
||||
# (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md).
|
||||
#
|
||||
# Reads `context_files` or `context_file`, plus `context_markers.{start,end}`, from the
|
||||
# agent-context extension config:
|
||||
# .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(
|
||||
[Parameter(Position = 0)]
|
||||
[string]$PlanPath
|
||||
)
|
||||
|
||||
function Add-MdcFrontmatter {
|
||||
<#
|
||||
Ensure .mdc content has YAML frontmatter with alwaysApply: true.
|
||||
|
||||
Cursor only auto-loads .mdc rule files that carry frontmatter with
|
||||
alwaysApply: true. Prepend it when missing, or repair the value while
|
||||
preserving any existing frontmatter comments/formatting.
|
||||
#>
|
||||
param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$Content)
|
||||
|
||||
$leading = ''
|
||||
$stripped = $Content
|
||||
$m = [regex]::Match($Content, '^\s*')
|
||||
if ($m.Success) {
|
||||
$leading = $m.Value
|
||||
$stripped = $Content.Substring($m.Length)
|
||||
}
|
||||
|
||||
if (-not $stripped.StartsWith('---')) {
|
||||
return "---`nalwaysApply: true`n---`n`n" + $Content
|
||||
}
|
||||
|
||||
$fm = [regex]::Match($stripped, '^(---[ \t]*\r?\n)(.*?)(\r?\n---[ \t]*)(\r?\n|$)(.*)', [System.Text.RegularExpressions.RegexOptions]::Singleline)
|
||||
if (-not $fm.Success) {
|
||||
return "---`nalwaysApply: true`n---`n`n" + $Content
|
||||
}
|
||||
|
||||
$opening = $fm.Groups[1].Value
|
||||
$fmText = $fm.Groups[2].Value
|
||||
$closing = $fm.Groups[3].Value
|
||||
$sep = $fm.Groups[4].Value
|
||||
$rest = $fm.Groups[5].Value
|
||||
$newline = if ($opening.Contains("`r`n")) { "`r`n" } else { "`n" }
|
||||
|
||||
if ([regex]::IsMatch($fmText, '(?m)^[ \t]*alwaysApply[ \t]*:[ \t]*true[ \t]*(?:#.*)?$')) {
|
||||
return $Content
|
||||
}
|
||||
|
||||
if ([regex]::IsMatch($fmText, '(?m)^[ \t]*alwaysApply[ \t]*:')) {
|
||||
$alwaysApplyRegex = [regex]'(?m)^([ \t]*)alwaysApply[ \t]*:.*?([ \t]*(?:#.*)?)$'
|
||||
$fmText = $alwaysApplyRegex.Replace($fmText, '${1}alwaysApply: true${2}', 1)
|
||||
} elseif ($fmText.Trim()) {
|
||||
$fmText = $fmText + $newline + 'alwaysApply: true'
|
||||
} else {
|
||||
$fmText = 'alwaysApply: true'
|
||||
}
|
||||
|
||||
return "$leading$opening$fmText$closing$sep$rest"
|
||||
}
|
||||
|
||||
function Get-ConfigValue {
|
||||
param(
|
||||
[AllowNull()][object]$Object,
|
||||
[Parameter(Mandatory = $true)][string]$Key
|
||||
)
|
||||
|
||||
if ($null -eq $Object) {
|
||||
return $null
|
||||
}
|
||||
if ($Object -is [System.Collections.IDictionary]) {
|
||||
return $Object[$Key]
|
||||
}
|
||||
$prop = $Object.PSObject.Properties[$Key]
|
||||
if ($prop) {
|
||||
return $prop.Value
|
||||
}
|
||||
return $null
|
||||
}
|
||||
|
||||
function Test-ConfigObject {
|
||||
param(
|
||||
[AllowNull()][object]$Object
|
||||
)
|
||||
|
||||
if ($null -eq $Object) {
|
||||
return $false
|
||||
}
|
||||
if ($Object -is [System.Collections.IDictionary]) {
|
||||
return $true
|
||||
}
|
||||
if ($Object -is [System.Management.Automation.PSCustomObject]) {
|
||||
return $true
|
||||
}
|
||||
return $false
|
||||
}
|
||||
|
||||
function Resolve-ContextPath {
|
||||
param(
|
||||
[Parameter(Mandatory = $true)][string]$Root,
|
||||
[Parameter(Mandatory = $true)][string]$RelativePath
|
||||
)
|
||||
|
||||
$rootFull = [System.IO.Path]::GetFullPath($Root)
|
||||
$segments = $RelativePath -split '/'
|
||||
$resolved = $rootFull
|
||||
|
||||
foreach ($segment in $segments) {
|
||||
if ([string]::IsNullOrWhiteSpace($segment) -or $segment -eq '.') {
|
||||
continue
|
||||
}
|
||||
|
||||
$candidate = [System.IO.Path]::GetFullPath((Join-Path $resolved $segment))
|
||||
if (Test-Path -LiteralPath $candidate) {
|
||||
$item = Get-Item -LiteralPath $candidate -Force
|
||||
if ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) {
|
||||
$target = $item.Target
|
||||
if ($target -is [System.Array]) {
|
||||
$target = $target[0]
|
||||
}
|
||||
if ($target) {
|
||||
if ([System.IO.Path]::IsPathRooted($target)) {
|
||||
$candidate = [System.IO.Path]::GetFullPath($target)
|
||||
} else {
|
||||
$candidate = [System.IO.Path]::GetFullPath(
|
||||
(Join-Path (Split-Path -Parent $candidate) $target)
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
$resolved = $candidate
|
||||
}
|
||||
|
||||
return $resolved
|
||||
}
|
||||
|
||||
function Test-IsSubPath {
|
||||
param(
|
||||
[Parameter(Mandatory = $true)][string]$Root,
|
||||
[Parameter(Mandatory = $true)][string]$Path
|
||||
)
|
||||
|
||||
$comparison = if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) {
|
||||
[System.StringComparison]::OrdinalIgnoreCase
|
||||
} else {
|
||||
[System.StringComparison]::Ordinal
|
||||
}
|
||||
$rootFull = [System.IO.Path]::GetFullPath($Root).TrimEnd(
|
||||
[System.IO.Path]::DirectorySeparatorChar,
|
||||
[System.IO.Path]::AltDirectorySeparatorChar
|
||||
)
|
||||
$pathFull = [System.IO.Path]::GetFullPath($Path)
|
||||
return $pathFull.Equals($rootFull, $comparison) -or
|
||||
$pathFull.StartsWith($rootFull + [System.IO.Path]::DirectorySeparatorChar, $comparison)
|
||||
}
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$DefaultStart = '<!-- SPECKIT START -->'
|
||||
$DefaultEnd = '<!-- SPECKIT END -->'
|
||||
$ProjectRoot = (Get-Location).Path
|
||||
$ExtConfig = Join-Path $ProjectRoot '.specify/extensions/agent-context/agent-context-config.yml'
|
||||
|
||||
if (-not (Test-Path -LiteralPath $ExtConfig)) {
|
||||
Write-Warning "agent-context: $ExtConfig not found; nothing to do."
|
||||
exit 0
|
||||
}
|
||||
|
||||
$Options = $null
|
||||
if (Get-Command ConvertFrom-Yaml -ErrorAction SilentlyContinue) {
|
||||
try {
|
||||
$Options = Get-Content -LiteralPath $ExtConfig -Raw -Encoding UTF8 | ConvertFrom-Yaml -ErrorAction Stop
|
||||
} catch {
|
||||
# fall through to ConvertFrom-Json fallback
|
||||
}
|
||||
}
|
||||
|
||||
if ($null -eq $Options) {
|
||||
# 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) {
|
||||
$pythonCandidates += $env:SPECKIT_PYTHON
|
||||
}
|
||||
$pythonCandidates += @('python3', 'python')
|
||||
foreach ($candidate in $pythonCandidates) {
|
||||
if (Get-Command $candidate -ErrorAction SilentlyContinue) {
|
||||
# Verify it is Python 3 with PyYAML available.
|
||||
$null = & $candidate -c "import sys; import yaml; sys.exit(0 if sys.version_info[0] == 3 else 1)" 2>$null
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
$pythonCmd = $candidate
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if ($pythonCmd) {
|
||||
$pyScript = $null
|
||||
try {
|
||||
$pyScript = [System.IO.Path]::GetTempFileName()
|
||||
Set-Content -LiteralPath $pyScript -Encoding UTF8 -Value @'
|
||||
import json
|
||||
import sys
|
||||
try:
|
||||
import yaml
|
||||
except ImportError:
|
||||
print(
|
||||
"agent-context: PyYAML is required to parse extension config; cannot update context.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
sys.exit(2)
|
||||
|
||||
try:
|
||||
with open(sys.argv[1], "r", encoding="utf-8") as fh:
|
||||
data = yaml.safe_load(fh)
|
||||
except Exception as exc:
|
||||
print(
|
||||
f"agent-context: unable to parse {sys.argv[1]} ({exc}); cannot update context.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
sys.exit(2)
|
||||
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
|
||||
print(json.dumps(data))
|
||||
'@
|
||||
$jsonOut = & $pythonCmd $pyScript $ExtConfig
|
||||
if ($LASTEXITCODE -eq 0 -and $jsonOut) {
|
||||
$Options = $jsonOut | ConvertFrom-Json -ErrorAction Stop
|
||||
}
|
||||
} catch {
|
||||
$Options = $null
|
||||
} finally {
|
||||
if ($pyScript -and (Test-Path -LiteralPath $pyScript)) {
|
||||
Remove-Item -LiteralPath $pyScript -Force -ErrorAction SilentlyContinue
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $Options) {
|
||||
Write-Warning "agent-context: unable to parse $ExtConfig; skipping update."
|
||||
exit 0
|
||||
}
|
||||
}
|
||||
|
||||
if (-not (Test-ConfigObject -Object $Options)) {
|
||||
Write-Warning "agent-context: $ExtConfig must contain a YAML mapping; skipping update."
|
||||
exit 0
|
||||
}
|
||||
|
||||
$ConfiguredContextFiles = Get-ConfigValue -Object $Options -Key 'context_files'
|
||||
$ContextFiles = @()
|
||||
if ($null -ne $ConfiguredContextFiles) {
|
||||
foreach ($item in @($ConfiguredContextFiles)) {
|
||||
if ($item -is [string] -and -not [string]::IsNullOrWhiteSpace($item)) {
|
||||
$ContextFiles += $item.Trim()
|
||||
}
|
||||
}
|
||||
}
|
||||
if ($ContextFiles.Count -eq 0) {
|
||||
$ContextFile = Get-ConfigValue -Object $Options -Key 'context_file'
|
||||
if ($ContextFile -is [string] -and -not [string]::IsNullOrWhiteSpace($ContextFile)) {
|
||||
$ContextFiles += $ContextFile.Trim()
|
||||
}
|
||||
}
|
||||
$pathComparison = if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) {
|
||||
[System.StringComparer]::OrdinalIgnoreCase
|
||||
} else {
|
||||
[System.StringComparer]::Ordinal
|
||||
}
|
||||
$seenContextFiles = [System.Collections.Generic.HashSet[string]]::new($pathComparison)
|
||||
$dedupedContextFiles = @()
|
||||
foreach ($ContextFile in $ContextFiles) {
|
||||
if ($seenContextFiles.Add($ContextFile)) {
|
||||
$dedupedContextFiles += $ContextFile
|
||||
}
|
||||
}
|
||||
$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, using the extension's OWN bundled mapping
|
||||
# (agent-context-defaults.json). Independent of the Specify CLI by design.
|
||||
$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) {
|
||||
$defaultsPath = Join-Path $ProjectRoot '.specify/extensions/agent-context/agent-context-defaults.json'
|
||||
if (Test-Path -LiteralPath $defaultsPath) {
|
||||
$defaults = Get-Content -LiteralPath $defaultsPath -Raw | ConvertFrom-Json -ErrorAction Stop
|
||||
$derived = $null
|
||||
if ($defaults.PSObject.Properties['agents'] -and $defaults.agents.PSObject.Properties[$integrationKey]) {
|
||||
$derived = [string]$defaults.agents.PSObject.Properties[$integrationKey].Value
|
||||
}
|
||||
if ($derived -and -not [string]::IsNullOrWhiteSpace($derived)) {
|
||||
$ContextFiles += $derived.Trim()
|
||||
} else {
|
||||
Write-Warning ("agent-context: no default context file is known for integration '{0}'; set 'context_file' in the extension config to choose one." -f $integrationKey)
|
||||
}
|
||||
} else {
|
||||
Write-Warning ("agent-context: unable to read {0}; cannot self-seed the context file. Set 'context_file' in the extension config." -f $defaultsPath)
|
||||
}
|
||||
}
|
||||
} 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
|
||||
}
|
||||
|
||||
foreach ($ContextFile in $ContextFiles) {
|
||||
# Reject absolute paths, drive-qualified paths, backslash separators, and '..' path segments in context files
|
||||
if ($ContextFile -match '^[A-Za-z]:') {
|
||||
Write-Warning "agent-context: context files must be project-relative paths; got '$ContextFile'."
|
||||
exit 1
|
||||
}
|
||||
if ([System.IO.Path]::IsPathRooted($ContextFile)) {
|
||||
Write-Warning "agent-context: context files must be project-relative paths; got '$ContextFile'."
|
||||
exit 1
|
||||
}
|
||||
if ($ContextFile.Contains('\')) {
|
||||
Write-Warning "agent-context: context files must not contain backslash separators; got '$ContextFile'."
|
||||
exit 1
|
||||
}
|
||||
$cfSegments = $ContextFile -split '[/\\]'
|
||||
if ($cfSegments -contains '..') {
|
||||
Write-Warning "agent-context: context files must not contain '..' path segments; got '$ContextFile'."
|
||||
exit 1
|
||||
}
|
||||
$resolvedTarget = Resolve-ContextPath -Root $ProjectRoot -RelativePath $ContextFile
|
||||
if (-not (Test-IsSubPath -Root $ProjectRoot -Path $resolvedTarget)) {
|
||||
Write-Warning "agent-context: context file path resolves outside the project root; got '$ContextFile'."
|
||||
exit 1
|
||||
}
|
||||
}
|
||||
|
||||
$MarkerStart = $DefaultStart
|
||||
$MarkerEnd = $DefaultEnd
|
||||
$cm = Get-ConfigValue -Object $Options -Key 'context_markers'
|
||||
if ($cm) {
|
||||
$cmStart = Get-ConfigValue -Object $cm -Key 'start'
|
||||
if ($cmStart -is [string] -and $cmStart) {
|
||||
$MarkerStart = $cmStart
|
||||
}
|
||||
$cmEnd = Get-ConfigValue -Object $cm -Key 'end'
|
||||
if ($cmEnd -is [string] -and $cmEnd) {
|
||||
$MarkerEnd = $cmEnd
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $PlanPath) {
|
||||
# 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'
|
||||
# Recurse (rather than the old one-level specs/*/plan.md scan) so scoped
|
||||
# layouts created via SPECIFY_FEATURE_DIRECTORY, e.g.
|
||||
# specs/<scope>/<feature>/plan.md, are still discovered when
|
||||
# feature.json is absent (#3024).
|
||||
$candidate = Get-ChildItem -Path $specsDir -Filter 'plan.md' -File -Recurse -ErrorAction SilentlyContinue |
|
||||
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.
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$lines = @($MarkerStart,
|
||||
'For additional context about technologies to be used, project structure,',
|
||||
'shell commands, and other important information, read the current plan')
|
||||
if ($PlanPath) {
|
||||
$lines += "at $PlanPath"
|
||||
}
|
||||
$lines += $MarkerEnd
|
||||
$Section = ($lines -join "`n") + "`n"
|
||||
|
||||
foreach ($ContextFile in $ContextFiles) {
|
||||
$CtxPath = Join-Path $ProjectRoot $ContextFile
|
||||
$CtxDir = Split-Path -Parent $CtxPath
|
||||
if ($CtxDir -and -not (Test-Path -LiteralPath $CtxDir)) {
|
||||
New-Item -ItemType Directory -Path $CtxDir -Force | Out-Null
|
||||
}
|
||||
|
||||
if (Test-Path -LiteralPath $CtxPath) {
|
||||
$rawBytes = [System.IO.File]::ReadAllBytes($CtxPath)
|
||||
# Strip UTF-8 BOM if present
|
||||
if ($rawBytes.Length -ge 3 -and $rawBytes[0] -eq 0xEF -and $rawBytes[1] -eq 0xBB -and $rawBytes[2] -eq 0xBF) {
|
||||
$content = [System.Text.Encoding]::UTF8.GetString($rawBytes, 3, $rawBytes.Length - 3)
|
||||
} else {
|
||||
$content = [System.Text.Encoding]::UTF8.GetString($rawBytes)
|
||||
}
|
||||
|
||||
$s = $content.IndexOf($MarkerStart)
|
||||
$e = if ($s -ge 0) { $content.IndexOf($MarkerEnd, $s) } else { $content.IndexOf($MarkerEnd) }
|
||||
|
||||
if ($s -ge 0 -and $e -ge 0 -and $e -gt $s) {
|
||||
$endOfMarker = $e + $MarkerEnd.Length
|
||||
if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
|
||||
if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
|
||||
$newContent = $content.Substring(0, $s) + $Section + $content.Substring($endOfMarker)
|
||||
} elseif ($s -ge 0) {
|
||||
$newContent = $content.Substring(0, $s) + $Section
|
||||
} elseif ($e -ge 0) {
|
||||
$endOfMarker = $e + $MarkerEnd.Length
|
||||
if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
|
||||
if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
|
||||
$newContent = $Section + $content.Substring($endOfMarker)
|
||||
} else {
|
||||
if ($content -and -not $content.EndsWith("`n")) { $content += "`n" }
|
||||
if ($content) { $newContent = $content + "`n" + $Section } else { $newContent = $Section }
|
||||
}
|
||||
} else {
|
||||
$newContent = $Section
|
||||
}
|
||||
|
||||
$newContent = $newContent.Replace("`r`n", "`n").Replace("`r", "`n")
|
||||
if ($ContextFile -match '\.mdc$') {
|
||||
$newContent = Add-MdcFrontmatter -Content $newContent
|
||||
}
|
||||
[System.IO.File]::WriteAllText($CtxPath, $newContent, (New-Object System.Text.UTF8Encoding($false)))
|
||||
|
||||
Write-Host "agent-context: updated $ContextFile"
|
||||
}
|
||||
@@ -0,0 +1,352 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Refresh the managed Spec Kit section in the coding agent's context file(s).
|
||||
|
||||
Python port of ``update-agent-context.sh`` / ``update-agent-context.ps1``.
|
||||
|
||||
Reads ``context_files`` or ``context_file``, plus ``context_markers.{start,end}``,
|
||||
from the agent-context extension config:
|
||||
.specify/extensions/agent-context/agent-context-config.yml
|
||||
|
||||
Usage: update_agent_context.py [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.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
DEFAULT_START = "<!-- SPECKIT START -->"
|
||||
DEFAULT_END = "<!-- SPECKIT END -->"
|
||||
|
||||
|
||||
def _err(message: str) -> None:
|
||||
print(message, file=sys.stderr)
|
||||
|
||||
|
||||
def _get_str(obj: object, *keys: str) -> str:
|
||||
node = obj
|
||||
for key in keys:
|
||||
if isinstance(node, dict) and key in node:
|
||||
node = node[key]
|
||||
else:
|
||||
return ""
|
||||
return node if isinstance(node, str) else ""
|
||||
|
||||
|
||||
def _collect_context_files(data: dict, project_root: str) -> list[str]:
|
||||
"""Resolve the managed context files from config, mirroring the bash logic."""
|
||||
context_files: list[str] = []
|
||||
seen: set[str] = set()
|
||||
case_insensitive = sys.platform.startswith(("win32", "cygwin", "msys"))
|
||||
|
||||
def add(value: object) -> None:
|
||||
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:
|
||||
return
|
||||
context_files.append(candidate)
|
||||
seen.add(key)
|
||||
|
||||
raw_files = data.get("context_files")
|
||||
if isinstance(raw_files, list):
|
||||
for value in raw_files:
|
||||
add(value)
|
||||
if not context_files:
|
||||
add(_get_str(data, "context_file"))
|
||||
if not context_files:
|
||||
# Self-seed: when the config declares no target, derive one from the
|
||||
# active integration recorded in init-options.json, mapped through the
|
||||
# bundled agent-context-defaults.json file. Independent of the Specify
|
||||
# CLI by design.
|
||||
integration_key = ""
|
||||
try:
|
||||
with open(
|
||||
f"{project_root}/.specify/init-options.json", "r", encoding="utf-8"
|
||||
) as fh:
|
||||
opts = json.load(fh)
|
||||
if isinstance(opts, dict):
|
||||
value = opts.get("integration") or opts.get("ai") or ""
|
||||
integration_key = value if isinstance(value, str) else ""
|
||||
except Exception:
|
||||
integration_key = ""
|
||||
if integration_key:
|
||||
defaults_path = (
|
||||
f"{project_root}/.specify/extensions/agent-context/"
|
||||
"agent-context-defaults.json"
|
||||
)
|
||||
mapping = {}
|
||||
try:
|
||||
with open(defaults_path, "r", encoding="utf-8") as fh:
|
||||
loaded = json.load(fh)
|
||||
agents = loaded.get("agents", {}) if isinstance(loaded, dict) else {}
|
||||
mapping = agents if isinstance(agents, dict) else {}
|
||||
except Exception:
|
||||
_err(
|
||||
"agent-context: unable to read %s; cannot self-seed the context "
|
||||
"file. Set context_file in the extension config." % defaults_path
|
||||
)
|
||||
mapping = {}
|
||||
add(mapping.get(integration_key, "") or "")
|
||||
if not context_files:
|
||||
_err(
|
||||
"agent-context: no default context file is known for integration "
|
||||
"%s. Set context_file in the extension config to choose one."
|
||||
% integration_key
|
||||
)
|
||||
return context_files
|
||||
|
||||
|
||||
def _validate_context_file(project_root: str, context_file: str) -> str | None:
|
||||
"""Return an error message when the path escapes the project root."""
|
||||
if context_file.startswith("/") or re.match(r"^[A-Za-z]:", context_file):
|
||||
return (
|
||||
"agent-context: context files must be project-relative paths; "
|
||||
f"got '{context_file}'."
|
||||
)
|
||||
if "\\" in context_file:
|
||||
return (
|
||||
"agent-context: context files must not contain backslash separators; "
|
||||
f"got '{context_file}'."
|
||||
)
|
||||
if ".." in context_file.split("/"):
|
||||
return (
|
||||
"agent-context: context files must not contain '..' path segments; "
|
||||
f"got '{context_file}'."
|
||||
)
|
||||
root = Path(project_root).resolve()
|
||||
target = (root / context_file).resolve()
|
||||
try:
|
||||
target.relative_to(root)
|
||||
except ValueError:
|
||||
return (
|
||||
"agent-context: context file path resolves outside the project root; "
|
||||
f"got '{context_file}'."
|
||||
)
|
||||
return None
|
||||
|
||||
|
||||
def _resolve_plan_path(project_root: str) -> str:
|
||||
"""Derive the plan path: feature.json first, then the mtime fallback."""
|
||||
plan_path = ""
|
||||
feature_json = Path(project_root) / ".specify" / "feature.json"
|
||||
if feature_json.is_file():
|
||||
feature_dir = ""
|
||||
try:
|
||||
with open(feature_json, "r", encoding="utf-8") as fh:
|
||||
data = json.load(fh)
|
||||
value = data.get("feature_directory", "")
|
||||
feature_dir = value if isinstance(value, str) else ""
|
||||
except Exception:
|
||||
feature_dir = ""
|
||||
# Normalize backslashes (written by PS on Windows) before path ops.
|
||||
feature_dir = feature_dir.replace("\\", "/").rstrip("/")
|
||||
if feature_dir:
|
||||
# feature_directory may be relative or absolute (absolute paths
|
||||
# outside the project root are preserved as-is), including
|
||||
# drive-qualified paths (C:/...) written by PowerShell on Windows.
|
||||
if feature_dir.startswith("/") or re.match(r"^[A-Za-z]:/", feature_dir):
|
||||
candidate = Path(feature_dir) / "plan.md"
|
||||
else:
|
||||
candidate = Path(project_root) / feature_dir / "plan.md"
|
||||
if candidate.is_file():
|
||||
# Resolve symlinks before comparing so paths like /var/… vs
|
||||
# /private/var/… (macOS) are treated as equivalent.
|
||||
root = Path(project_root).resolve()
|
||||
resolved = candidate.resolve()
|
||||
try:
|
||||
plan_path = resolved.relative_to(root).as_posix()
|
||||
except ValueError:
|
||||
plan_path = resolved.as_posix()
|
||||
|
||||
if not plan_path:
|
||||
root = Path(project_root).resolve()
|
||||
plans = sorted(
|
||||
(root / "specs").glob("*/plan.md"),
|
||||
key=lambda p: p.stat().st_mtime,
|
||||
reverse=True,
|
||||
)
|
||||
if plans:
|
||||
try:
|
||||
plan_path = plans[0].relative_to(root).as_posix()
|
||||
except ValueError:
|
||||
plan_path = ""
|
||||
return plan_path
|
||||
|
||||
|
||||
def _build_section(marker_start: str, marker_end: str, plan_path: str) -> str:
|
||||
lines = [
|
||||
marker_start,
|
||||
"For additional context about technologies to be used, project structure,",
|
||||
"shell commands, and other important information, read the current plan",
|
||||
]
|
||||
if plan_path:
|
||||
lines.append(f"at {plan_path}")
|
||||
lines.append(marker_end)
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
def ensure_mdc_frontmatter(content: str) -> str:
|
||||
"""Ensure ``.mdc`` content has YAML frontmatter with ``alwaysApply: true``.
|
||||
|
||||
Cursor only auto-loads ``.mdc`` rule files that carry frontmatter with
|
||||
``alwaysApply: true``. Prepend it when missing, or repair the value while
|
||||
preserving any existing frontmatter comments/formatting.
|
||||
"""
|
||||
leading_ws = len(content) - len(content.lstrip())
|
||||
leading = content[:leading_ws]
|
||||
stripped = content[leading_ws:]
|
||||
|
||||
if not stripped.startswith("---"):
|
||||
return "---\nalwaysApply: true\n---\n\n" + content
|
||||
|
||||
match = re.match(
|
||||
r"^(---[ \t]*\r?\n)(.*?)(\r?\n---[ \t]*)(\r?\n|$)(.*)",
|
||||
stripped,
|
||||
re.DOTALL,
|
||||
)
|
||||
if not match:
|
||||
return "---\nalwaysApply: true\n---\n\n" + content
|
||||
|
||||
opening, fm_text, closing, sep, rest = match.groups()
|
||||
newline = "\r\n" if "\r\n" in opening else "\n"
|
||||
|
||||
if re.search(r"(?m)^[ \t]*alwaysApply[ \t]*:[ \t]*true[ \t]*(?:#.*)?$", fm_text):
|
||||
return content
|
||||
|
||||
if re.search(r"(?m)^[ \t]*alwaysApply[ \t]*:", fm_text):
|
||||
fm_text = re.sub(
|
||||
r"(?m)^([ \t]*)alwaysApply[ \t]*:.*?([ \t]*(?:#.*)?)$",
|
||||
r"\1alwaysApply: true\2",
|
||||
fm_text,
|
||||
count=1,
|
||||
)
|
||||
elif fm_text.strip():
|
||||
fm_text = fm_text + newline + "alwaysApply: true"
|
||||
else:
|
||||
fm_text = "alwaysApply: true"
|
||||
|
||||
return f"{leading}{opening}{fm_text}{closing}{sep}{rest}"
|
||||
|
||||
|
||||
def _upsert_section(
|
||||
ctx_path: str, marker_start: str, marker_end: str, section: str
|
||||
) -> None:
|
||||
"""Insert or replace the managed section, then normalize and write."""
|
||||
if os.path.exists(ctx_path):
|
||||
with open(ctx_path, "r", encoding="utf-8-sig") as fh:
|
||||
content = fh.read()
|
||||
s = content.find(marker_start)
|
||||
e = content.find(marker_end, s if s != -1 else 0)
|
||||
if s != -1 and e != -1 and e > s:
|
||||
end_of_marker = e + len(marker_end)
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\r":
|
||||
end_of_marker += 1
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\n":
|
||||
end_of_marker += 1
|
||||
new_content = content[:s] + section + content[end_of_marker:]
|
||||
elif s != -1:
|
||||
new_content = content[:s] + section
|
||||
elif e != -1:
|
||||
end_of_marker = e + len(marker_end)
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\r":
|
||||
end_of_marker += 1
|
||||
if end_of_marker < len(content) and content[end_of_marker] == "\n":
|
||||
end_of_marker += 1
|
||||
new_content = section + content[end_of_marker:]
|
||||
else:
|
||||
if content and not content.endswith("\n"):
|
||||
content += "\n"
|
||||
new_content = (content + "\n" + section) if content else section
|
||||
else:
|
||||
new_content = section
|
||||
|
||||
new_content = new_content.replace("\r\n", "\n").replace("\r", "\n")
|
||||
if ctx_path.casefold().endswith(".mdc"):
|
||||
new_content = ensure_mdc_frontmatter(new_content)
|
||||
with open(ctx_path, "wb") as fh:
|
||||
fh.write(new_content.encode("utf-8"))
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
args = sys.argv[1:] if argv is None else argv
|
||||
project_root = os.getcwd()
|
||||
ext_config = (
|
||||
f"{project_root}/.specify/extensions/agent-context/agent-context-config.yml"
|
||||
)
|
||||
|
||||
if not os.path.isfile(ext_config):
|
||||
_err(f"agent-context: {ext_config} not found; nothing to do.")
|
||||
return 0
|
||||
|
||||
try:
|
||||
import yaml
|
||||
except ImportError:
|
||||
_err(
|
||||
"agent-context: PyYAML is required to parse extension config but is "
|
||||
"not available in the current Python environment.\n"
|
||||
" To resolve: pip install pyyaml (or install it into the environment "
|
||||
"used by python3).\n"
|
||||
" Context file will not be updated until PyYAML is importable."
|
||||
)
|
||||
_err("agent-context: skipping update (see above for details).")
|
||||
return 0
|
||||
|
||||
try:
|
||||
with open(ext_config, "r", encoding="utf-8") as fh:
|
||||
data = yaml.safe_load(fh)
|
||||
except Exception as exc:
|
||||
_err(
|
||||
f"agent-context: unable to parse {ext_config} ({exc}); "
|
||||
"cannot update context."
|
||||
)
|
||||
_err("agent-context: skipping update (see above for details).")
|
||||
return 0
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
|
||||
context_files = _collect_context_files(data, project_root)
|
||||
if not context_files:
|
||||
_err(
|
||||
"agent-context: context_files/context_file not set in extension config; "
|
||||
"nothing to do."
|
||||
)
|
||||
return 0
|
||||
|
||||
for context_file in context_files:
|
||||
error = _validate_context_file(project_root, context_file)
|
||||
if error:
|
||||
_err(error)
|
||||
return 1
|
||||
|
||||
marker_start = _get_str(data, "context_markers", "start") or DEFAULT_START
|
||||
marker_end = _get_str(data, "context_markers", "end") or DEFAULT_END
|
||||
|
||||
plan_path = args[0] if args else ""
|
||||
if not plan_path:
|
||||
plan_path = _resolve_plan_path(project_root)
|
||||
|
||||
section = _build_section(marker_start, marker_end, plan_path)
|
||||
|
||||
for context_file in context_files:
|
||||
ctx_path = os.path.join(project_root, context_file)
|
||||
os.makedirs(os.path.dirname(ctx_path) or ".", exist_ok=True)
|
||||
_upsert_section(ctx_path, marker_start, marker_end, section)
|
||||
print(f"agent-context: updated {context_file}")
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in New Issue
Block a user