github · yuanyuanyuan · Oct 9, 2025 · Oct 9, 2025 · Oct 9, 2025
@@ -34,7 +34,9 @@ rewrite_paths() {
   sed -E \
     -e 's@(/?)memory/@.specify/memory/@g' \
     -e 's@(/?)scripts/@.specify/scripts/@g' \
-    -e 's@(/?)templates/@.specify/templates/@g'
+    -e 's@(/?)templates/@.specify/templates/@g' \
+    -e 's@\.specify/\.specify/@.specify/@g' \
+    -e 's@\.specify\.specify/@.specify/@g'
 }
 
 generate_commands() {

@@ -0,0 +1,103 @@
+name: UI Blueprint Smoke Tests
+
+on:
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  smoke:
+    name: Smoke on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install jq (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y jq
+
+      - name: Install shellcheck (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get install -y shellcheck
+
+      - name: Build packages
+        shell: bash
+        run: |
+          chmod +x .github/workflows/scripts/create-release-packages.sh
+          .github/workflows/scripts/create-release-packages.sh v0.0.99
+
+      - name: Lint bash scripts (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          shellcheck -x scripts/bash/*.sh .github/workflows/scripts/*.sh || true
+
+      - name: Lint PowerShell scripts (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          Set-PSRepository -Name 'PSGallery' -InstallationPolicy Trusted
+          Install-Module PSScriptAnalyzer -Force
+          Invoke-ScriptAnalyzer -Path scripts/powershell -Recurse -Severity Warning || $true
+
+      - name: Validate JSON templates (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          jq -e . templates/ui/tokens.json >/dev/null
+          jq -e . templates/ui/types.schema.json >/dev/null
+
+      - name: Verify no double .specify prefix (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          unzip -p .genreleases/spec-kit-template-claude-sh-v0.0.99.zip .claude/commands/speckit.ui.md |\
+            grep -qv '\.specify\.specify/'
+
+      - name: Smoke test packaged project (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          mkdir -p /tmp/ui-smoke && cd /tmp/ui-smoke
+          unzip -q $GITHUB_WORKSPACE/.genreleases/spec-kit-template-claude-sh-v0.0.99.zip -d ./pkg
+          cd pkg
+          # Create feature directory via the provided script
+          .specify/scripts/bash/create-new-feature.sh --json 'UI smoke' | tee /tmp/feat.json
+          BRANCH=$(jq -r .BRANCH_NAME /tmp/feat.json)
+          # Run UI setup and validate JSON keys
+          .specify/scripts/bash/setup-ui.sh | tee /tmp/ui.json
+          for key in UI_DIR TOKENS_FILE COMPONENTS_SPEC FLOWS_FILE HTML_SKELETON BDD_FILE README_FILE; do
+            jq -e ".${key}" /tmp/ui.json >/dev/null || (echo "Missing JSON key: $key" && exit 1)
+          done
+          # Ensure files exist and are non-empty
+          for key in TOKENS_FILE COMPONENTS_SPEC FLOWS_FILE HTML_SKELETON BDD_FILE README_FILE; do
+            f=$(jq -r ".${key}" /tmp/ui.json); test -s "$f" || (echo "Empty file: $f" && exit 1)
+          done
+
+      - name: Smoke test packaged project (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $zip = Join-Path $env:GITHUB_WORKSPACE '.genreleases/spec-kit-template-claude-ps-v0.0.99.zip'
+          $dest = Join-Path $env:RUNNER_TEMP 'pkg'
+          New-Item -ItemType Directory -Force -Path $dest | Out-Null
+          Add-Type -AssemblyName System.IO.Compression.FileSystem
+          [System.IO.Compression.ZipFile]::ExtractToDirectory($zip, $dest)
+          Set-Location $dest
+          .\.specify\scripts\powershell\create-new-feature.ps1 -Json 'UI smoke' | Out-File -Encoding utf8 -FilePath $env:RUNNER_TEMP\feat.json
+          .\.specify\scripts\powershell\setup-ui.ps1 | Out-File -Encoding utf8 -FilePath $env:RUNNER_TEMP\ui.json
+          $json = Get-Content $env:RUNNER_TEMP\ui.json | ConvertFrom-Json
+          foreach ($k in 'UI_DIR','TOKENS_FILE','COMPONENTS_SPEC','FLOWS_FILE','HTML_SKELETON','BDD_FILE','README_FILE') {
+            if (-not $json.$k) { throw "Missing JSON key: $k" }
+          }
+          foreach ($k in 'TOKENS_FILE','COMPONENTS_SPEC','FLOWS_FILE','HTML_SKELETON','BDD_FILE','README_FILE') {
+            $p = $json.$k
+            if (-not (Test-Path $p -PathType Leaf)) { throw "Missing file: $p" }
+            if ((Get-Item $p).Length -le 0) { throw "Empty file: $p" }
+          }
@@ -0,0 +1,162 @@
+# Spec Kit PR Guidelines (Working Playbook)
+
+This guide distills practical rules and checklists from recent PR work to help contributors ship changes that are spec‑first, technology‑neutral, reproducible, and easy to review. It consolidates prior notes from both English and Chinese guides into one canonical document.
+
+## Before You Start: Why + Definition of Done
+
+- State the Why in one sentence (bug, compatibility, maintainability, UX, perf, compliance, etc.).
+- Define verifiable acceptance criteria (e.g., all agent×script packages build; docs compile; CLI examples run on Windows and Linux).
+- Break work down into small tasks (e.g., update CLI help → update README → patch packaging script → local verify).
+
+## Purpose
+
+- Strengthen Spec‑Driven Development (SDD) by turning ideas into structured, machine‑readable specs.
+- Keep changes agent‑agnostic and framework‑agnostic.
+- Prevent silent failures; make success/failure observable and reproducible.
+
+## Core Principles
+
+- Spec‑First: Prefer structured artifacts (tokens, component APIs, flows, HTML skeletons, BDD, data contracts) over prose.
+- Technology‑Neutral: Default to semantic HTML + ARIA and JSON Schema; avoid binding to specific frameworks.
+- Reproducible Paths: Always use absolute file paths emitted by scripts; never guess or hard‑code template locations in commands.
+- Fail‑Fast: If prerequisites/templates are missing, exit with a clear error (no silent empty files).
+- Idempotent Packaging: Path rewriting must not produce double prefixes (e.g., `.specify.specify/`).
+- Minimal Scope: Keep each PR focused; only touch files relevant to the change.
+
+## Agent Integration and CLI Core Changes
+
+- If you modify `src/specify_cli/__init__.py`:
+  - Bump the version in `pyproject.toml` and add a `CHANGELOG.md` entry (per AGENTS.md).
+- Adding or changing agent support:
+  - Update `AI_CHOICES` and help text in `src/specify_cli/__init__.py`.
+  - Update Supported Agents table in `README.md`.
+  - Update `.github/workflows/scripts/create-release-packages.sh` (ALL_AGENTS, directory cases, placeholder replacements).
+  - If release artifacts change, update `.github/workflows/scripts/create-github-release.sh` accordingly.
+  - Keep agent context updaters in sync: `scripts/bash/update-agent-context.sh` and `scripts/powershell/update-agent-context.ps1`.
+
+## Branching & Environment
+
+- Use feature branches like `001-some-feature`.
+- For non‑Git environments, set `SPECIFY_FEATURE` to select the feature folder.
+- Common helpers already warn but allow non‑Git flows; prefer branches when possible.
+
+## Files, Paths, and Scripts
+
+- Command templates (e.g., `/speckit.*`):
+  - Rely only on JSON keys printed by setup scripts (e.g., `README_FILE`, `TOKENS_FILE`, `COMPONENTS_SPEC`, `FLOWS_FILE`, `HTML_SKELETON`, `BDD_FILE`, `TYPES_SCHEMA`/`TYPES_TS`).
+  - Do not infer or reconstruct paths inside command text.
+- Setup scripts (Bash + PowerShell):
+  - Resolve template root from `.specify/templates/<area>` (packaged projects) or `templates/<area>` (repo checkout).
+  - Emit absolute paths via JSON once and reuse them.
+  - Fail if any required template is missing; include actionable guidance in errors.
+- Do not commit generated artifacts under `specs/` in PRs unless explicitly requested.
+
+### Cross‑Agent Conventions (placeholders)
+
+- Directory layout by agent: `.claude/commands/`, `.gemini/commands/`, `.cursor/commands/`, `.windsurf/workflows/`, `.github/prompts/` (Copilot), etc.
+- Argument placeholders by format:
+  - Markdown/Prompt: `$ARGUMENTS`
+  - TOML: `{{args}}`
+  - Script path placeholder: `{SCRIPT}`
+  - Agent name placeholder: `__AGENT__`
+
+## Packaging & Release
+
+- Packager script: `.github/workflows/scripts/create-release-packages.sh`
+  - Rewrites `memory/`, `scripts/`, and `templates/` into `.specify/*`.
+  - Include an idempotency guard to collapse accidental double prefixes (e.g., `.specify/.specify/`).
+- Do not modify CLI core (`src/specify_cli/__init__.py`) unless necessary. If you do:
+  - Bump version in `pyproject.toml` and add a `CHANGELOG.md` entry (per AGENTS.md).
+
+### Workflow Triggers
+
+- Release workflow (`.github/workflows/release.yml`) is triggered on changes under `memory/**`, `scripts/**`, `templates/**`, and `.github/workflows/**`.
+- Docs workflow (`.github/workflows/docs.yml`) builds and publishes docs when `docs/**` changes.
+
+### Docs Build (DocFX)
+
+- Docs use DocFX. If you modify DocFX config/structure, verify locally before pushing (requires .NET + DocFX).
+
+## CI Smoke Tests
+
+- Add/update a workflow that:
+  - Builds packages for supported agents and script variants (sh/ps).
+  - Verifies no `.specify.specify/` strings in packaged commands.
+  - Runs `create-new-feature` and your setup script; validates JSON keys exist; asserts files are non‑empty.
+  - Validates JSON with `jq` (Linux). Add light static analysis (`shellcheck`, `PSScriptAnalyzer`)—warnings may be non‑blocking initially.
+
+## Documentation & Help Text
+
+- README: Add commands and minimal usage notes (branch vs `SPECIFY_FEATURE`, “use JSON keys only”, and default to JSON Schema).
+- Template README: Document conventions (tokens‑only styling, accessibility, neutrality, path usage via JSON keys).
+- Keep examples concise and technology‑neutral; add framework mapping notes as comments when helpful.
+
+## Local Verification (quick references)
+
+- Using uv (no global install required):
+  - `uv sync`
+  - `uv run specify --help`
+  - `uv run specify check`
+  - Example: `uv run specify init demo --ai claude --script sh --ignore-agent-tools`
+- Global Specify (optional):
+  - `specify --help`
+  - `specify check`
+- Packaging dry‑run:
+  - `bash .github/workflows/scripts/create-release-packages.sh v0.0.0`
+
+## Data Contracts
+
+- Prefer JSON Schema (`types.schema.json`) for neutrality.
+- TypeScript interfaces (`types.ts`) are optional developer aids.
+- Ensure contracts align with events/results implied by flows and components.
+
+## Accessibility & Tokens
+
+- Put all visual primitives in `tokens.json` (colors, spacing, radius, shadows, typography; optional: breakpoints, zIndex, opacity, motion).
+- Encourage rem‑based sizing guidance in docs (e.g., 16px body → 1rem).
+- Preserve roles/labels/`aria-live`; plan focus management.
+
+## AI Disclosure
+
+- Include a short note in PRs if AI assisted drafting or code generation, and confirm manual review/verification.
+
+## Review Checklist
+
+- [ ] Command uses only script JSON keys (no hard‑coded paths).
+- [ ] Scripts resolve both packaged and repo roots; missing templates fail with guidance.
+- [ ] No silent file creation; all artifacts are real and non‑empty.
+- [ ] Packaging contains `.specify/templates/<area>/*` and no `.specify.specify/`.
+- [ ] Tokens‑only styling outside of `tokens.json` (no raw hex/px in other files).
+- [ ] Components referenced in `skeleton.html` exist in `components.md`.
+- [ ] Flows and BDD align on state names and transitions.
+- [ ] Data contracts present; JSON Schema preferred.
+- [ ] README/Template docs updated; include branch/SPECIFY_FEATURE guidance.
+- [ ] CI smoke tests pass on Ubuntu + Windows.
+- [ ] If CLI core changed: version bump + changelog entry present.
+
+## Quick Commands (examples)
+
+- Local (no init):
+  ```bash
+  export SPECIFY_FEATURE=001-ui-feature
+  bash scripts/bash/setup-ui.sh | tee /tmp/ui.json
+  jq -r '.README_FILE,.TOKENS_FILE,.COMPONENTS_SPEC,.FLOWS_FILE,.HTML_SKELETON,.BDD_FILE,.TYPES_SCHEMA,.TYPES_TS' /tmp/ui.json
+  ```
+- Packaged (Linux):
+  ```bash
+  bash .github/workflows/scripts/create-release-packages.sh vX.Y.Z
+  unzip -q .genreleases/spec-kit-template-claude-sh-vX.Y.Z.zip -d /tmp/p
+  cd /tmp/p
+  .specify/scripts/bash/create-new-feature.sh --json 'UI smoke'
+  .specify/scripts/bash/setup-ui.sh | jq .
+  ```
+
+## Anti‑Patterns
+
+- Hard‑coding template paths in commands.
+- Creating empty placeholder files on failure.
+- Binding artifacts to a specific UI framework by default.
+- Mixing unrelated changes (workflows, docs, and features) without clear rationale.
+
+---
+Keep this guide updated as the process evolves.
@@ -0,0 +1,82 @@
+feat(templates): add /speckit.ui blueprint, fail-fast scripts, JSON Schema, and smoke CI
+
+摘要
+
+新增可选命令 /speckit.ui 及配套模板与脚本，生成框架无关的 UI 蓝图（设计令牌、组件 API、状态机、语义 HTML 骨架、BDD、数据契约）；修复打包路径幂等（避免 .specify.specify），新增跨平台烟测工作流，杜绝“静默空文件”。
+
+背景/动机
+
+- 现状与痛点：
+  - UI/UX 仅靠自然语言，机器理解空间大，易在样式/结构/交互与数据契约上产生偏差。
+  - 打包时路径替换过度可能出现 .specify.specify/。
+  - 模板缺失时旧脚本会“touch 空文件”，属于“静默降级”，与仓库质量基调不符。
+- 目标与原则（规格先行、技术中立、可复制验证）：
+  - 用 Tokens/组件表/流程图/HTML 骨架/BDD/数据契约把 UI 决策工程化。
+  - 不绑定具体框架（HTML + ARIA，注明如何映射到各框架）。
+  - 打包后命令/模板即插即用，CI 端到端“体检+冒烟”验证。
+
+变更内容
+
+- 代码/脚本
+  - scripts/bash/setup-ui.sh：双路径探测（.specify/templates/ui 与 templates/ui）、缺失即 fail-fast、输出 JSON 键：UI_DIR、TOKENS_FILE、COMPONENTS_SPEC、FLOWS_FILE、HTML_SKELETON、BDD_FILE、TYPES_SCHEMA、TYPES_TS、README_FILE
+  - scripts/powershell/setup-ui.ps1：同上
+  - .github/workflows/scripts/create-release-packages.sh：rewrite_paths 增加幂等折叠，避免 .specify.specify/
+- 命令模板
+  - templates/commands/ui.md：改为只使用脚本 JSON 键，不再硬编码路径；数据契约默认优先 JSON Schema（types.schema.json），TS 接口可选
+- 模板
+  - templates/ui/README.md（约定与路径使用）、templates/ui/tokens.json（扩展 breakpoints/zIndex/opacity/motion）、templates/ui/components.md、templates/ui/flows.mmd、templates/ui/skeleton.html、templates/ui/stories.feature、templates/ui/types.ts、templates/ui/types.schema.json
+- 文档
+  - README.md：Available Slash Commands 增加 /speckit.ui；新增 “UI Command Usage” 小节（分支/环境、只用 JSON 键、Schema 优先）
+- 兼容性
+  - 非破坏性（不改 CLI 内核）
+- 与版本/日志（仅当触及 CLI 核心）
+  - 是否修改 src/specify_cli/__init__.py：否
+  - 版本/CHANGELOG：不适用
+
+如何验证（可复现步骤）
+
+- 环境要求：Python 3.11+、uv、Git
+- 本地快速演示（不 init，Bash）
+  - export SPECIFY_FEATURE=001-ui-blueprint
+  - bash scripts/bash/setup-ui.sh | tee /tmp/ui.json
+  - 真实 JSON 输出（示例）：
+    - {"UI_DIR":"/abs/specs/001-ui-blueprint/ui","TOKENS_FILE":"/abs/specs/001-ui-blueprint/ui/tokens.json","COMPONENTS_SPEC":"/abs/specs/001-ui-blueprint/ui/components.md","FLOWS_FILE":"/abs/specs/001-ui-blueprint/ui/flows.mmd","HTML_SKELETON":"/abs/specs/001-ui-blueprint/ui/skeleton.html","BDD_FILE":"/abs/specs/001-ui-blueprint/ui/stories.feature","TYPES_TS":"/abs/specs/001-ui-blueprint/ui/types.ts","TYPES_SCHEMA":"/abs/specs/001-ui-blueprint/ui/types.schema.json","README_FILE":"/abs/specs/001-ui-blueprint/ui/README.md"}
+  - 校验（Linux）：
+    - jq -e '.README_FILE and .TOKENS_FILE and .COMPONENTS_SPEC and .FLOWS_FILE and .HTML_SKELETON and .BDD_FILE' /tmp/ui.json
+    - for k in TOKENS_FILE COMPONENTS_SPEC FLOWS_FILE HTML_SKELETON BDD_FILE README_FILE; do f=$(jq -r .${k} /tmp/ui.json); test -s "$f" || echo "Empty: $f"; done
+- 打包产物验证（Linux）
+  - bash .github/workflows/scripts/create-release-packages.sh v0.0.5
+  - unzip -p .genreleases/spec-kit-template-claude-sh-v0.0.5.zip .claude/commands/speckit.ui.md | grep -qv '.specify.specify/'
+  - 解包后运行 .specify/scripts/.../setup-ui.*，重复“JSON 键齐备 + 文件非空”检查
+- CI 冒烟
+  - .github/workflows/ui-smoke.yml（Ubuntu + Windows）：
+    - 构建包、检查无 .specify.specify、执行 create-new-feature + setup-ui、校验 JSON 键存在与文件非空、JSON 合法性（jq），并做脚本静态分析（shellcheck/PSScriptAnalyzer 警告级）
+
+风险与回滚
+
+- 风险：路径重写规则微调、增加 CI 工作流
+- 回滚：如有问题，可快速 revert 本 PR；或保留 UI 模板与命令，移除幂等折叠/CI 后再观察
+
+文档与工作流
+
+- README 是否更新：是（Available Slash Commands 与 UI Command Usage）
+- docs 是否更新：否
+- CI/CD 影响：是（新增 .github/workflows/ui-smoke.yml）
+
+性能与安全
+
+- 性能：仅模板与脚本文本；无运行时开销
+- 安全：不引入凭据；路径输出为本地绝对路径，仅供本地生成与编辑
+
+AI 使用披露
+
+- 此 PR 使用了 AI 辅助起草与整理模板/脚本，所有改动已人工审阅并在本地与打包环境中验证通过。
+
+关联项
+
+- 建议评审人：@localden
+- 重点希望评审的部分：
+  - 命令说明“只用 JSON 键”的稳健性
+  - fail-fast 行为是否符合仓库质量预期
+  - JSON Schema/TS 双模板的技术中立性与默认策略（Schema 优先）
+