@gordon.gan/specflow 1.3.3-beta → 1.4.0-beta

package/skills/specflow-approval/SKILL.md

@@ -0,0 +1,508 @@
+---
+name: specflow-approval
+description: "Post-refine technical approval document -- AI closed-loop check + code/baseline grounding + over-design guard + implementability assessment"
+---
+
+# SpecFlow: Approval
+
+> **HARD GATE**: phase must be `refined`. Run `/specflow:refine` first if not.
+> **HARD GATE**: User must confirm before `approval.md` is written to the change directory.
+> Approval does NOT advance phase — it produces an optional review artifact for human sign-off.
+
+## Purpose
+
+Approval is the **post-refine, pre-apply technical review pass**: it reads the four
+refined artifacts (`proposal.md`, delta `specs/`, `design.md`, `tasks.md`), **grounds them
+against existing project code and spec baseline**, and produces a single `approval.md`
+technical-approval document for human sign-off.
+
+It is **optional**. Skip it when you want to go straight from refine to apply. Use it when
+the change is significant enough to warrant formal technical review before implementation
+begins — architecture decisions, cross-team impact, regulatory exposure, or any change where
+"should we even build this, this way?" deserves a documented answer.
+
+Unlike `/specflow:review` (which reviews code after implementation) and `/specflow:verify`
+(which validates implementation against specs), approval reviews the **plan** before any
+code is written. It fills the gap between refine convergence and apply execution.
+
+Approval does five things a deterministic CLI cannot:
+
+1. **Integrates** the four artifacts into a single narrative with cross-references.
+2. **Checks closed-loop coherence** across requirements ↔ design ↔ specs ↔ tasks using
+   semantic reasoning (fuzzy wording detection, coverage gaps, traceability).
+3. **Grounds the plan against reality** — reads existing project code (anchor files) and
+   the main spec baseline to verify the plan can actually land on this codebase.
+4. **Guards design quality** — detects over-engineering (YAGNI violations) while confirming
+   reasonable extensibility is preserved.
+5. **Assesses implementability** — can an engineer execute this plan without getting stuck?
+
+## Invocation
+
+```text
+/specflow:approval <change-name>
+```
+
+Cursor: `specflow:approval <change-name>`;Codex: `$specflow-approval <change-name>`.
+
+## Prerequisites
+
+- An active change exists with `.specflow.yaml` and `phase: refined`.
+  - If phase is not `refined`, REFUSE to proceed and suggest: "This change is in phase
+    `<phase>`. Run `/specflow:refine` first to complete deep review before generating an
+    approval document."
+- All four refined artifacts exist in `specflow/changes/<name>/`:
+  - `proposal.md`
+  - `specs/**/*.md` (at least one delta spec)
+  - `design.md`
+  - `tasks.md`
+- `specflow` CLI is available on PATH (for `specflow validate` and optional status lookup).
+- Optional: `explore.md` with `Status: confirmed` (enriches the approval's "why" section).
+
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active planning
+root's `specflow/config.yaml` before generating `approval.md`. Apply the policy to all
+human-readable narrative content (summaries, assessments, evidence). Preserve protocol
+markers (`### Requirement:`, `#### Scenario:`, `- **WHEN**`, `- **THEN**`), capability IDs,
+change names, file paths, commands, and code in their original form.
+
+---
+
+## Stage 1: Pre-flight Validation
+
+1. Read `.specflow.yaml` and confirm `phase: refined`. If not, refuse and suggest `/specflow:refine`.
+2. Confirm all four artifacts exist. If any is missing, stop and tell the user which are missing.
+3. Read `specflow/config.yaml` and resolve `artifacts.language` (default `en`).
+4. Detect project tech stack signals at the project root only (do not recurse):
+   - `package.json` → Node/TS/JS ecosystem
+   - `go.mod` → Go
+   - `pyproject.toml` / `requirements.txt` → Python
+   - `Cargo.toml` → Rust
+   - `tsconfig.json` → TypeScript (refines Node detection)
+   - If none match, set `techStack: unknown`
+5. Read `specflow/specs/` baseline if it exists (for Pass 7 baseline cross-check).
+
+Announce: "Generating technical approval document for change `<name>` (phase=refined, language=<lang>, techStack=<stack>)."
+
+---
+
+## Stage 2: Load Execution Instructions
+
+Read the file at `.claude/specflow/prompts/approval/generate.md` and follow its instructions.
+
+That prompt file contains the complete specification for:
+
+- The 7-dimension closed-loop verification (Passes 1–7, each with AI self-prompt, verdict rules, evidence format)
+- The design quality assessment (over-engineering signals + extensibility signals)
+- The architecture design (Mermaid module-dependency/system-interaction diagrams + core-component responsibility & boundary table, with project-type adaptation)
+- The detailed design generation (data structures / interfaces / business flow / core logic / config / compatibility, with project-type adaptation and traceability rules)
+- The test strategy (layered test matrix: unit/integration/acceptance/regression/performance-security-compat, each layer mapped to acceptance criteria)
+- The deployment/release/rollback plan (deployment method/order, release strategy, rollback, monitoring; selective with "不涉及运行时部署" for pure-library projects)
+- The implementability assessment (7 dimensions with verdict rules)
+- The approval document structure and generation rules
+- Protocol-marker preservation and language policy enforcement
+- Dashboard count computation (must be precise, not AI-guessed)
+- Anchor-file extraction and code-reading rules (depth: anchor file only, no recursion)
+
+You MUST read `generate.md` before performing any analysis or writing `approval.md`. Do not
+invent the assessment dimensions or document structure — they are defined in that prompt.
+
+---
+
+## Stage 3: Extract Anchor Files
+
+Before running the closed-loop passes, extract the set of **anchor files** that the plan
+references. These are the files Pass 6 (Code Grounding) will read.
+
+**Extraction rules** (defined in detail in `generate.md` Part A → Pass 6):
+
+1. Scan `design.md` and `tasks.md` for file path references (backtick-quoted paths, code
+   blocks, or inline paths like `src/core/...`).
+2. Collect only paths under the project root that look like source files (`.ts`, `.js`,
+   `.py`, `.go`, `.rs`, `.kt`, `.java`, etc.) or config files (`package.json`, `tsconfig.json`,
+   etc.).
+3. Deduplicate. Do NOT read directories, only files.
+4. **Depth limit: read the anchor file itself only.** Do not follow imports, do not recurse.
+5. If no anchor files are found and the project has no source code (greenfield), Pass 6
+   will emit `skipped (greenfield — no existing code)`. If the project HAS source code but
+   the plan references no existing files, that is a `FAIL` (plan is ungrounded).
+
+Announce the extracted anchor file list to the user before Pass 1 begins.
+
+---
+
+## Stage 4: AI Closed-Loop Verification
+
+Perform the 7 closed-loop passes defined in `generate.md`, in order:
+
+### Internal coherence (Passes 1–5)
+
+1. **Pass 1 — Requirement Closure**: proposal ↔ specs coverage
+2. **Pass 2 — Design Closure**: design decisions ↔ spec requirements
+3. **Pass 3 — Spec Closure**: scenario completeness + testability (3-level grading) + delta integrity
+4. **Pass 4 — Implementation Closure**: tasks ↔ spec requirements coverage + granularity
+5. **Pass 5 — Risk Closure**: risks ↔ mitigations + BREAKING migration + unidentified risks
+
+### External grounding (Passes 6–7)
+
+6. **Pass 6 — Code Grounding**: design/tasks anchor files exist in the project + structure
+   compatibility + tech-stack consistency. Reads actual project code (anchor files only).
+7. **Pass 7 — Baseline Cross-Check**: delta specs vs `specflow/specs/` main baseline —
+   conflict detection, duplicate-definition detection, MODIFIED name matching.
+
+Each Pass must produce visible output to the user:
+
+- **Verdict**: `PASS` | `WARNING` | `FAIL` | `SKIPPED`
+- **Evidence**: concrete citations (file, section, requirement name, scenario name, line)
+
+Present each Pass's result as it completes — do not batch all 7 at the end. The user should
+see the reasoning unfold and can interject if a Pass reveals something that changes direction.
+
+### Closed-Loop Overall Verdict
+
+After all 7 Passes:
+
+- `FAIL` if any Pass is `FAIL`
+- `PASS WITH WARNINGS` if no `FAIL` but at least one `WARNING`
+- `PASS` if all Passes are `PASS` (a `SKIPPED` Pass does not affect the verdict)
+
+---
+
+## Stage 5: Design Quality Assessment
+
+Perform the two design-quality checks defined in `generate.md` Part B:
+
+### Over-Engineering Check
+
+Scan `design.md` and `tasks.md` for the 5 over-engineering signals:
+
+1. Interface for unrequested requirements
+2. Unnecessary abstraction layers
+3. Pre-built unused infrastructure
+4. Config fields beyond current needs
+5. Complexity exceeding problem scale
+
+**Verdict rule**: 1 signal → `WARNING`; 3+ signals → `FAIL`; 0 signals → `PASS`.
+
+### Extensibility Assessment
+
+Scan `design.md` for the 5 extensibility signals:
+
+1. Namespace reservation
+2. Stable interface, replaceable implementation
+3. Explicit Non-Goals
+4. Backward-compatibility path
+5. Decision rationale mentions extensibility trade-off
+
+**Verdict rule**: 4-5 signals present → `PASS`; 2-3 → `WARNING`; 0-1 → `WARNING`.
+
+### Combined Design Quality Verdict
+
+- `FAIL` if over-engineering is `FAIL`
+- `WARNING` if either check is `WARNING`
+- `PASS` if both are `PASS`
+- **Special**: if over-engineering = `WARNING`/`FAIL` AND extensibility = `WARNING` →
+  escalate to `FAIL` (the plan is both bloated AND not extensible)
+
+---
+
+## Stage 6: Architecture Design
+
+Produce the **architecture design** section (approval.md §5 架构整体设计) defined in
+`generate.md` Part E. This answers "what modules make up the system, how they depend on
+and interact with each other, and what each module's responsibility and boundary is."
+
+It is complementary to Detailed Design: architecture is about **module-to-module
+relationships** (macro), detailed design is about **module-internal implementation**
+(micro).
+
+### 5.1 Overall Architecture
+
+Draw a Mermaid diagram — **system interaction diagram** or **module dependency diagram**:
+
+- **Module dependency / layered diagram** — `mermaid flowchart LR` (modules as nodes,
+  dependencies as edges)
+- **System interaction diagram** — `mermaid sequenceDiagram` (participants as modules/roles)
+
+Requirements:
+
+1. **Mark changed modules** (`[新增]` / `[修改]` labels or color) so the reviewer can see
+   the change surface at a glance.
+2. Label edges with dependency direction (who depends on whom) or interaction message
+   (who calls whom, passing what).
+3. Project-type mapping: CLI/library → `src/core/*`, `src/cli/*`; Web → services/components;
+   multi-repo → repositories/services.
+4. The diagram must be consistent with §4 decisions — every structure shown must trace to
+   a decision.
+
+### 5.2 Core Components
+
+Define each module/component's responsibility and boundary in a table:
+
+| Component | Responsibility | Boundary (does / does NOT) | Depends on | Change type |
+|-----------|---------------|----------------------------|-----------|-------------|
+
+Requirements:
+
+1. List **all involved components** (added + modified) with responsibility, boundary,
+   dependency.
+2. Boundary must state **what it does NOT do** — to keep logic in the right module (e.g.,
+   CLI does not parse slash args, core layer does not do AI reasoning).
+3. Dependency direction explicit, avoid circular dependencies.
+4. **Consistent with §5.1 diagram**: every table component appears in the diagram; table
+   dependencies match diagram edges.
+5. Each component boundary traces to a §4 decision.
+
+**If the change does not alter architecture**: write the explicit `不涉及架构变更(单模块/
+单文件调整,模块边界无变化)` marker instead of leaving blank.
+
+### 5.3 Architecture Consistency Self-check
+
+- Diagram marks added/modified modules; change surface visible at a glance.
+- Each component has a "does NOT do" boundary.
+- Diagram and table correspond 1:1.
+- Component boundaries trace to §4 decisions.
+- Uninvolved categories carry the explicit "不涉及架构变更" marker.
+
+Present the architecture design to the user as part of the confirmation summary.
+
+---
+
+## Stage 7: Detailed Design
+
+Produce the **detailed design** section (approval.md §6 方案详细设计) defined in
+`generate.md` Part E. This takes the plan from "macro decisions" to "implementer-ready
+detail".
+
+The detailed design is **selective**: cover only the categories this change actually
+involves. For each category NOT involved, write the explicit "不涉及 X" marker instead of
+leaving it blank.
+
+Categories (from `generate.md` §6.1–6.6):
+
+1. **数据结构 / 数据模型变更** — table structures, fields, types, constraints, index
+   recommendations (query-driven), data migration. For CLI/library projects: config
+   structure, state files, YAML schema.
+2. **接口设计** — API/RPC/CLI command signatures, input params (name/type/required/valid
+   values/defaults), output shapes, error-code definitions with status-code mapping.
+3. **业务流程** — sequence description (who calls whom, order, branches, error paths) or
+   state-machine transitions (states/events/conditions/terminal). Use Mermaid
+   `sequenceDiagram` / `stateDiagram-v2` when clarifying.
+4. **核心算法 / 逻辑说明** — input/output, processing steps, complexity, boundary conditions.
+5. **配置与运行环境** — new config keys, env vars, runtime dependencies.
+6. **兼容性与迁移** — old→new behavior mapping, migration path, rollback.
+
+**Traceability requirement** (hard rule): every detailed-design element must trace to a
+§3 Requirement/Scenario and a §4 decision. If an element cannot be written at
+implementer-ready detail, mark it `[待 refine 澄清: <元素>]` and report it to the user —
+this is a quality signal that the plan is not fully thought through.
+
+**Quality self-check** after drafting:
+
+- Every involved category has real content (signatures/fields/states), no blank placeholders.
+- Every uninvolved category has the explicit "不涉及" marker.
+- Data/interface/flow elements trace to spec requirements and design decisions.
+
+Present the detailed design to the user as part of the confirmation summary.
+
+---
+
+## Stage 8: Test Strategy
+
+Produce the **test strategy** section (approval.md §7 测试策略) defined in `generate.md`
+Part E. This upgrades "is §3 acceptance verifiable" into "**how will layered tests prove
+the plan is correct**." It answers: which test layer covers each acceptance criterion
+(WHEN/THEN), with what tool, proving what.
+
+### 8.1 Layered Test Matrix
+
+Produce a layered test matrix:
+
+| Test layer | Covers | Tool/framework | Goal (proves what) | Acceptance criteria covered |
+|-----------|--------|---------------|--------------------|----------------------------|
+
+Layers (selective — only those this change actually needs):
+
+- **Unit tests** — core functions/classes/internal logic
+- **Integration tests** — module interactions, interface contracts, external deps
+- **Acceptance tests** — spec WHEN/THEN user-visible behavior (E2E / CLI tests)
+- **Regression tests** — main-spec baseline + existing behavior
+- **Performance / security / compatibility** — NFR goals (as applicable)
+
+Requirements:
+
+1. Each test layer **maps to §3 acceptance criteria** (cite specific Scenario names) — this
+   closes the loop between test strategy and acceptance criteria.
+2. Each layer annotates **tool/framework** (echoing full-stack-skills' phase→skill mapping:
+   test phase → test-writer/playwright/pytest).
+3. **Goals must be verifiable** ("prove P95 < 200ms", not "test performance").
+4. Distinguish **new tests** vs **modifications to existing tests**.
+
+### 8.2 Test Environment & Data
+
+Cover: test environment (local tmpdir / isolated CI), fixture/seed data (incl. Chinese/
+English samples), parallelism/isolation, coverage target.
+
+### 8.3 Test Strategy Self-check
+
+- Every §3 acceptance criterion is covered by ≥1 test layer (closed loop).
+- Every test layer has a tool and a verifiable goal.
+- Existing behavior is protected by regression tests (corresponds to Pass 7 baseline).
+- New tests vs modifications to existing tests are distinguished.
+
+**If the change needs no testing**: write the explicit `不涉及测试变更(纯文档/配置变更,无
+行为逻辑需要测试)` marker.
+
+Present the test strategy to the user as part of the confirmation summary.
+
+---
+
+## Stage 9: Deployment & Release
+
+Produce the **deployment / release / rollback** section (approval.md §8 部署/发布/回滚方案)
+defined in `generate.md` Part E. This answers "how does the change go live, how is it
+released, how do we roll back if something breaks, and how do we monitor it after launch."
+
+**Selective**: mandatory for projects with a running system; pure library/CLI/documentation
+projects write the explicit `不涉及运行时部署(纯库/CLI/文档项目,无服务上线,变更通过包发布/
+版本发布交付)` marker.
+
+### 9.1 Deployment Plan
+
+Cover: deployment target (prod/staging/multi-env), deployment method (image/package/code/
+config; CI pipeline steps), deployment order (e.g. DB migration before app deploy), config
+management (new keys per env, secrets), environment differences.
+
+### 9.2 Release Strategy
+
+Cover: release method (blue-green / canary / rolling / direct replace + rationale), release
+window / canary ratio, old-new compatibility during coexistence (API versioning, DB compat).
+
+### 9.3 Rollback Plan
+
+Cover: rollback trigger conditions (error rate / metric thresholds), rollback method (image
+revert / code revert / data rollback; auto or manual), data consistency on rollback
+(if data migration), rollback verification.
+
+### 9.4 Monitoring & Observability
+
+Cover: key metrics to monitor post-launch, logging/tracing, alert thresholds & owner.
+
+### 9.5 Deployment Self-check
+
+- Deployment target / method / order explicit.
+- Release strategy with compatibility.
+- Rollback trigger / method / data consistency / verification explicit.
+- Post-launch monitoring metrics & alerts explicit.
+
+Present the deployment plan to the user as part of the confirmation summary.
+
+---
+
+## Stage 10: Implementability Assessment
+
+Perform the 7 implementability dimensions defined in `generate.md` Part C:
+
+1. **Completeness** — no TODOs, placeholders, vague tasks
+2. **Spec Alignment** — tasks cover all spec requirements, no scope creep
+3. **Task Actionability** — can an engineer execute each task without ambiguity
+4. **Technical Feasibility** — design decisions are achievable in the detected tech stack
+5. **Dependency Clarity** — task dependencies and external dependencies are explicit
+6. **Architecture Consistency** — design choices match project's existing tech stack, directory structure, error-handling patterns, and test framework (grounded in code reading from Pass 6)
+7. **Implementation Risk** — high-risk module changes, data migration, concurrency, external API breaks, team tech-stack unfamiliarity
+
+Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) with evidence.
+
+### Implementability Overall Verdict
+
+- `BLOCKED` if any dimension is `BLOCKED`
+- `NEEDS REFINEMENT` if no `BLOCKED` but any dimension is `NEEDS REFINEMENT`
+- `READY` if all 7 are `READY`
+
+---
+
+## Stage 11: Generate approval.md
+
+Following the document structure and generation rules in `generate.md` Part E, produce
+`approval.md` inside the change directory at `specflow/changes/<name>/approval.md`.
+
+Key rules:
+
+- Dashboard counts (capability count, requirement count, scenario count, task count, anchor
+  file count, baseline spec count) MUST be computed by reading the actual files, not
+  estimated. If a count is uncertain, say so explicitly rather than guessing.
+- The "Decision Review" table must include every decision found in `design.md`.
+- The "Acceptance Criteria" section must include every Requirement and Scenario from all
+  delta specs, with 3-level testability grading.
+- The "Detailed Design" section must be selective: real content for involved categories,
+  explicit "不涉及" markers for uninvolved ones, every element traceable to spec + decision.
+- The "Test Strategy" section must be a layered matrix where every §3 acceptance criterion
+  is covered by ≥1 layer (closed loop), with tools and verifiable goals.
+- The "Deployment/Release/Rollback" section must be selective: real plan for running
+  systems, explicit "不涉及运行时部署" marker for pure-library/CLI/documentation projects.
+- The "Code Grounding" section (Pass 6 evidence) must cite actual file paths read and
+  concrete findings (function signatures, module structure, compatibility assessment).
+- The human sign-off table must be empty (blank fields for the approver to fill).
+- AI pre-approval recommendation must be grounded in all three verdicts (closed-loop,
+  design quality, implementability) — never recommend "approve" if any verdict is `FAIL`.
+
+---
+
+## Gate: User Confirmation
+
+Present a summary to the user:
+
+- Closed-loop overall verdict (PASS / PASS WITH WARNINGS / FAIL)
+- Design quality verdict (PASS / WARNING / FAIL)
+- Implementability overall verdict (READY / NEEDS REFINEMENT / BLOCKED)
+- AI pre-approval recommendation (建议批准 / 有条件批准 / 退回 refine / 拒绝)
+- The path where `approval.md` will be written
+
+Ask explicitly:
+
+> "确认生成审批文档并写入 `specflow/changes/<name>/approval.md`?"
+
+Do NOT write the file until the user confirms. If the user wants changes to the assessment,
+re-run the relevant Pass or dimension and update the summary before re-asking.
+
+On confirmation:
+
+1. Write `approval.md` to the change directory.
+2. Do NOT change `phase` — it remains `refined`.
+3. Report the file path and next-step suggestions.
+
+---
+
+## Stage 12: Next-Step Suggestions
+
+Based on the assessment results:
+
+- **If closed-loop = PASS, design quality = PASS, and implementability = READY**:
+  Suggest `/specflow:apply` to begin implementation.
+
+- **If any verdict is WARNING**:
+  Suggest the user either (a) proceed to `/specflow:apply` after acknowledging the warnings
+  in the approval document, or (b) return to `/specflow:refine` to close the gaps first.
+
+- **If any verdict is FAIL or implementability = BLOCKED**:
+  Strongly recommend `/specflow:refine` to resolve the failures before implementation.
+  Do NOT suggest `/specflow:apply` — the plan is not ready.
+
+In all cases, remind the user that `approval.md` is an optional artifact: it does not block
+`/specflow:apply` (which only requires `phase=refined`), and it does not affect
+`/specflow:archive` (which scans `specs/`, not `approval.md`).
+
+---
+
+## Not Covered by Approval
+
+- No code implementation — `/specflow:apply` owns that.
+- No phase transition — phase stays `refined` until `/specflow:apply` advances it.
+- No spec validation — `/specflow:verify` owns delta + main spec regression checks.
+- No code review — `/specflow:review` owns post-implementation code quality checks.
+- No artifact modification — approval reads the four artifacts (and project code, read-only)
+  but never modifies them. If a Pass reveals a gap, the user returns to `/specflow:refine`
+  to fix it; approval only documents the finding.
+- No full codebase scan — approval reads only the anchor files extracted in Stage 3. Full
+  codebase investigation is `/specflow:explore`'s job.
+- Approval is **not** a gate for apply. It is a decision-support artifact for human review.