mirror of
https://github.com/github/spec-kit.git
synced 2026-07-03 20:36:23 +08:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
cee80f7841 |
11
AGENTS.md
11
AGENTS.md
@@ -381,26 +381,25 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):
|
||||
|
||||
## Branch Naming Convention
|
||||
|
||||
Branches follow one of two patterns depending on whether an issue exists:
|
||||
All branches **must** follow this pattern:
|
||||
|
||||
```
|
||||
<type>/<number>-<short-slug> # when an issue is created first
|
||||
<type>/<short-slug> # when no issue exists (PR-only changes)
|
||||
<type>/<number>-<short-slug>
|
||||
```
|
||||
|
||||
When an issue exists, include its number immediately after the prefix — this is what makes branches traceable. For small or self-contained changes that go straight to a PR without a tracking issue, omit the number.
|
||||
Where `<number>` is either an issue number or a PR number — whichever is created first.
|
||||
|
||||
| Prefix | When to use | Example |
|
||||
|---|---|---|
|
||||
| `feat/` | New features | `feat/2342-workflow-cli-alignment` |
|
||||
| `fix/` | Bug fixes | `fix/2653-paths-only-validation` |
|
||||
| `docs/` | Documentation changes | `docs/2677-branch-naming-convention`, `docs/update-landing-stats` |
|
||||
| `docs/` | Documentation changes | `docs/2677-branch-naming-convention` |
|
||||
| `community/` | Community catalog additions | `community/2492-add-mde-extension` |
|
||||
| `chore/` | Maintenance, tooling, CI | `chore/2366-editorconfig` |
|
||||
|
||||
**Rules:**
|
||||
|
||||
1. Include the issue number when one exists — this is what makes branches traceable
|
||||
1. Always include the issue or PR number immediately after the prefix — this is what makes branches traceable
|
||||
2. Use kebab-case for the slug
|
||||
3. Keep the slug short — enough to identify the work without looking up the issue
|
||||
|
||||
|
||||
14
CHANGELOG.md
14
CHANGELOG.md
@@ -2,20 +2,6 @@
|
||||
|
||||
<!-- insert new changelog below this comment -->
|
||||
|
||||
## [0.8.16] - 2026-05-27
|
||||
|
||||
### Changed
|
||||
|
||||
- docs: update landing page stats and branch naming convention (#2727)
|
||||
- feat(workflows): expose {{ context.run_id }} template variable (#2664)
|
||||
- fix: resolve __SPECKIT_COMMAND_*__ refs in preset skill rendering (#2717) (#2718)
|
||||
- Add Workflow Preset to community catalog (#2725)
|
||||
- fix: paths-only skips branch validation, setup-plan preserves existing plan (#2672)
|
||||
- docs: fix broken pipx homepage URLs to point to pipx.pypa.io (#2670)
|
||||
- Update Architecture Guard extension to v1.8.9 (#2723)
|
||||
- Re-validate spec quality checklist after clarify updates spec (#2715)
|
||||
- chore: release 0.8.15, begin 0.8.16.dev0 development (#2722)
|
||||
|
||||
## [0.8.15] - 2026-05-27
|
||||
|
||||
### Changed
|
||||
|
||||
@@ -281,7 +281,7 @@ Our research and experimentation focus on:
|
||||
|
||||
- **Linux/macOS/Windows**
|
||||
- [Supported](#-supported-ai-coding-agent-integrations) AI coding agent.
|
||||
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
|
||||
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
|
||||
- [Python 3.11+](https://www.python.org/downloads/)
|
||||
- [Git](https://git-scm.com/downloads)
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ The following community-contributed extensions are available in [`catalog.commun
|
||||
| AI-Driven Engineering (AIDE) | A structured 7-step workflow for building new projects from scratch with AI assistants — from vision through implementation | `process` | Read+Write | [aide](https://github.com/mnriem/spec-kit-extensions/tree/main/aide) |
|
||||
| API Evolve | Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC | `process` | Read+Write | [spec-kit-api-evolve](https://github.com/Quratulain-bilal/spec-kit-api-evolve) |
|
||||
| Architect Impact Previewer | Predicts architectural impact, complexity, and risks of proposed changes before implementation. | `visibility` | Read-only | [spec-kit-architect-preview](https://github.com/UmmeHabiba1312/spec-kit-architect-preview) |
|
||||
| Architecture Guard | Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) |
|
||||
| Architecture Guard | Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals. | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) |
|
||||
| Architecture Workflow | Generate or reverse project-level 4+1 architecture view artifacts and synthesis | `docs` | Read+Write | [spec-kit-arch](https://github.com/bigsmartben/spec-kit-arch) |
|
||||
| Archive Extension | Archive merged features into main project memory. | `docs` | Read+Write | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) |
|
||||
| Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | `integration` | Read+Write | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
|
||||
|
||||
@@ -27,6 +27,5 @@ The following community-contributed presets customize how Spec Kit behaves — o
|
||||
| Spec2Cloud | Spec-driven workflow tuned for shipping to Azure: spec → plan → tasks → implement → deploy | 5 templates, 8 commands | — | [spec2cloud](https://github.com/Azure-Samples/Spec2Cloud) |
|
||||
| Table of Contents Navigation | Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents | 3 templates, 3 commands | — | [spec-kit-preset-toc-navigation](https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation) |
|
||||
| VS Code Ask Questions | Enhances the clarify command to use `vscode/askQuestions` for batched interactive questioning. | 1 command | — | [spec-kit-presets](https://github.com/fdcastel/spec-kit-presets) |
|
||||
| Workflow Preset | Behavior-first specification, design artifacts, and agent-native handoff orchestration — adds requirement-phase behavior drafts, formal BDD/UIF/behavior contracts, optional design artifacts, and scoped implementation handoffs with Core Agent, Vertical Planner Agent, and Worker Agent modes | 23 templates, 7 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) |
|
||||
|
||||
To build and publish your own preset, see the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md).
|
||||
|
||||
@@ -43,7 +43,7 @@ Run `specify init` with your agent of choice and Spec Kit sets up the right comm
|
||||
|
||||
### Make it your own
|
||||
|
||||
<span class="pillar-stat">105 community extensions</span> (60+ authors), <span class="pillar-stat">22 presets</span>, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
|
||||
<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
|
||||
|
||||
Including entirely different SDD processes:
|
||||
|
||||
@@ -82,7 +82,7 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
|
||||
|
||||
<div class="stats-grid">
|
||||
<div class="stat-item">
|
||||
<span class="stat-number">106K+</span>
|
||||
<span class="stat-number">96K+</span>
|
||||
<span class="stat-label">GitHub stars</span>
|
||||
</div>
|
||||
<div class="stat-item">
|
||||
@@ -94,11 +94,11 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
|
||||
<span class="stat-label">Integrations</span>
|
||||
</div>
|
||||
<div class="stat-item">
|
||||
<span class="stat-number">105</span>
|
||||
<span class="stat-number">91</span>
|
||||
<span class="stat-label">Extensions</span>
|
||||
</div>
|
||||
<div class="stat-item">
|
||||
<span class="stat-number">22</span>
|
||||
<span class="stat-number">18</span>
|
||||
<span class="stat-label">Presets</span>
|
||||
</div>
|
||||
<div class="stat-item">
|
||||
@@ -150,5 +150,3 @@ specify init my-project --integration copilot
|
||||
Ready to start? Follow the [Quick Start Guide](quickstart.md).
|
||||
|
||||
</div>
|
||||
|
||||
<p class="text-end small text-body-secondary">Last updated: May 27, 2026</p>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Installing with pipx
|
||||
|
||||
[pipx](https://pipx.pypa.io/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).
|
||||
[pipx](https://pypa.github.io/pipx/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).
|
||||
|
||||
## Install Specify CLI
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
- **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
|
||||
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
|
||||
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
|
||||
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
|
||||
- [Python 3.11+](https://www.python.org/downloads/)
|
||||
- [Git](https://git-scm.com/downloads)
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-05-27T00:00:00Z",
|
||||
"updated_at": "2026-05-26T00:00:00Z",
|
||||
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
|
||||
"extensions": {
|
||||
"aide": {
|
||||
@@ -240,10 +240,10 @@
|
||||
"architecture-guard": {
|
||||
"name": "Architecture Guard",
|
||||
"id": "architecture-guard",
|
||||
"description": "Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks.",
|
||||
"description": "Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals.",
|
||||
"author": "DyanGalih",
|
||||
"version": "1.8.9",
|
||||
"download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.9.zip",
|
||||
"version": "1.8.4",
|
||||
"download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.4.zip",
|
||||
"repository": "https://github.com/DyanGalih/spec-kit-architecture-guard",
|
||||
"homepage": "https://github.com/DyanGalih/spec-kit-architecture-guard",
|
||||
"documentation": "https://github.com/DyanGalih/spec-kit-architecture-guard/blob/main/README.md",
|
||||
@@ -258,18 +258,17 @@
|
||||
},
|
||||
"tags": [
|
||||
"architecture",
|
||||
"spec-kit",
|
||||
"review",
|
||||
"refactor",
|
||||
"workflow",
|
||||
"governance",
|
||||
"guardrails"
|
||||
"drift-detection",
|
||||
"refactor",
|
||||
"monolithic",
|
||||
"microservices"
|
||||
],
|
||||
"verified": false,
|
||||
"downloads": 0,
|
||||
"stars": 0,
|
||||
"created_at": "2026-05-05T07:26:00Z",
|
||||
"updated_at": "2026-05-27T00:00:00Z"
|
||||
"updated_at": "2026-05-11T14:58:00Z"
|
||||
},
|
||||
"archive": {
|
||||
"name": "Archive Extension",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-05-27T00:00:00Z",
|
||||
"updated_at": "2026-05-26T00:00:00Z",
|
||||
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
|
||||
"presets": {
|
||||
"a11y-governance": {
|
||||
@@ -581,34 +581,6 @@
|
||||
"clarify",
|
||||
"interactive"
|
||||
]
|
||||
},
|
||||
"workflow-preset": {
|
||||
"name": "Workflow Preset",
|
||||
"id": "workflow-preset",
|
||||
"version": "1.2.0",
|
||||
"description": "Behavior-first specification, design artifacts, and agent-native handoff orchestration.",
|
||||
"author": "bigsmartben",
|
||||
"repository": "https://github.com/bigsmartben/spec-kit-workflow-preset",
|
||||
"download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.2.0.zip",
|
||||
"homepage": "https://github.com/bigsmartben/spec-kit-workflow-preset",
|
||||
"documentation": "https://github.com/bigsmartben/spec-kit-workflow-preset/blob/main/README.md",
|
||||
"license": "MIT",
|
||||
"requires": {
|
||||
"speckit_version": ">=0.8.10.dev0"
|
||||
},
|
||||
"provides": {
|
||||
"templates": 23,
|
||||
"commands": 7
|
||||
},
|
||||
"tags": [
|
||||
"behavior",
|
||||
"bdd",
|
||||
"planning",
|
||||
"implementation",
|
||||
"handoff"
|
||||
],
|
||||
"created_at": "2026-05-27T00:00:00Z",
|
||||
"updated_at": "2026-05-27T00:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "specify-cli"
|
||||
version = "0.8.16"
|
||||
version = "0.8.15"
|
||||
description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
|
||||
requires-python = ">=3.11"
|
||||
dependencies = [
|
||||
|
||||
@@ -78,12 +78,13 @@ done
|
||||
SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
source "$SCRIPT_DIR/common.sh"
|
||||
|
||||
# Get feature paths
|
||||
# Get feature paths and validate branch
|
||||
_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
|
||||
eval "$_paths_output"
|
||||
unset _paths_output
|
||||
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
|
||||
|
||||
# If paths-only mode, output paths and exit (no validation)
|
||||
# If paths-only mode, output paths and exit (support JSON + paths-only combined)
|
||||
if $PATHS_ONLY; then
|
||||
if $JSON_MODE; then
|
||||
# Minimal JSON paths payload (no validation performed)
|
||||
@@ -111,9 +112,6 @@ if $PATHS_ONLY; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Validate branch name
|
||||
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
|
||||
|
||||
# Validate required directories and files
|
||||
if [[ ! -d "$FEATURE_DIR" ]]; then
|
||||
echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
|
||||
|
||||
@@ -40,31 +40,15 @@ fi
|
||||
# Ensure the feature directory exists
|
||||
mkdir -p "$FEATURE_DIR"
|
||||
|
||||
# Copy plan template if plan doesn't already exist
|
||||
if [[ -f "$IMPL_PLAN" ]]; then
|
||||
if $JSON_MODE; then
|
||||
echo "Plan already exists at $IMPL_PLAN, skipping template copy" >&2
|
||||
else
|
||||
echo "Plan already exists at $IMPL_PLAN, skipping template copy"
|
||||
fi
|
||||
# Copy plan template if it exists
|
||||
TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
|
||||
if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
|
||||
cp "$TEMPLATE" "$IMPL_PLAN"
|
||||
echo "Copied plan template to $IMPL_PLAN"
|
||||
else
|
||||
TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
|
||||
if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
|
||||
cp "$TEMPLATE" "$IMPL_PLAN"
|
||||
if $JSON_MODE; then
|
||||
echo "Copied plan template to $IMPL_PLAN" >&2
|
||||
else
|
||||
echo "Copied plan template to $IMPL_PLAN"
|
||||
fi
|
||||
else
|
||||
if $JSON_MODE; then
|
||||
echo "Warning: Plan template not found" >&2
|
||||
else
|
||||
echo "Warning: Plan template not found"
|
||||
fi
|
||||
# Create a basic plan file if template doesn't exist
|
||||
touch "$IMPL_PLAN"
|
||||
fi
|
||||
echo "Warning: Plan template not found"
|
||||
# Create a basic plan file if template doesn't exist
|
||||
touch "$IMPL_PLAN"
|
||||
fi
|
||||
|
||||
# Output results
|
||||
|
||||
@@ -56,10 +56,14 @@ EXAMPLES:
|
||||
# Source common functions
|
||||
. "$PSScriptRoot/common.ps1"
|
||||
|
||||
# Get feature paths
|
||||
# Get feature paths and validate branch
|
||||
$paths = Get-FeaturePathsEnv
|
||||
|
||||
# If paths-only mode, output paths and exit (no validation)
|
||||
if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) {
|
||||
exit 1
|
||||
}
|
||||
|
||||
# If paths-only mode, output paths and exit (support combined -Json -PathsOnly)
|
||||
if ($PathsOnly) {
|
||||
if ($Json) {
|
||||
[PSCustomObject]@{
|
||||
@@ -81,11 +85,6 @@ if ($PathsOnly) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# Validate branch name
|
||||
if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) {
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Validate required directories and files
|
||||
if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
|
||||
Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
|
||||
|
||||
@@ -33,25 +33,17 @@ if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFe
|
||||
# Ensure the feature directory exists
|
||||
New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null
|
||||
|
||||
# Copy plan template if plan doesn't already exist
|
||||
if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
|
||||
if ($Json) {
|
||||
[Console]::Error.WriteLine("Plan already exists at $($paths.IMPL_PLAN), skipping template copy")
|
||||
} else {
|
||||
Write-Output "Plan already exists at $($paths.IMPL_PLAN), skipping template copy"
|
||||
}
|
||||
# Copy plan template if it exists, otherwise note it or create empty file
|
||||
$template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
|
||||
if ($template -and (Test-Path $template)) {
|
||||
# Read the template content and write it to the implementation plan file with UTF-8 encoding without BOM
|
||||
$content = [System.IO.File]::ReadAllText($template)
|
||||
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
|
||||
[System.IO.File]::WriteAllText($paths.IMPL_PLAN, $content, $utf8NoBom)
|
||||
} else {
|
||||
$template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
|
||||
if ($template -and (Test-Path $template)) {
|
||||
# Read the template content and write it to the implementation plan file with UTF-8 encoding without BOM
|
||||
$content = [System.IO.File]::ReadAllText($template)
|
||||
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
|
||||
[System.IO.File]::WriteAllText($paths.IMPL_PLAN, $content, $utf8NoBom)
|
||||
} else {
|
||||
Write-Warning "Plan template not found"
|
||||
# Create a basic plan file if template doesn't exist
|
||||
New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
|
||||
}
|
||||
Write-Warning "Plan template not found"
|
||||
# Create a basic plan file if template doesn't exist
|
||||
New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
|
||||
}
|
||||
|
||||
# Output results
|
||||
|
||||
@@ -28,7 +28,6 @@ from packaging import version as pkg_version
|
||||
from packaging.specifiers import SpecifierSet, InvalidSpecifier
|
||||
|
||||
from .extensions import REINSTALL_COMMAND, ExtensionRegistry, normalize_priority
|
||||
from .integrations.base import IntegrationBase
|
||||
|
||||
|
||||
def _substitute_core_template(
|
||||
@@ -1059,9 +1058,6 @@ class PresetManager:
|
||||
body = registrar.resolve_skill_placeholders(
|
||||
selected_ai, fm, body, self.project_root
|
||||
)
|
||||
body = self._resolve_skill_command_refs(
|
||||
body, registrar, selected_ai
|
||||
)
|
||||
fm_data = registrar.build_skill_frontmatter(
|
||||
selected_ai if isinstance(selected_ai, str) else "",
|
||||
skill_name, desc,
|
||||
@@ -1138,23 +1134,6 @@ class PresetManager:
|
||||
title_name = title_name[len("speckit."):]
|
||||
return title_name.replace(".", " ").replace("-", " ").title()
|
||||
|
||||
@staticmethod
|
||||
def _resolve_skill_command_refs(
|
||||
body: str, registrar: "CommandRegistrar", selected_ai: str
|
||||
) -> str:
|
||||
"""Render ``__SPECKIT_COMMAND_*__`` tokens in a skill body as invocations.
|
||||
|
||||
Looks up the agent's invoke separator and rewrites each
|
||||
``__SPECKIT_COMMAND_<NAME>__`` placeholder into the matching
|
||||
slash-command invocation — ``/speckit-<cmd>`` for a ``-`` separator,
|
||||
``/speckit.<cmd>`` for ``.`` — the same rendering the command layer
|
||||
applies via ``CommandRegistrar.register_commands()``.
|
||||
"""
|
||||
separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get(
|
||||
"invoke_separator", "."
|
||||
)
|
||||
return IntegrationBase.resolve_command_refs(body, separator)
|
||||
|
||||
def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:
|
||||
"""Index extension-backed skill restore data by skill directory name."""
|
||||
from .extensions import ExtensionManifest, ValidationError
|
||||
@@ -1331,7 +1310,6 @@ class PresetManager:
|
||||
body = registrar.resolve_skill_placeholders(
|
||||
selected_ai, frontmatter, body, self.project_root
|
||||
)
|
||||
body = self._resolve_skill_command_refs(body, registrar, selected_ai)
|
||||
|
||||
for target_skill_name in target_skill_names:
|
||||
skill_subdir = skills_dir / target_skill_name
|
||||
@@ -1424,9 +1402,6 @@ class PresetManager:
|
||||
body = registrar.resolve_skill_placeholders(
|
||||
selected_ai, frontmatter, body, self.project_root
|
||||
)
|
||||
body = self._resolve_skill_command_refs(
|
||||
body, registrar, selected_ai
|
||||
)
|
||||
|
||||
original_desc = frontmatter.get("description", "")
|
||||
enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
|
||||
@@ -1464,9 +1439,6 @@ class PresetManager:
|
||||
body = registrar.resolve_skill_placeholders(
|
||||
selected_ai, frontmatter, body, self.project_root
|
||||
)
|
||||
body = self._resolve_skill_command_refs(
|
||||
body, registrar, selected_ai
|
||||
)
|
||||
|
||||
command_name = extension_restore["command_name"]
|
||||
title_name = self._skill_title_from_command(command_name)
|
||||
|
||||
@@ -102,15 +102,6 @@ def _build_namespace(context: Any) -> dict[str, Any]:
|
||||
ns["item"] = context.item
|
||||
if hasattr(context, "fan_in"):
|
||||
ns["fan_in"] = context.fan_in or {}
|
||||
# Engine-managed runtime metadata. Always present (even outside a
|
||||
# run) so templates referencing it never error: `run_id` falls back
|
||||
# to an empty string when no run is active (dry-run, validation,
|
||||
# ad-hoc evaluator usage). The value is the same one Spec Kit
|
||||
# prints as `Run ID:` at the end of `workflow run` — auto-generated
|
||||
# runs use an 8-character uuid4 hex; operator-supplied ids may be
|
||||
# any alphanumeric string with hyphens or underscores.
|
||||
run_id = getattr(context, "run_id", None) or ""
|
||||
ns["context"] = {"run_id": run_id}
|
||||
return ns
|
||||
|
||||
|
||||
|
||||
@@ -197,25 +197,6 @@ Execution steps:
|
||||
|
||||
7. Write the updated spec back to `FEATURE_SPEC`.
|
||||
|
||||
8. **Re-validate Spec Quality Checklist** (if it exists):
|
||||
- Check if `FEATURE_DIR/checklists/requirements.md` exists.
|
||||
- If it does NOT exist, skip this step silently.
|
||||
- If it exists:
|
||||
1. Read the checklist file.
|
||||
2. Identify all GitHub task-list checkbox lines — lines matching `- [ ]`, `- [x]`, or `- [X]` (case-insensitive, tolerant of leading whitespace for nested items) outside of code fences. Ignore all other content (headings, notes, non-checkbox bullets, metadata).
|
||||
3. For each checkbox line, record its current marker state (checked or unchecked) and item text into a before-snapshot list.
|
||||
4. Re-evaluate each checkbox item against the **updated** spec (the version just saved in step 7).
|
||||
5. For each checkbox item, update only if the checked/unchecked state actually changes:
|
||||
- If the item now passes and was unchecked: change `[ ]` to `[x]`.
|
||||
- If the item now fails and was checked: change `[x]`/`[X]` to `[ ]`.
|
||||
- If the state is unchanged: leave the marker as-is (preserve existing case to avoid cosmetic diffs).
|
||||
6. Save the updated checklist file. **Only toggle the `[ ]`/`[x]` marker portion of checkbox lines whose state changed.** All other file content — headings, metadata, notes, line ordering, whitespace — must remain unchanged to avoid noisy diffs.
|
||||
7. Compare the before-snapshot with the current state to compute three lists for the Completion Report:
|
||||
- **Newly passing**: items that changed from unchecked to checked.
|
||||
- **Regressions**: items that changed from checked to unchecked.
|
||||
- **Still unchecked**: items that remain unchecked.
|
||||
8. Record the before/after pass counts as checked/total checkbox items (e.g., "12/16 → 15/16 items passing").
|
||||
|
||||
Behavior rules:
|
||||
|
||||
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
|
||||
@@ -267,7 +248,6 @@ Report completion (after questioning loop ends or early termination):
|
||||
- Number of questions asked & answered.
|
||||
- Path to updated spec.
|
||||
- Sections touched (list names).
|
||||
- Spec quality checklist status (if `FEATURE_DIR/checklists/requirements.md` was re-validated): show before/after pass counts (e.g., "Spec Quality Checklist: 12/16 → 15/16 items passing") and list any items that changed state — both newly checked (unchecked → checked) and any regressions (checked → unchecked). If any items remain unchecked, list them as areas needing attention.
|
||||
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
|
||||
- If any Outstanding or Deferred remain, recommend whether to proceed to `__SPECKIT_COMMAND_PLAN__` or run `__SPECKIT_COMMAND_CLARIFY__` again later post-plan.
|
||||
- Suggested next command.
|
||||
@@ -275,6 +255,5 @@ Report completion (after questioning loop ends or early termination):
|
||||
## Done When
|
||||
|
||||
- [ ] Spec ambiguities identified and clarifications integrated into spec file
|
||||
- [ ] Spec quality checklist re-validated against updated spec (if `FEATURE_DIR/checklists/requirements.md` exists)
|
||||
- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
|
||||
- [ ] Completion reported to user with questions answered, sections touched, checklist status, and coverage summary
|
||||
- [ ] Completion reported to user with questions answered, sections touched, and coverage summary
|
||||
|
||||
@@ -1,205 +0,0 @@
|
||||
"""Tests for check-prerequisites --paths-only skipping branch validation (#2653)."""
|
||||
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.conftest import requires_bash
|
||||
|
||||
PROJECT_ROOT = Path(__file__).resolve().parent.parent
|
||||
COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
|
||||
CHECK_PREREQS_SH = PROJECT_ROOT / "scripts" / "bash" / "check-prerequisites.sh"
|
||||
COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
|
||||
CHECK_PREREQS_PS = PROJECT_ROOT / "scripts" / "powershell" / "check-prerequisites.ps1"
|
||||
|
||||
HAS_PWSH = shutil.which("pwsh") is not None
|
||||
_POWERSHELL = shutil.which("powershell.exe") or shutil.which("powershell")
|
||||
|
||||
|
||||
def _install_bash_scripts(repo: Path) -> None:
|
||||
d = repo / ".specify" / "scripts" / "bash"
|
||||
d.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy(COMMON_SH, d / "common.sh")
|
||||
shutil.copy(CHECK_PREREQS_SH, d / "check-prerequisites.sh")
|
||||
|
||||
|
||||
def _install_ps_scripts(repo: Path) -> None:
|
||||
d = repo / ".specify" / "scripts" / "powershell"
|
||||
d.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy(COMMON_PS, d / "common.ps1")
|
||||
shutil.copy(CHECK_PREREQS_PS, d / "check-prerequisites.ps1")
|
||||
|
||||
|
||||
def _clean_env() -> dict[str, str]:
|
||||
env = os.environ.copy()
|
||||
for key in list(env):
|
||||
if key.startswith("SPECIFY_"):
|
||||
env.pop(key)
|
||||
return env
|
||||
|
||||
|
||||
def _git_init(repo: Path) -> None:
|
||||
subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
|
||||
subprocess.run(
|
||||
["git", "config", "user.email", "test@example.com"], cwd=repo, check=True
|
||||
)
|
||||
subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)
|
||||
subprocess.run(
|
||||
["git", "commit", "--allow-empty", "-m", "init", "-q"], cwd=repo, check=True
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def prereq_repo(tmp_path: Path) -> Path:
|
||||
repo = tmp_path / "proj"
|
||||
repo.mkdir()
|
||||
_git_init(repo)
|
||||
(repo / ".specify").mkdir()
|
||||
_install_bash_scripts(repo)
|
||||
_install_ps_scripts(repo)
|
||||
return repo
|
||||
|
||||
|
||||
# ── Bash tests ────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_paths_only_succeeds_on_non_spec_branch(prereq_repo: Path) -> None:
|
||||
"""--paths-only must return paths without branch validation (main branch)."""
|
||||
script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json", "--paths-only"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
assert "REPO_ROOT" in data
|
||||
assert "BRANCH" in data
|
||||
assert "FEATURE_DIR" in data
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_paths_only_succeeds_on_spec_branch(prereq_repo: Path) -> None:
|
||||
"""--paths-only must also work on a properly named spec branch."""
|
||||
subprocess.run(
|
||||
["git", "checkout", "-q", "-b", "001-my-feature"],
|
||||
cwd=prereq_repo,
|
||||
check=True,
|
||||
)
|
||||
script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json", "--paths-only"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
assert "FEATURE_DIR" in data
|
||||
assert "001-my-feature" in data.get("BRANCH", "")
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_paths_only_text_mode_on_non_spec_branch(prereq_repo: Path) -> None:
|
||||
"""--paths-only without --json must return text paths on a non-spec branch."""
|
||||
script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--paths-only"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
assert "REPO_ROOT:" in result.stdout
|
||||
assert "FEATURE_DIR:" in result.stdout
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
|
||||
"""Without --paths-only, branch validation must still fail on main."""
|
||||
script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode != 0
|
||||
assert "Not on a feature branch" in result.stderr
|
||||
|
||||
|
||||
# ── PowerShell tests ──────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
|
||||
def test_ps_paths_only_succeeds_on_non_spec_branch(prereq_repo: Path) -> None:
|
||||
"""-PathsOnly must return paths without branch validation (main branch)."""
|
||||
script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
|
||||
exe = "pwsh" if HAS_PWSH else _POWERSHELL
|
||||
result = subprocess.run(
|
||||
[exe, "-NoProfile", "-File", str(script), "-Json", "-PathsOnly"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
assert "REPO_ROOT" in data
|
||||
assert "BRANCH" in data
|
||||
assert "FEATURE_DIR" in data
|
||||
|
||||
|
||||
@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
|
||||
def test_ps_paths_only_succeeds_on_spec_branch(prereq_repo: Path) -> None:
|
||||
"""-PathsOnly must also work on a properly named spec branch."""
|
||||
subprocess.run(
|
||||
["git", "checkout", "-q", "-b", "001-my-feature"],
|
||||
cwd=prereq_repo,
|
||||
check=True,
|
||||
)
|
||||
script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
|
||||
exe = "pwsh" if HAS_PWSH else _POWERSHELL
|
||||
result = subprocess.run(
|
||||
[exe, "-NoProfile", "-File", str(script), "-Json", "-PathsOnly"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
assert "FEATURE_DIR" in data
|
||||
|
||||
|
||||
@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
|
||||
def test_ps_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
|
||||
"""Without -PathsOnly, branch validation must still fail on main."""
|
||||
script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
|
||||
exe = "pwsh" if HAS_PWSH else _POWERSHELL
|
||||
result = subprocess.run(
|
||||
[exe, "-NoProfile", "-File", str(script), "-Json"],
|
||||
cwd=prereq_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode != 0
|
||||
assert "Not on a feature branch" in result.stderr
|
||||
@@ -2346,154 +2346,6 @@ class TestPresetSkills:
|
||||
metadata = manager.registry.get("self-test")
|
||||
assert "speckit-specify" in metadata.get("registered_skills", [])
|
||||
|
||||
def test_register_skills_resolves_command_refs(self, project_dir, temp_dir):
|
||||
"""Preset skill overrides must resolve __SPECKIT_COMMAND_*__ tokens (issue #2717).
|
||||
|
||||
``_register_skills()`` previously ran only ``resolve_skill_placeholders()``,
|
||||
so command cross-references leaked into SKILL.md as raw placeholders
|
||||
instead of rendering as ``/speckit-<cmd>`` like the command layer.
|
||||
"""
|
||||
self._write_init_options(project_dir, ai="claude")
|
||||
skills_dir = project_dir / ".claude" / "skills"
|
||||
self._create_skill(skills_dir, "speckit-specify")
|
||||
|
||||
preset_dir = self._create_command_preset(
|
||||
temp_dir,
|
||||
"cmdref-install",
|
||||
"speckit.specify",
|
||||
"Override specify",
|
||||
"Run `__SPECKIT_COMMAND_SPECIFY__` then `__SPECKIT_COMMAND_PLAN__`.\n",
|
||||
)
|
||||
|
||||
manager = PresetManager(project_dir)
|
||||
manager.install_from_directory(preset_dir, "0.1.5")
|
||||
|
||||
content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
|
||||
assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked into SKILL.md"
|
||||
# Claude's invoke_separator is "-", so tokens render as /speckit-<cmd>.
|
||||
assert "/speckit-specify" in content
|
||||
assert "/speckit-plan" in content
|
||||
|
||||
def test_restore_skill_resolves_command_refs(self, project_dir, temp_dir):
|
||||
"""Skill restore on preset removal must also resolve command tokens (issue #2717)."""
|
||||
self._write_init_options(project_dir, ai="claude")
|
||||
skills_dir = project_dir / ".claude" / "skills"
|
||||
self._create_skill(skills_dir, "speckit-specify")
|
||||
|
||||
core_cmds = project_dir / ".specify" / "templates" / "commands"
|
||||
core_cmds.mkdir(parents=True, exist_ok=True)
|
||||
(core_cmds / "specify.md").write_text(
|
||||
"---\ndescription: Core specify\n---\n\n"
|
||||
"Then run `__SPECKIT_COMMAND_PLAN__`.\n"
|
||||
)
|
||||
|
||||
preset_dir = self._create_command_preset(
|
||||
temp_dir,
|
||||
"cmdref-restore",
|
||||
"speckit.specify",
|
||||
"Override specify",
|
||||
"Override body\n",
|
||||
)
|
||||
manager = PresetManager(project_dir)
|
||||
manager.install_from_directory(preset_dir, "0.1.5")
|
||||
manager.remove("cmdref-restore")
|
||||
|
||||
content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
|
||||
assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on restore"
|
||||
assert "/speckit-plan" in content
|
||||
|
||||
def test_reconcile_override_skill_resolves_command_refs(self, project_dir, temp_dir):
|
||||
"""Reconcile's project-override restore must resolve command tokens (issue #2717).
|
||||
|
||||
When a preset that overrode a command is removed and a project override
|
||||
becomes the winning layer, ``_reconcile_skills`` rewrites the skill from
|
||||
the override body — which must also render ``__SPECKIT_COMMAND_*__`` tokens.
|
||||
"""
|
||||
self._write_init_options(project_dir, ai="claude")
|
||||
skills_dir = project_dir / ".claude" / "skills"
|
||||
self._create_skill(skills_dir, "speckit-specify")
|
||||
|
||||
# Project override wins once the preset is removed; its body carries a
|
||||
# command cross-reference token. No core template exists for "specify",
|
||||
# so the skill is restored exclusively via the reconcile override branch.
|
||||
overrides_dir = project_dir / ".specify" / "templates" / "overrides"
|
||||
overrides_dir.mkdir(parents=True, exist_ok=True)
|
||||
(overrides_dir / "speckit.specify.md").write_text(
|
||||
"---\ndescription: Override specify\n---\n\n"
|
||||
"Then run `__SPECKIT_COMMAND_PLAN__`.\n"
|
||||
)
|
||||
|
||||
preset_dir = self._create_command_preset(
|
||||
temp_dir,
|
||||
"cmdref-reconcile",
|
||||
"speckit.specify",
|
||||
"Preset specify",
|
||||
"Preset body\n",
|
||||
)
|
||||
manager = PresetManager(project_dir)
|
||||
manager.install_from_directory(preset_dir, "0.1.5")
|
||||
manager.remove("cmdref-reconcile")
|
||||
|
||||
content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
|
||||
assert "override:speckit.specify" in content, "skill should be restored from the project override"
|
||||
assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on reconcile"
|
||||
assert "/speckit-plan" in content
|
||||
|
||||
def test_extension_restore_resolves_command_refs(self, project_dir, temp_dir):
|
||||
"""Extension-backed skill restore must resolve command tokens (issue #2717).
|
||||
|
||||
When a preset override is removed and the skill is restored from an
|
||||
extension command body, ``__SPECKIT_COMMAND_*__`` tokens in that body
|
||||
must render as slash-command invocations like the core-template path.
|
||||
"""
|
||||
self._write_init_options(project_dir, ai="claude")
|
||||
skills_dir = project_dir / ".claude" / "skills"
|
||||
self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")
|
||||
|
||||
extension_dir = project_dir / ".specify" / "extensions" / "fakeext"
|
||||
(extension_dir / "commands").mkdir(parents=True, exist_ok=True)
|
||||
(extension_dir / "commands" / "cmd.md").write_text(
|
||||
"---\ndescription: Extension fakeext cmd\n---\n\n"
|
||||
"Then run `__SPECKIT_COMMAND_PLAN__`.\n"
|
||||
)
|
||||
extension_manifest = {
|
||||
"schema_version": "1.0",
|
||||
"extension": {
|
||||
"id": "fakeext",
|
||||
"name": "Fake Extension",
|
||||
"version": "1.0.0",
|
||||
"description": "Test",
|
||||
},
|
||||
"requires": {"speckit_version": ">=0.1.0"},
|
||||
"provides": {
|
||||
"commands": [
|
||||
{
|
||||
"name": "speckit.fakeext.cmd",
|
||||
"file": "commands/cmd.md",
|
||||
"description": "Fake extension command",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
with open(extension_dir / "extension.yml", "w") as f:
|
||||
yaml.dump(extension_manifest, f)
|
||||
|
||||
preset_dir = self._create_command_preset(
|
||||
temp_dir,
|
||||
"cmdref-ext-restore",
|
||||
"speckit.fakeext.cmd",
|
||||
"Override fakeext cmd",
|
||||
"Override body\n",
|
||||
)
|
||||
manager = PresetManager(project_dir)
|
||||
manager.install_from_directory(preset_dir, "0.1.5")
|
||||
manager.remove("cmdref-ext-restore")
|
||||
|
||||
content = (skills_dir / "speckit-fakeext-cmd" / "SKILL.md").read_text()
|
||||
assert "source: extension:fakeext" in content, "skill should be restored from the extension"
|
||||
assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on extension restore"
|
||||
assert "/speckit-plan" in content
|
||||
|
||||
def test_core_command_override_skill_uses_preset_command_description(self, project_dir, temp_dir):
|
||||
"""Preset skill overrides for core commands should keep preset frontmatter descriptions."""
|
||||
self._write_init_options(project_dir, ai="claude")
|
||||
|
||||
@@ -1,216 +0,0 @@
|
||||
"""Tests for setup-plan preserving existing plan.md (#2653)."""
|
||||
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.conftest import requires_bash
|
||||
|
||||
PROJECT_ROOT = Path(__file__).resolve().parent.parent
|
||||
COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
|
||||
SETUP_PLAN_SH = PROJECT_ROOT / "scripts" / "bash" / "setup-plan.sh"
|
||||
COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
|
||||
SETUP_PLAN_PS = PROJECT_ROOT / "scripts" / "powershell" / "setup-plan.ps1"
|
||||
PLAN_TEMPLATE = PROJECT_ROOT / "templates" / "plan-template.md"
|
||||
|
||||
HAS_PWSH = shutil.which("pwsh") is not None
|
||||
_POWERSHELL = shutil.which("powershell.exe") or shutil.which("powershell")
|
||||
|
||||
|
||||
def _install_bash_scripts(repo: Path) -> None:
|
||||
d = repo / ".specify" / "scripts" / "bash"
|
||||
d.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy(COMMON_SH, d / "common.sh")
|
||||
shutil.copy(SETUP_PLAN_SH, d / "setup-plan.sh")
|
||||
|
||||
|
||||
def _install_ps_scripts(repo: Path) -> None:
|
||||
d = repo / ".specify" / "scripts" / "powershell"
|
||||
d.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy(COMMON_PS, d / "common.ps1")
|
||||
shutil.copy(SETUP_PLAN_PS, d / "setup-plan.ps1")
|
||||
|
||||
|
||||
def _minimal_templates(repo: Path) -> None:
|
||||
tdir = repo / ".specify" / "templates"
|
||||
tdir.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy(PLAN_TEMPLATE, tdir / "plan-template.md")
|
||||
|
||||
|
||||
def _clean_env() -> dict[str, str]:
|
||||
env = os.environ.copy()
|
||||
for key in list(env):
|
||||
if key.startswith("SPECIFY_"):
|
||||
env.pop(key)
|
||||
return env
|
||||
|
||||
|
||||
def _git_init(repo: Path) -> None:
|
||||
subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
|
||||
subprocess.run(
|
||||
["git", "config", "user.email", "test@example.com"], cwd=repo, check=True
|
||||
)
|
||||
subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)
|
||||
subprocess.run(
|
||||
["git", "commit", "--allow-empty", "-m", "init", "-q"], cwd=repo, check=True
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def plan_repo(tmp_path: Path) -> Path:
|
||||
repo = tmp_path / "proj"
|
||||
repo.mkdir()
|
||||
_git_init(repo)
|
||||
subprocess.run(
|
||||
["git", "checkout", "-q", "-b", "001-my-feature"],
|
||||
cwd=repo,
|
||||
check=True,
|
||||
)
|
||||
(repo / ".specify").mkdir()
|
||||
_minimal_templates(repo)
|
||||
_install_bash_scripts(repo)
|
||||
_install_ps_scripts(repo)
|
||||
return repo
|
||||
|
||||
|
||||
# ── Bash tests ────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_setup_plan_creates_plan_when_missing(plan_repo: Path) -> None:
|
||||
"""First run must create plan.md from the template."""
|
||||
script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json"],
|
||||
cwd=plan_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
plan_path = Path(data["IMPL_PLAN"])
|
||||
assert plan_path.is_file()
|
||||
# Template content should be present
|
||||
content = plan_path.read_text(encoding="utf-8")
|
||||
assert len(content) > 0
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_setup_plan_preserves_existing_plan(plan_repo: Path) -> None:
|
||||
"""Rerun must not overwrite an existing plan.md."""
|
||||
feat = plan_repo / "specs" / "001-my-feature"
|
||||
feat.mkdir(parents=True)
|
||||
existing_content = "# My carefully authored plan\n\nDo not overwrite me.\n"
|
||||
(feat / "plan.md").write_text(existing_content, encoding="utf-8")
|
||||
|
||||
script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json"],
|
||||
cwd=plan_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
# Plan must be unchanged
|
||||
assert (feat / "plan.md").read_text(encoding="utf-8") == existing_content
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_setup_plan_skip_message_on_stderr_in_json_mode(plan_repo: Path) -> None:
|
||||
"""In --json mode, status messages must go to stderr, not stdout."""
|
||||
feat = plan_repo / "specs" / "001-my-feature"
|
||||
feat.mkdir(parents=True)
|
||||
(feat / "plan.md").write_text("# existing\n", encoding="utf-8")
|
||||
|
||||
script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json"],
|
||||
cwd=plan_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
# stdout must be valid JSON (no status messages mixed in)
|
||||
data = json.loads(result.stdout)
|
||||
assert "IMPL_PLAN" in data
|
||||
# The skip message should be on stderr
|
||||
assert "already exists" in result.stderr
|
||||
|
||||
|
||||
@requires_bash
|
||||
def test_setup_plan_json_parseable_on_first_run(plan_repo: Path) -> None:
|
||||
"""In --json mode, first-run stdout must be parseable JSON (no status on stdout)."""
|
||||
script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
|
||||
result = subprocess.run(
|
||||
["bash", str(script), "--json"],
|
||||
cwd=plan_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
assert "IMPL_PLAN" in data
|
||||
assert "Copied plan template" in result.stderr
|
||||
|
||||
|
||||
# ── PowerShell tests ──────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
|
||||
def test_ps_setup_plan_creates_plan_when_missing(plan_repo: Path) -> None:
|
||||
"""First run must create plan.md from the template."""
|
||||
script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
|
||||
exe = "pwsh" if HAS_PWSH else _POWERSHELL
|
||||
result = subprocess.run(
|
||||
[exe, "-NoProfile", "-File", str(script), "-Json"],
|
||||
cwd=plan_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
data = json.loads(result.stdout)
|
||||
plan_path = Path(data["IMPL_PLAN"])
|
||||
assert plan_path.is_file()
|
||||
content = plan_path.read_text(encoding="utf-8")
|
||||
assert len(content) > 0
|
||||
|
||||
|
||||
@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
|
||||
def test_ps_setup_plan_preserves_existing_plan(plan_repo: Path) -> None:
|
||||
"""Rerun must not overwrite an existing plan.md."""
|
||||
feat = plan_repo / "specs" / "001-my-feature"
|
||||
feat.mkdir(parents=True)
|
||||
existing_content = "# My carefully authored plan\n\nDo not overwrite me.\n"
|
||||
(feat / "plan.md").write_text(existing_content, encoding="utf-8")
|
||||
|
||||
script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
|
||||
exe = "pwsh" if HAS_PWSH else _POWERSHELL
|
||||
result = subprocess.run(
|
||||
[exe, "-NoProfile", "-File", str(script), "-Json"],
|
||||
cwd=plan_repo,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
env=_clean_env(),
|
||||
)
|
||||
assert result.returncode == 0, result.stderr
|
||||
assert (feat / "plan.md").read_text(encoding="utf-8") == existing_content
|
||||
# stdout must be valid JSON (no status messages mixed in)
|
||||
data = json.loads(result.stdout)
|
||||
assert "IMPL_PLAN" in data
|
||||
# The skip message should be on stderr
|
||||
assert "already exists" in result.stderr
|
||||
@@ -333,44 +333,6 @@ class TestExpressions:
|
||||
result = evaluate_expression("{{ steps.tasks.output.task_list[0].file }}", ctx)
|
||||
assert result == "a.md"
|
||||
|
||||
def test_context_run_id_resolves(self):
|
||||
"""``{{ context.run_id }}`` resolves to ``StepContext.run_id``.
|
||||
|
||||
Locks the contract from issue #2590: workflow templates can
|
||||
reference the engine-assigned run id for telemetry, artifact
|
||||
metadata, or per-run scratch isolation.
|
||||
"""
|
||||
from specify_cli.workflows.expressions import evaluate_expression
|
||||
from specify_cli.workflows.base import StepContext
|
||||
|
||||
ctx = StepContext(run_id="a1b2c3d4")
|
||||
assert evaluate_expression("{{ context.run_id }}", ctx) == "a1b2c3d4"
|
||||
|
||||
def test_context_run_id_defaults_to_empty_when_unset(self):
|
||||
"""``{{ context.run_id }}`` resolves to ``""`` when no run is
|
||||
active (dry-run, validation, ad-hoc evaluator usage) rather
|
||||
than raising — workflows referencing the variable never error
|
||||
outside a run context.
|
||||
"""
|
||||
from specify_cli.workflows.expressions import evaluate_expression
|
||||
from specify_cli.workflows.base import StepContext
|
||||
|
||||
# No run_id set on the context.
|
||||
ctx = StepContext()
|
||||
assert evaluate_expression("{{ context.run_id }}", ctx) == ""
|
||||
|
||||
def test_context_run_id_string_interpolation(self):
|
||||
"""Run id interpolates inside a larger template string — the
|
||||
common pattern for stamping shell commands and artifact paths
|
||||
with the run id.
|
||||
"""
|
||||
from specify_cli.workflows.expressions import evaluate_expression
|
||||
from specify_cli.workflows.base import StepContext
|
||||
|
||||
ctx = StepContext(run_id="deadbeef")
|
||||
result = evaluate_expression("RUN_ID={{ context.run_id }}", ctx)
|
||||
assert result == "RUN_ID=deadbeef"
|
||||
|
||||
|
||||
# ===== Integration Dispatch Tests =====
|
||||
|
||||
@@ -2192,147 +2154,6 @@ steps:
|
||||
assert "retry-loop:step-b:2" in state.step_results
|
||||
|
||||
|
||||
# ===== context.run_id Tests =====
|
||||
#
|
||||
# End-to-end coverage for the `{{ context.run_id }}` template
|
||||
# variable introduced in issue #2590. Locks resolution inside the
|
||||
# three step types the acceptance criteria called out — shell `run:`,
|
||||
# command `input.args:`, and switch `expression:` — plus the
|
||||
# "workflow doesn't reference it" backward-compat path.
|
||||
|
||||
|
||||
class TestContextRunId:
|
||||
"""End-to-end tests for `{{ context.run_id }}` in workflow YAML."""
|
||||
|
||||
def test_shell_run_resolves_run_id(self, project_dir):
|
||||
"""`run: "echo {{ context.run_id }}"` substitutes the
|
||||
engine-assigned run id into the spawned shell, and the
|
||||
same value appears on `state.run_id`.
|
||||
"""
|
||||
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
|
||||
|
||||
definition = WorkflowDefinition.from_string("""
|
||||
schema_version: "1.0"
|
||||
workflow:
|
||||
id: "stamp-run-id"
|
||||
name: "Stamp Run Id"
|
||||
version: "1.0.0"
|
||||
steps:
|
||||
- id: stamp
|
||||
type: shell
|
||||
run: "echo RUN_ID={{ context.run_id }}"
|
||||
""")
|
||||
engine = WorkflowEngine(project_dir)
|
||||
state = engine.execute(definition, run_id="abc12345")
|
||||
|
||||
assert state.run_id == "abc12345"
|
||||
stdout = state.step_results["stamp"]["output"]["stdout"]
|
||||
assert stdout.strip() == "RUN_ID=abc12345"
|
||||
|
||||
def test_command_input_args_resolves_run_id(self, project_dir):
|
||||
"""`input.args: "{{ context.run_id }}"` is resolved by
|
||||
`CommandStep` and recorded in step output, even when CLI
|
||||
dispatch is unavailable (no integration installed). Covers
|
||||
the artifact-metadata use case from the issue.
|
||||
"""
|
||||
from unittest.mock import patch
|
||||
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
|
||||
|
||||
definition = WorkflowDefinition.from_string("""
|
||||
schema_version: "1.0"
|
||||
workflow:
|
||||
id: "command-stamp"
|
||||
name: "Command Stamp"
|
||||
version: "1.0.0"
|
||||
integration: claude
|
||||
steps:
|
||||
- id: tag-artifact
|
||||
command: speckit.specify
|
||||
input:
|
||||
args: "{{ context.run_id }}"
|
||||
""")
|
||||
engine = WorkflowEngine(project_dir)
|
||||
with patch(
|
||||
"specify_cli.workflows.steps.command.shutil.which",
|
||||
return_value=None,
|
||||
):
|
||||
state = engine.execute(definition, run_id="cafef00d")
|
||||
|
||||
# Even when dispatch fails (no CLI), the resolved input is
|
||||
# recorded so downstream observers see the run id in artifact
|
||||
# metadata.
|
||||
assert state.step_results["tag-artifact"]["output"]["input"]["args"] == "cafef00d"
|
||||
|
||||
def test_switch_expression_matches_on_run_id(self, project_dir):
|
||||
"""`switch` over `{{ context.run_id }}` matches against case
|
||||
keys, and the nested branch can ALSO reference
|
||||
`{{ context.run_id }}`. Demonstrates the run id is a
|
||||
first-class value in the expression engine (not just a
|
||||
string-interpolation token) AND that it propagates into
|
||||
nested step execution via the recursive `_execute_steps`
|
||||
traversal.
|
||||
"""
|
||||
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
|
||||
from specify_cli.workflows.base import RunStatus
|
||||
|
||||
definition = WorkflowDefinition.from_string("""
|
||||
schema_version: "1.0"
|
||||
workflow:
|
||||
id: "switch-on-run-id"
|
||||
name: "Switch On Run Id"
|
||||
version: "1.0.0"
|
||||
steps:
|
||||
- id: route
|
||||
type: switch
|
||||
expression: "{{ context.run_id }}"
|
||||
cases:
|
||||
target-run:
|
||||
- id: matched-branch
|
||||
type: shell
|
||||
run: "echo nested-run-id={{ context.run_id }}"
|
||||
default:
|
||||
- id: default-branch
|
||||
type: shell
|
||||
run: "echo defaulted"
|
||||
""")
|
||||
engine = WorkflowEngine(project_dir)
|
||||
state = engine.execute(definition, run_id="target-run")
|
||||
|
||||
assert state.status == RunStatus.COMPLETED
|
||||
assert state.step_results["route"]["output"]["matched_case"] == "target-run"
|
||||
assert "matched-branch" in state.step_results
|
||||
assert "default-branch" not in state.step_results
|
||||
# The nested branch sees the same run id — propagation through
|
||||
# recursive `_execute_steps` is intact.
|
||||
nested_stdout = state.step_results["matched-branch"]["output"]["stdout"]
|
||||
assert nested_stdout.strip() == "nested-run-id=target-run"
|
||||
|
||||
def test_workflow_without_context_reference_unchanged(self, project_dir):
|
||||
"""Workflows that do not reference `{{ context.run_id }}`
|
||||
continue to run exactly as before. Locks the byte-equivalent
|
||||
default required by the issue's acceptance criteria.
|
||||
"""
|
||||
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
|
||||
from specify_cli.workflows.base import RunStatus
|
||||
|
||||
definition = WorkflowDefinition.from_string("""
|
||||
schema_version: "1.0"
|
||||
workflow:
|
||||
id: "no-context-ref"
|
||||
name: "No Context Ref"
|
||||
version: "1.0.0"
|
||||
steps:
|
||||
- id: only-step
|
||||
type: shell
|
||||
run: "echo hello"
|
||||
""")
|
||||
engine = WorkflowEngine(project_dir)
|
||||
state = engine.execute(definition)
|
||||
|
||||
assert state.status == RunStatus.COMPLETED
|
||||
assert state.step_results["only-step"]["output"]["stdout"].strip() == "hello"
|
||||
|
||||
|
||||
# ===== State Persistence Tests =====
|
||||
|
||||
class TestRunState:
|
||||
|
||||
@@ -239,33 +239,6 @@ message: "{{ status | default('pending') }}"
|
||||
|
||||
Supported filters: `default`, `join`, `contains`, `map`.
|
||||
|
||||
### Runtime Context
|
||||
|
||||
`{{ context.* }}` exposes engine-managed runtime metadata for the
|
||||
current run:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `context.run_id` | The current workflow run id (the same value Spec Kit prints as `Run ID:` at the end of `workflow run`). Auto-generated runs are 8-character hex from `uuid4`; operator-supplied ids may be any alphanumeric string with hyphens or underscores. Empty string outside a run context. |
|
||||
|
||||
```yaml
|
||||
# Stamp telemetry events with the run id for cross-system join.
|
||||
- id: emit-event
|
||||
type: shell
|
||||
run: 'echo "{\"run_id\":\"{{ context.run_id }}\",\"event\":\"started\"}" >> events.jsonl'
|
||||
|
||||
# Per-run scratch directory.
|
||||
- id: prep-scratch
|
||||
type: shell
|
||||
run: 'mkdir -p /tmp/run-{{ context.run_id }}'
|
||||
|
||||
# Pass run id into a command for artifact metadata.
|
||||
- id: tag-artifact
|
||||
command: speckit.specify
|
||||
input:
|
||||
args: "{{ context.run_id }}"
|
||||
```
|
||||
|
||||
## Input Types
|
||||
|
||||
Workflow inputs are type-checked and coerced from CLI string values:
|
||||
|
||||
Reference in New Issue
Block a user