diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml index 896ab21913..10f231689d 100644 --- a/.github/workflows/community-smoke.yml +++ b/.github/workflows/community-smoke.yml @@ -97,15 +97,7 @@ jobs: speckit-arch-reverse; do test -f ".claude/skills/$arch_skill/SKILL.md" done - for preview_skill in \ - speckit-preview-low-md \ - speckit-preview-low-html \ - speckit-preview-mid-md \ - speckit-preview-mid-html \ - speckit-preview-high-md \ - speckit-preview-high-html; do - test -f ".claude/skills/$preview_skill/SKILL.md" - done + test -f .claude/skills/speckit-preview-wireflow/SKILL.md test -f .claude/skills/speckit-discovery-contract/SKILL.md test -f .claude/skills/speckit-intake-visual-design/SKILL.md test -f .claude/skills/speckit-intake-prd/SKILL.md @@ -135,15 +127,7 @@ jobs: test "$(find .claude/skills -maxdepth 1 -type d -name 'speckit-arch-*' | wc -l)" -eq 0 ;; preview) - for preview_skill in \ - speckit-preview-low-md \ - speckit-preview-low-html \ - speckit-preview-mid-md \ - speckit-preview-mid-html \ - speckit-preview-high-md \ - speckit-preview-high-html; do - test ! -d ".claude/skills/$preview_skill" - done + test ! -d .claude/skills/speckit-preview-wireflow ;; discovery) test "$(find .claude/skills -maxdepth 1 -type d -name 'speckit-discovery-*' | wc -l)" -eq 0 @@ -166,16 +150,8 @@ jobs: grep -q "architecture planning contract" .claude/skills/speckit-arch-generate/SKILL.md ;; preview) - for preview_skill in \ - speckit-preview-low-md \ - speckit-preview-low-html \ - speckit-preview-mid-md \ - speckit-preview-mid-html \ - speckit-preview-high-md \ - speckit-preview-high-html; do - test -f ".claude/skills/$preview_skill/SKILL.md" - grep -q "evidence-backed" ".claude/skills/$preview_skill/SKILL.md" - done + test -f .claude/skills/speckit-preview-wireflow/SKILL.md + grep -q "Input-to-Design Synthesis Pass" .claude/skills/speckit-preview-wireflow/SKILL.md ;; discovery) test -f .claude/skills/speckit-discovery-contract/SKILL.md diff --git a/extensions/catalog.community.json b/extensions/catalog.community.json index 867b6c6c63..f3cb0aea5c 100644 --- a/extensions/catalog.community.json +++ b/extensions/catalog.community.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-07-03T00:00:00Z", + "updated_at": "2026-07-06T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json", "extensions": { "agent-assign": { @@ -2524,10 +2524,10 @@ "preview": { "name": "Spec Kit Preview", "id": "preview", - "description": "Generate evidence-backed low, mid, or high fidelity previews from Spec Kit artifacts as Markdown or self-contained HTML", + "description": "Generate one fidelity-specific HTML design artifact from spec.md and uc.md inputs with required low, mid, or high fidelity", "author": "bigsmartben", - "version": "1.2.0", - "download_url": "https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.2.0.zip", + "version": "1.3.0", + "download_url": "https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.3.0.zip", "repository": "https://github.com/bigsmartben/spec-kit-preview", "homepage": "https://github.com/bigsmartben/spec-kit-preview", "documentation": "https://github.com/bigsmartben/spec-kit-preview/blob/main/README.md", @@ -2539,14 +2539,13 @@ "speckit_version": ">=0.8.10.dev0" }, "provides": { - "commands": 6, + "commands": 1, "hooks": 0 }, "tags": [ "preview", "prototype", "html", - "markdown", "wireflow", "ux" ], @@ -2554,7 +2553,7 @@ "downloads": 0, "stars": 0, "created_at": "2026-05-15T00:00:00Z", - "updated_at": "2026-07-01T00:00:00Z" + "updated_at": "2026-07-06T00:00:00Z" }, "product": { "name": "Product Spec Extension", diff --git a/extensions/catalog.json b/extensions/catalog.json index 5674648166..8d19786a6d 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-07-03T00:00:00Z", + "updated_at": "2026-07-06T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json", "extensions": { "agent-context": { @@ -96,8 +96,8 @@ "preview": { "name": "Spec Kit Preview", "id": "preview", - "version": "1.2.0", - "description": "Generate evidence-backed low, mid, or high fidelity previews from Spec Kit artifacts as Markdown or self-contained HTML", + "version": "1.3.0", + "description": "Generate one fidelity-specific HTML design artifact from spec.md and uc.md inputs with required low, mid, or high fidelity", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-preview", "license": "MIT", @@ -106,13 +106,12 @@ "speckit_version": ">=0.8.10.dev0" }, "provides": { - "commands": 6 + "commands": 1 }, "tags": [ "preview", "prototype", "html", - "markdown", "wireflow", "ux" ] diff --git a/extensions/preview/.gitignore b/extensions/preview/.gitignore index 4f5e1d4482..126188574e 100644 --- a/extensions/preview/.gitignore +++ b/extensions/preview/.gitignore @@ -1,23 +1,6 @@ .venv/ -venv/ __pycache__/ -*.py[cod] +*.pyc .pytest_cache/ -.mypy_cache/ -.ruff_cache/ -.coverage -htmlcov/ dist/ -build/ -*.egg-info/ *.zip -*.log -.env -.env.* -!.env.example -.tmp/ -tmp/ -temp/ -.DS_Store -Thumbs.db -.worktrees/ diff --git a/extensions/preview/CATALOG-SUBMISSION.md b/extensions/preview/CATALOG-SUBMISSION.md index d71badf07f..acf5bd3aa0 100644 --- a/extensions/preview/CATALOG-SUBMISSION.md +++ b/extensions/preview/CATALOG-SUBMISSION.md @@ -2,40 +2,43 @@ Extension ID: preview Name: Spec Kit Preview -Version: 1.2.0 -Description: Generate evidence-backed low, mid, or high fidelity previews from Spec Kit artifacts as Markdown or self-contained HTML +Version: 1.3.0 +Description: Generate one fidelity-specific HTML design artifact from spec.md and uc.md inputs with required low, mid, or high fidelity Author: bigsmartben Repository URL: https://github.com/bigsmartben/spec-kit-preview -Download URL: https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.2.0.zip +Download URL: https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.3.0.zip Documentation URL: https://github.com/bigsmartben/spec-kit-preview/blob/main/README.md License: MIT Required Spec Kit version: >=0.8.10.dev0 -Commands count: 6 +Commands count: 1 Hooks count: 0 -Tags: preview, prototype, html, markdown, wireflow, ux +Tags: preview, prototype, html, wireflow, ux ## Key Features -- Adds `speckit.preview.low-md` and `speckit.preview.low-html`. -- Adds `speckit.preview.mid-md` and `speckit.preview.mid-html`. -- Adds `speckit.preview.high-md` and `speckit.preview.high-html`. -- Generates `specs//preview/wireflow-low.md`, `wireflow-mid.md`, or `wireflow-high.md`. -- Generates matching `wireflow-low.html`, `wireflow-mid.html`, or `wireflow-high.html`. -- Optionally adapts mid-fidelity structured intake artifacts through `schemas/preview/mid-ir-adapter.schema.json`. -- Uses fixed templates under `templates/preview/` for output sections, table schemas, HTML shells, and preserved-review slots. +- Adds `speckit.preview.wireflow` as the single preview command. +- Requires `low`, `mid`, or `high` as the first command argument. +- Generates one HTML design artifact at `specs//preview/wireflow.html`. +- Requires `spec.md` and `uc.md` as first-class source inputs for design synthesis. +- Runs an Input-to-Design Synthesis Pass before composing the design artifact. +- Preserves `schemas/preview/mid-ir-adapter.schema.json` as an optional supporting input boundary for `mid` fidelity. +- Uses evidence and quality conclusions to improve the fidelity-specific design artifact by exposing supported flows, gaps, and design questions. +- Uses fixed `templates/preview/wireflow.html` output structure with design input mapping, interaction, state, and preserved design-note slots. - Uses `schemas/preview/contract.json` and `schemas/preview/contract.schema.json` as the structural validation source. -- Keeps previews self-contained with inline CSS and fidelity-appropriate JavaScript. +- Keeps the preview self-contained with inline CSS and template-local JavaScript. - Explicitly avoids production source, spec, plan, and task file changes. -- Captures coverage evidence, inferred assumptions, unsupported items, and unresolved questions. ## Testing Performed -- `python3 -m py_compile tests/validate-extension.py` -- `python3 tests/validate-extension.py` -- Validated `schemas/preview/mid-ir-adapter.schema.json` with Draft 2020-12 schema checks and adapter smoke payloads. -- Confirmed adapter smoke payloads reject empty page purpose, missing `source_refs` for covered items, and root-level upstream `contract_type`. +- `python -m py_compile tests/validate-extension.py` +- `python tests/validate-extension.py` +- Validator verified the manifest registers one `speckit.preview.wireflow` command. +- Validator verified the command/template file set contains only `commands/speckit.preview.wireflow.md` and `templates/preview/wireflow.html`. +- Validator verified declared schema files, including `schemas/preview/mid-ir-adapter.schema.json`. +- Validator verified documentation alignment for `speckit.preview.wireflow` and `wireflow.html`. + ## Release Checklist -- Create release `v1.2.0` from this revision. +- Create release `v1.3.0` from this revision. - Install release ZIP in a fresh Spec Kit project: - `specify extension add preview --from https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.2.0.zip` + `specify extension add preview --from https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.3.0.zip` diff --git a/extensions/preview/CHANGELOG.md b/extensions/preview/CHANGELOG.md index e622d501ee..e0d3cda0a5 100644 --- a/extensions/preview/CHANGELOG.md +++ b/extensions/preview/CHANGELOG.md @@ -1,23 +1,29 @@ # Changelog +## v1.3.0 + +- Replaces separate fidelity and format commands with one `speckit.preview.wireflow` command. +- Requires `low`, `mid`, or `high` as the first command argument. +- Makes HTML the only generated artifact at `specs//preview/wireflow.html`. +- Uses `spec.md` and `uc.md` as required primary inputs for input-to-design synthesis. +- Keeps structured IR mapping non-blocking for `mid` fidelity: missing, partial, or unmappable IR falls back to primary design inputs and is reported as a design question or delivery quality issue. + ## v1.2.0 - Adds a preview-owned `schemas/preview/mid-ir-adapter.schema.json` ingest contract for evidence-backed mid-fidelity structured IR adaptation. -- Updates `speckit.preview.mid-md` and `speckit.preview.mid-html` to optionally consume `structured-ir.yaml`, `ir-assertions.yaml`, and `ir-evidence-packet.md` when they can be mapped to the preview adapter contract. -- Keeps structured IR mapping non-blocking: missing, partial, or unmappable IR falls back to existing Spec Kit artifacts and is reported as an evidence gap. - Updates package validation so declared schema files are driven by `schemas/preview/contract.json` instead of a hard-coded schema file list. ## v1.1.0 -- Adds six preview commands: `speckit.preview.low-md`, `speckit.preview.low-html`, `speckit.preview.mid-md`, `speckit.preview.mid-html`, `speckit.preview.high-md`, and `speckit.preview.high-html`. -- Adds separate Markdown and HTML output designs for low, mid, and high fidelity preview artifacts. -- Adds fixed preview templates under `templates/preview/` so command prompts no longer define output structure inline. -- Adds schema-backed validation contracts under `schemas/preview/` for command/template structure checks. -- Adds consistent active feature detection and update-preservation guidance across preview commands. -- Strengthens package validation for command/template responsibility separation, output boundaries, and fidelity-specific contracts. +- Replaces the six preview commands with one `speckit.preview.wireflow` command. +- Requires `low`, `mid`, or `high` as the first command argument. +- Makes HTML the only generated artifact at `specs//preview/wireflow.html`. +- Adds a unified `templates/preview/wireflow.html` template. +- Adds explicit Input-to-Design Synthesis Pass rules for `spec.md` and `uc.md`. +- Adds schema-backed validation contracts under `schemas/preview/` for single-command and single-template checks. +- Strengthens package validation for command/template responsibility separation, output boundaries, and documentation alignment. ## v1.0.0 - Initial release. -- Adds `speckit.preview.html` for generating self-contained interactive HTML prototypes from Spec Kit feature artifacts. - +- Adds an initial self-contained interactive HTML preview flow for Spec Kit feature artifacts. diff --git a/extensions/preview/README.md b/extensions/preview/README.md index 0296a38e19..364cb6886a 100644 --- a/extensions/preview/README.md +++ b/extensions/preview/README.md @@ -1,104 +1,100 @@ # Spec Kit Preview Extension -Generate evidence-backed low, mid, or high fidelity previews from Spec Kit feature artifacts as Markdown or self-contained HTML. +Generate one fidelity-specific HTML design artifact from `spec.md` and `uc.md` inputs. The command requires a `low`, `mid`, or `high` fidelity parameter. ## Overview -This extension adds review artifacts between specification and implementation. It helps teams validate product flows, page/state structure, coverage evidence, layout assumptions, UI states, and interaction details before production code is planned or built. +This extension turns Spec Kit requirements and use-case inputs into a design artifact between specification and implementation. Its only goal is to help teams produce the right design artifact for the selected fidelity: product flows, page/state structure, layout assumptions, UI states, interaction details, handoff notes, and delivery-relevant design gaps before production code is planned or built. -Commands act as execution orchestrators: they resolve the active feature, load Spec Kit artifacts, apply evidence policy, and fill fixed templates under `templates/preview/`. The mid-fidelity commands can also adapt structured intake IR into the preview-owned `schemas/preview/mid-ir-adapter.schema.json` contract when enough source-backed structure is available. The templates are the source of truth for output sections, table schemas, HTML shells, and preserved-review slots. Structural validation is driven by `schemas/preview/contract.json`, validated against `schemas/preview/contract.schema.json`. +The command acts as an execution orchestrator: it resolves the active feature, loads `spec.md`, `uc.md`, and supporting Spec Kit artifacts, applies input-to-design synthesis policy, and fills the fixed HTML template under `templates/preview/`. Evidence and coverage labels support output quality; they are not separate deliverables. The template is the source of truth for output sections, table schemas, HTML shell, and preserved design-note slots. Structural validation is driven by `schemas/preview/contract.json`, validated against `schemas/preview/contract.schema.json`. -Generated HTML previews are intentionally standalone: +Generated previews are intentionally standalone: - one HTML file - inline CSS -- JavaScript only where the selected fidelity allows it +- JavaScript only for documented interactions and template controls - no network dependencies - no build step - no production source changes -Markdown previews are evidence-backed wireflows with requirement coverage, unknowns, and review questions. - -## Commands +## Command | Command | Description | |---------|-------------| -| `speckit.preview.low-md` | Generate `specs//preview/wireflow-low.md` | -| `speckit.preview.low-html` | Generate `specs//preview/wireflow-low.html` | -| `speckit.preview.mid-md` | Generate `specs//preview/wireflow-mid.md` | -| `speckit.preview.mid-html` | Generate `specs//preview/wireflow-mid.html` | -| `speckit.preview.high-md` | Generate `specs//preview/wireflow-high.md` | -| `speckit.preview.high-html` | Generate `specs//preview/wireflow-high.html` | +| `speckit.preview.wireflow` | Generate `specs//preview/wireflow.html`; first argument must be `low`, `mid`, or `high` | ## Usage ```text -/speckit.preview.low-md -/speckit.preview.mid-html -/speckit.preview.high-html +/speckit.preview.wireflow low +/speckit.preview.wireflow mid admin dashboard empty and error states +/speckit.preview.wireflow high checkout confirmation flow, desktop first ``` -Optional focus examples: +The first argument is mandatory: -```text -/speckit.preview.low-md onboarding happy path -/speckit.preview.low-html onboarding happy path -/speckit.preview.mid-md admin dashboard empty and error states -/speckit.preview.mid-html admin dashboard empty and error states -/speckit.preview.high-md checkout review flow, desktop first -/speckit.preview.high-html checkout review flow, desktop first -``` +- `low`: low-fidelity design artifact with actor intent, core journey, major nodes, branch points, and delivery-relevant gaps. +- `mid`: mid-fidelity design artifact with source-defined pages, fields, controls, layout relationships, state inventory, and delivery-relevant gaps. +- `high`: high-fidelity design artifact with documented interactions, observable state transitions, validation feedback, permissions, responsive states, and delivery-relevant gaps. + +Any text after the fidelity parameter is treated as optional design focus. Focus changes ordering and emphasis, but it must not hide `spec.md` or `uc.md` flows, constraints, states, or gaps that affect delivery quality. + +## Fidelity Outputs + +- `low` must include a core journey map, actor intent and trigger, abstract node list, major branch points, outcome summary, delivery-relevant gaps, and unresolved design questions. +- `mid` must include a screen or node inventory, layout regions, visible controls, source-defined fields, representative empty/loading/success/error states, branch handling, delivery-relevant gaps, and unresolved design questions. +- `high` must include a primary interactive surface, documented control behavior, interaction matrix, state transition matrix, validation and permission feedback, responsive mobile and desktop notes, delivery-relevant gaps, and unresolved design questions. ## Inputs The command reads the active feature under `specs//`: - `spec.md` (required) +- `uc.md` (required) - `plan.md` (optional) - `research.md` (optional) - `data-model.md` (optional) - `contracts/` (optional) - `quickstart.md` (optional) -For mid-fidelity previews, the command also looks for optional structured intake artifacts: +For `mid` fidelity, the command can also use optional structured intake artifacts as supporting evidence: - `intake/**/structured-ir.yaml` - `intake/**/ir-assertions.yaml` - `intake/**/ir-evidence-packet.md` -These files are not required. When they can be mapped to `schemas/preview/mid-ir-adapter.schema.json`, the preview uses the mapped pages, regions, fields, controls, states, relations, assertions, and provenance as IR-backed evidence. When they are missing or cannot be mapped, preview generation falls back to the existing feature artifacts and records the limitation as an evidence gap. +These files are not required. When they can be mapped to `schemas/preview/mid-ir-adapter.schema.json`, the design artifact can use the mapped pages, regions, fields, controls, states, relations, assertions, and provenance as source-grounded design inputs. When they are missing or cannot be mapped, design synthesis continues from `spec.md`, `uc.md`, and other supporting feature artifacts, and the limitation is recorded as a design question or delivery quality issue. It also reads `.specify/memory/constitution.md` when present. ## Output ```text -specs//preview/wireflow-low.md -specs//preview/wireflow-low.html -specs//preview/wireflow-mid.md -specs//preview/wireflow-mid.html -specs//preview/wireflow-high.md -specs//preview/wireflow-high.html +specs//preview/wireflow.html ``` -HTML files can be opened directly in a browser. +The HTML file can be opened directly in a browser. + +## Input-To-Design Synthesis + +The command must run an Input-to-Design Synthesis Pass before composing the design artifact. This pass exists to improve the completeness, usefulness, and handoff quality of the delivered HTML design artifact: -## Fidelity +- `spec.md` inputs: user stories, acceptance scenarios, functional requirements, edge cases, constraints, success criteria, entities, data conditions, permissions, validation rules, and user-visible system responses must be considered and represented in the delivered design through screens, states, interactions, quality conclusions, or design questions. +- `uc.md` inputs: use cases, actors, triggers, preconditions, main flows, alternate flows, exception flows, postconditions, business rules, data conditions, error conditions, and feedback requirements must be considered and represented in the delivered design through flows, states, interactions, quality conclusions, or design questions. +- If `uc.md` is missing, the command stops before writing output because use-case input is required for high-quality design synthesis. -- Low fidelity: early feasibility review, abstract nodes, core path, branch points, and major missing scope. -- Mid fidelity: product, UX, and engineering review with source-defined labels, optional structured IR adaptation, page/state inventory, basic layout relationships, relation checks, assertions, and state coverage. -- High fidelity: final confirmation with interaction matrix, state matrix, validation feedback, permissions, responsive states, and clickable HTML simulation in the `.html` command. +Supporting files such as `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, structured intake artifacts, and `.specify/memory/constitution.md` may refine the design artifact, but they do not override `spec.md` or `uc.md`. Conflicts become design questions or delivery quality issues. ## Boundaries -This extension does not modify app source code, tests, build files, specs, plans, or tasks. Previews are not production implementation and should not replace `/speckit.plan`, `/speckit.tasks`, or `/speckit.implement`. +This extension does not modify app source code, tests, build files, specs, plans, or tasks. The preview is not production implementation and should not replace `/speckit.plan`, `/speckit.tasks`, or `/speckit.implement`. ## Installation -Install from the v1.2.0 release ZIP: +Install from the v1.3.0 release ZIP: ```bash -specify extension add preview --from https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.2.0.zip +specify extension add preview --from https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.3.0.zip ``` For local development from this repository root: @@ -112,8 +108,7 @@ specify extension add --dev . When the command runs in a Spec Kit project, it writes only: ```text -specs//preview/wireflow-*.md -specs//preview/wireflow-*.html +specs//preview/wireflow.html ``` Installing the extension copies this repository into: @@ -122,20 +117,15 @@ Installing the extension copies this repository into: .specify/extensions/preview/ ``` -## Template Sources +## Template Source -Command prompts load one matching template per output: +Command prompts load one output template: ```text -templates/preview/low.md -templates/preview/low.html -templates/preview/mid.md -templates/preview/mid.html -templates/preview/high.md -templates/preview/high.html +templates/preview/wireflow.html ``` -The command layer owns context loading, evidence policy, and file-write boundaries. The template layer owns sections, required tables, HTML structure, and the preserved review records slot. +The command layer owns invocation, fidelity parameter validation, context loading, evidence policy, input-to-design synthesis, and file-write boundaries. The template layer owns sections, required tables, HTML structure, and the preserved design records slot. ## Validation Contract @@ -149,4 +139,4 @@ schemas/preview/mid-ir-adapter.schema.json `tests/validate-extension.py` validates the contract shape with a standard-library JSON Schema subset, then uses the contract to verify manifest command mappings, declared schema files, command/template files, required slots, forbidden legacy phrases, and documentation alignment. -`schemas/preview/mid-ir-adapter.schema.json` is a preview-owned ingest boundary for mid-fidelity rendering. It validates whether a mapped payload has enough source-backed pages, regions, fields, controls, states, relations, assertions, coverage labels, and provenance for an evidence-backed preview. It is not the authoritative schema for upstream `spec-kit-intake` IR. +`schemas/preview/mid-ir-adapter.schema.json` is a preview-owned ingest boundary for optional mid-fidelity structured intake. It validates whether a mapped payload has enough source-backed pages, regions, fields, controls, states, relations, assertions, coverage labels, and provenance to support the `mid` design artifact. It is not the authoritative schema for upstream `spec-kit-intake` IR. diff --git a/extensions/preview/commands/speckit.preview.high-html.md b/extensions/preview/commands/speckit.preview.high-html.md deleted file mode 100644 index 108806a8b5..0000000000 --- a/extensions/preview/commands/speckit.preview.high-html.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -description: Generate a high-fidelity evidence-backed interactive HTML preview from Spec Kit artifacts. ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** evaluate the user input before proceeding. Treat it as preview focus, audience, device, flow, interaction, or review criteria. - -If `$ARGUMENTS` requests a page, role, device, state, interaction, validation rule, permission, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only for the minimal traceable inference required to preserve preview coherence. - -## Goal - -Generate or update `specs//preview/wireflow-high.html`. - -High-fidelity HTML is an interactive review artifact for implementation handoff validation. It simulates documented interactions and observable state transitions without emitting production implementation code. - -## Command Responsibilities - -- Resolve the active feature and load source artifacts. -- Apply evidence policy and fidelity-specific extraction rules. -- Load the output template from `.specify/extensions/preview/templates/preview/high.html`; when running from this extension repository, use `templates/preview/high.html`. -- Populate template slots with evidence-backed content only. -- Write only `specs//preview/wireflow-high.html`. Create `specs//preview/` if it is missing; do not create any other files or directories. - -Do not redefine template sections, table columns, CSS shell, JavaScript hook names, or output structure in this command. The template is the source of truth for HTML shape and required tables. - -## Boundaries - -- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. -- Do not create Markdown, Figma files, images, screenshots, or production UI. -- Do not invent business rules, roles, fields, states, copy, data rules, or interactions. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. -- HTML output must be self-contained and network-free. Use inline CSS and JavaScript only to simulate documented interactions and state changes. -- If an interaction is not documented or minimally inferable from source evidence, show it as a review question instead of making it clickable. -- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. - -## Context Loading - -1. Verify the current directory is a Spec Kit project by checking for `.specify/`. -2. Identify the active feature: - - Prefer `SPECIFY_FEATURE` when set. - - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. - - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. - - Do not choose by most recent timestamp when multiple feature directories exist. - - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. -3. Read these files when present: - - `specs//spec.md` (required) - - `specs//plan.md` - - `specs//research.md` - - `specs//data-model.md` - - `specs//contracts/` - - `specs//quickstart.md` -4. Read `.specify/memory/constitution.md` if present. -5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. -6. If `specs//preview/wireflow-high.html` already exists, read it before writing. Preserve user-authored review notes, decisions, and unresolved questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. - -## Evidence Policy - -Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. - -Every requirement, screen, node, field, interaction, state, branch, permission, validation rule, and system response included in the preview must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. - -Coverage evidence must identify the source with a precise anchor: file path, heading, section id, line number, table row, or short quoted source excerpt. Use `输入未说明` when no source supports the requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. - -## High-Fidelity Extraction Policy - -Extract only: - -- Artifact-defined data conditions, roles, permissions, validation rules, and user-visible feedback. -- Interaction matrix content reflected in HTML behavior or visible documentation. -- State matrix content for hover, focus, click, loading, success, failure, disabled, empty, validation, timeout, retry, cancellation, and permission-denied states where relevant. -- Toast, inline error, confirmation dialog, retry, cancellation, timeout, and loading feedback rules when supported by evidence. -- Responsive mobile and desktop review states when the feature is user-facing; mark unsupported device assumptions as `推理补齐`. -- Motion or timing notes only when artifacts state them or when explicitly marked as `推理补齐`. -- Coverage evidence mapped from requirements to preview screens, interactions, states, or review questions. - -Do not claim that HTML is production-ready. Do not generate app components, production framework code, remote assets, analytics, or API calls. - -## Procedure - -1. Summarize the feature goal, personas, primary scenarios, and constraints from loaded artifacts. -2. Select the preview focus from `$ARGUMENTS`; if absent, cover the highest-priority user story and primary alternate flow state. -3. Extract evidence-backed pages, tasks, fields, controls, roles, permissions, data conditions, states, decisions, and system responses. -4. Fill the high-fidelity HTML template slots for metadata, initial screen, wireflow, node inventory, interaction matrix, state matrix, branches, coverage, preserved review records, and unresolved review questions. -5. Simulate only documented interactions. Label minimally inferred behavior as `推理补齐`, and record unsupported behavior as a review question instead of making it interactive. -6. Escape user-provided content and source excerpts before inserting them into HTML. -7. Write `specs//preview/wireflow-high.html`, preserving existing review content as described above. -8. Report output path, fidelity, input sources, flows covered, covered interactions, inferred assumptions, unsupported items, and unresolved review questions. diff --git a/extensions/preview/commands/speckit.preview.high-md.md b/extensions/preview/commands/speckit.preview.high-md.md deleted file mode 100644 index eba9b9ec84..0000000000 --- a/extensions/preview/commands/speckit.preview.high-md.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -description: Generate a high-fidelity evidence-backed Markdown interaction preview from Spec Kit artifacts. ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** evaluate the user input before proceeding. Treat it as preview focus, audience, device, flow, interaction, or review criteria. - -If `$ARGUMENTS` requests a page, role, device, state, interaction, validation rule, permission, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only for the minimal traceable inference required to preserve preview coherence. - -## Goal - -Generate or update `specs//preview/wireflow-high.md`. - -High-fidelity Markdown is a final product validation artifact for implementation handoff validation. It documents evidence-backed interaction feedback, state transitions, validation, permissions, and edge cases without emitting production implementation code. - -## Command Responsibilities - -- Resolve the active feature and load source artifacts. -- Apply evidence policy and fidelity-specific extraction rules. -- Load the output template from `.specify/extensions/preview/templates/preview/high.md`; when running from this extension repository, use `templates/preview/high.md`. -- Populate template slots with evidence-backed content only. -- Write only `specs//preview/wireflow-high.md`. Create `specs//preview/` if it is missing; do not create any other files or directories. - -Do not redefine template sections, table columns, or output structure in this command. The template is the source of truth for Markdown shape and required tables. - -## Boundaries - -- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. -- Do not create HTML, Figma files, images, screenshots, or production UI. -- Do not invent business rules, roles, fields, states, copy, data rules, or interactions. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. -- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. - -## Context Loading - -1. Verify the current directory is a Spec Kit project by checking for `.specify/`. -2. Identify the active feature: - - Prefer `SPECIFY_FEATURE` when set. - - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. - - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. - - Do not choose by most recent timestamp when multiple feature directories exist. - - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. -3. Read these files when present: - - `specs//spec.md` (required) - - `specs//plan.md` - - `specs//research.md` - - `specs//data-model.md` - - `specs//contracts/` - - `specs//quickstart.md` -4. Read `.specify/memory/constitution.md` if present. -5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. -6. If `specs//preview/wireflow-high.md` already exists, read it before writing. Preserve user-authored review notes, decisions, and unresolved questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. - -## Evidence Policy - -Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. - -Every requirement, page, node, field, interaction, state, branch, permission, validation rule, and system response included in the preview must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. - -Coverage evidence must identify the source with a precise anchor: file path, heading, section id, line number, table row, or short quoted source excerpt. Use `输入未说明` when no source supports the requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. - -## High-Fidelity Extraction Policy - -Extract only: - -- Artifact-defined data conditions, roles, permissions, validation rules, and user-visible feedback. -- Interaction matrix content: event, target, precondition, feedback, state change, error handling, coverage, and evidence. -- State matrix content for hover, focus, click, loading, success, failure, disabled, empty, validation, timeout, retry, cancellation, and permission-denied states where relevant. -- Toast, inline error, confirmation dialog, retry, cancellation, timeout, and loading feedback rules when supported by evidence. -- Motion or timing notes only when artifacts state them or when explicitly marked as `推理补齐`. -- Coverage evidence mapped from requirements to preview nodes, interactions, states, or review questions. - -Do not claim that Markdown is a clickable prototype or production-ready. - -## Procedure - -1. Summarize the feature goal, personas, primary scenarios, and constraints from loaded artifacts. -2. Select the preview focus from `$ARGUMENTS`; if absent, cover the highest-priority user story and primary alternate flow state. -3. Extract evidence-backed pages, tasks, fields, controls, roles, permissions, data conditions, states, decisions, and system responses. -4. Fill the high-fidelity Markdown template slots for metadata, evidence summary, wireflow, node inventory, interaction matrix, state matrix, branches, coverage, preserved review records, and unresolved review questions. -5. Write `specs//preview/wireflow-high.md`, preserving existing review content as described above. -6. Report output path, fidelity, input sources, flows covered, covered interactions, inferred assumptions, unsupported items, and unresolved review questions. diff --git a/extensions/preview/commands/speckit.preview.low-html.md b/extensions/preview/commands/speckit.preview.low-html.md deleted file mode 100644 index 66c26e55ac..0000000000 --- a/extensions/preview/commands/speckit.preview.low-html.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -description: Generate a low-fidelity evidence-backed static HTML wireflow preview from Spec Kit artifacts. ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** evaluate the user input before proceeding. Treat it as preview focus, audience, device, flow, or review criteria. - -If `$ARGUMENTS` requests a page, role, device, state, interaction, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only for the minimal traceable inference required to preserve preview coherence. - -## Goal - -Generate or update `specs//preview/wireflow-low.html`. - -Low-fidelity HTML is a static browser-renderable artifact for early product-scope validation. It presents the core path, branch points, missing scope, and review questions in HTML without adding interaction fidelity. - -## Command Responsibilities - -- Resolve the active feature and load source artifacts. -- Apply evidence policy and fidelity-specific extraction rules. -- Load the output template from `.specify/extensions/preview/templates/preview/low.html`; when running from this extension repository, use `templates/preview/low.html`. -- Populate template slots with evidence-backed content only. -- Write only `specs//preview/wireflow-low.html`. Create `specs//preview/` if it is missing; do not create any other files or directories. - -Do not redefine template sections, table columns, CSS shell, or output structure in this command. The template is the source of truth for HTML shape and required tables. - -## Boundaries - -- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. -- Do not create Markdown, Figma files, images, screenshots, or production UI. -- Do not invent pages, fields, business rules, roles, states, or visual details. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. -- HTML output must remain static, self-contained, and network-free. Use embedded CSS only; do not use external fonts, icons, images, scripts, analytics, APIs, or JavaScript interaction. -- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. - -## Context Loading - -1. Verify the current directory is a Spec Kit project by checking for `.specify/`. -2. Identify the active feature: - - Prefer `SPECIFY_FEATURE` when set. - - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. - - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. - - Do not choose by most recent timestamp when multiple feature directories exist. - - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. -3. Read these files when present: - - `specs//spec.md` (required) - - `specs//plan.md` - - `specs//research.md` - - `specs//data-model.md` - - `specs//contracts/` - - `specs//quickstart.md` -4. Read `.specify/memory/constitution.md` if present. -5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. -6. If `specs//preview/wireflow-low.html` already exists, read it before writing. Preserve user-authored review notes, decisions, and unresolved questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. - -## Evidence Policy - -Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. - -Every requirement, node, branch, state, and terminal outcome included in the preview must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. - -Coverage evidence must identify the source with a precise anchor: file path, heading, section id, line number, table row, or short quoted source excerpt. Use `输入未说明` when no source supports the requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. - -## Low-Fidelity Extraction Policy - -Extract only: - -- Core actor, trigger, goal, and terminal outcome. -- Primary path and major branch points. -- Abstract page or state nodes when screens are unnamed. -- Major alternate, error, empty, permission, cancellation, and retry paths only when source evidence supports them. -- Coverage conclusions for major user stories, acceptance criteria, and missing scope. - -Exclude precise layout, colors, component styling, animation, JavaScript interaction, and pixel-level details. - -## Procedure - -1. Summarize the feature goal, actors, primary scenarios, and constraints from loaded artifacts. -2. Select the preview focus from `$ARGUMENTS`; if absent, cover the highest-priority user story. -3. Extract evidence-backed actors, tasks, steps, decisions, states, and terminal outcomes. -4. Fill the low-fidelity HTML template slots for metadata, evidence summary, wireflow, node inventory, branches, coverage, preserved review records, and unresolved review questions. -5. Escape user-provided content and source excerpts before inserting them into HTML. -6. Write `specs//preview/wireflow-low.html`, preserving existing review content as described above. -7. Report output path, fidelity, input sources, flows covered, inferred assumptions, unsupported items, and unresolved review questions. diff --git a/extensions/preview/commands/speckit.preview.low-md.md b/extensions/preview/commands/speckit.preview.low-md.md deleted file mode 100644 index 49f1ff1d5f..0000000000 --- a/extensions/preview/commands/speckit.preview.low-md.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -description: Generate a low-fidelity evidence-backed Markdown wireflow preview from Spec Kit artifacts. ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** evaluate the user input before proceeding. Treat it as preview focus, audience, device, flow, or review criteria. - -If `$ARGUMENTS` requests a page, role, device, state, interaction, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only for the minimal traceable inference required to preserve preview coherence. - -## Goal - -Generate or update `specs//preview/wireflow-low.md`. - -Low fidelity is an early product-scope validation artifact. It captures the core actor, trigger, goal, primary path, branch points, terminal outcomes, missing scope, and review questions. - -## Command Responsibilities - -- Resolve the active feature and load source artifacts. -- Apply evidence policy and fidelity-specific extraction rules. -- Load the output template from `.specify/extensions/preview/templates/preview/low.md`; when running from this extension repository, use `templates/preview/low.md`. -- Populate template slots with evidence-backed content only. -- Write only `specs//preview/wireflow-low.md`. Create `specs//preview/` if it is missing; do not create any other files or directories. - -Do not redefine template sections, table columns, or output structure in this command. The template is the source of truth for Markdown shape and required tables. - -## Boundaries - -- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. -- Do not create HTML, Figma files, images, screenshots, or production UI. -- Do not invent pages, fields, business rules, roles, states, or visual details. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. -- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. - -## Context Loading - -1. Verify the current directory is a Spec Kit project by checking for `.specify/`. -2. Identify the active feature: - - Prefer `SPECIFY_FEATURE` when set. - - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. - - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. - - Do not choose by most recent timestamp when multiple feature directories exist. - - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. -3. Read these files when present: - - `specs//spec.md` (required) - - `specs//plan.md` - - `specs//research.md` - - `specs//data-model.md` - - `specs//contracts/` - - `specs//quickstart.md` -4. Read `.specify/memory/constitution.md` if present. -5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. -6. If `specs//preview/wireflow-low.md` already exists, read it before writing. Preserve user-authored review notes, decisions, and unresolved questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. - -## Evidence Policy - -Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. - -Every requirement, node, branch, state, and terminal outcome included in the preview must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. - -Coverage evidence must identify the source with a precise anchor: file path, heading, section id, line number, table row, or short quoted source excerpt. Use `输入未说明` when no source supports the requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. - -## Low-Fidelity Extraction Policy - -Extract only: - -- Core actor, trigger, goal, and terminal outcome. -- Primary path and major branch points. -- Abstract page or state nodes when screens are unnamed. -- Major alternate, error, empty, permission, cancellation, and retry paths only when source evidence supports them. -- Coverage conclusions for major user stories, acceptance criteria, and missing scope. - -Exclude precise layout, colors, component styling, animation, and pixel-level details. - -## Procedure - -1. Summarize the feature goal, actors, primary scenarios, and constraints from loaded artifacts. -2. Select the preview focus from `$ARGUMENTS`; if absent, cover the highest-priority user story. -3. Extract evidence-backed actors, tasks, steps, decisions, states, and terminal outcomes. -4. Fill the low-fidelity Markdown template slots for metadata, evidence summary, wireflow, node inventory, branches, coverage, preserved review records, and unresolved review questions. -5. Write `specs//preview/wireflow-low.md`, preserving existing review content as described above. -6. Report output path, fidelity, input sources, flows covered, inferred assumptions, unsupported items, and unresolved review questions. diff --git a/extensions/preview/commands/speckit.preview.mid-html.md b/extensions/preview/commands/speckit.preview.mid-html.md deleted file mode 100644 index 0382061b33..0000000000 --- a/extensions/preview/commands/speckit.preview.mid-html.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -description: Generate a mid-fidelity evidence-backed static HTML wireflow preview from Spec Kit artifacts. ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** evaluate the user input before proceeding. Treat it as preview focus, audience, device, flow, or review criteria. - -If `$ARGUMENTS` requests a page, role, device, state, interaction, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only for the minimal traceable inference required to preserve preview coherence. - -## Goal - -Generate or update `specs//preview/wireflow-mid.html`. - -Mid-fidelity HTML is a static browser-renderable artifact for baseline product, UX, and engineering review. It represents page structure, source-defined labels, basic layout relationships, states, and evidence-backed behavior without becoming production UI. - -## Command Responsibilities - -- Resolve the active feature and load source artifacts. -- Apply evidence policy and fidelity-specific extraction rules. -- Load the output template from `.specify/extensions/preview/templates/preview/mid.html`; when running from this extension repository, use `templates/preview/mid.html`. -- Populate template slots with evidence-backed content only. -- Write only `specs//preview/wireflow-mid.html`. Create `specs//preview/` if it is missing; do not create any other files or directories. - -Do not redefine template sections, table columns, CSS shell, JavaScript hook names, or output structure in this command. The template is the source of truth for HTML shape and required tables. - -## Boundaries - -- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. -- Do not create Markdown, Figma files, images, screenshots, or production UI. -- Do not invent business rules, roles, fields, states, visual details, or interactions. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. -- HTML output must remain static, self-contained, and network-free. Use embedded CSS and minimal JavaScript only for switching documented state examples or sections; do not create an end-to-end interactive prototype. -- Do not simulate undocumented navigation, persistence, APIs, or business logic. -- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. - -## Context Loading - -1. Verify the current directory is a Spec Kit project by checking for `.specify/`. -2. Identify the active feature: - - Prefer `SPECIFY_FEATURE` when set. - - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. - - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. - - Do not choose by most recent timestamp when multiple feature directories exist. - - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. -3. Read these files when present: - - `specs//spec.md` (required) - - `specs//plan.md` - - `specs//research.md` - - `specs//data-model.md` - - `specs//contracts/` - - `specs//quickstart.md` - - `specs//intake/**/structured-ir.yaml` - - `specs//intake/**/ir-assertions.yaml` - - `specs//intake/**/ir-evidence-packet.md` -4. Read `.specify/memory/constitution.md` if present. -5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. -6. If `specs//preview/wireflow-mid.html` already exists, read it before writing. Preserve user-authored review notes, decisions, and unresolved questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. - -## Evidence Policy - -Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. - -Every requirement, page, node, field, state, branch, and system response included in the preview must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. - -Coverage evidence must identify the source with a precise anchor: file path, heading, section id, line number, table row, or short quoted source excerpt. Use `输入未说明` when no source supports the requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. - -## Structured IR Adapter Input - -Use `schemas/preview/mid-ir-adapter.schema.json` as the preview-owned adapter contract for mid-fidelity structured input. This schema defines the minimum payload needed to render an evidence-backed mid preview; it is not the upstream `spec-kit-intake` structured IR authority and must not be treated as a copy of the upstream IR schema. - -When `specs//intake/**/structured-ir.yaml`, `specs//intake/**/ir-assertions.yaml`, or `specs//intake/**/ir-evidence-packet.md` are present, attempt to map source-backed `source_artifacts`, `pages`, `pages[].roles`, `pages[].viewports`, `regions`, `fields`, `controls`, `states`, `relations`, `assertions`, `evidence_gaps`, and `visual_enhancement_refs` into the adapter contract. Ignore upstream `contract_type`; do not use it as the preview validation target. Validate the mapped adapter payload against `schemas/preview/mid-ir-adapter.schema.json` before treating it as IR-backed preview input. Require only that the mapped payload contains enough adapter-compatible structure and provenance to support this preview. - -If the mapped payload passes adapter schema validation, prefer IR-backed pages, regions, fields, controls, states, relations, and assertions over looser extraction from prose artifacts. Each IR-backed item still requires a coverage label and provenance. If an item lacks `source_refs`, use it only when a minimal `推理补齐` explanation is available; otherwise mark it as `输入未说明` or record it as an evidence gap. - -If structured IR files are missing, unreadable, blocked, cannot be mapped, cannot be validated, or fail validation against `schemas/preview/mid-ir-adapter.schema.json`, do not fail solely for that reason. Continue from `spec.md`, `plan.md`, `contracts/`, and other available artifacts, then record the IR limitation as an evidence gap with one of these stable codes: `IR_MISSING`, `IR_UNMAPPABLE`, or `IR_PARTIAL`. - -Distinguish IR-backed structure from visual screenshot, HTML SSOT, design, or token enhancement refs. Visual enhancement refs may support layout review only; they do not create business rules, interactions, states, relations, assertions, coverage conclusions, or acceptance evidence by themselves. - -## Mid-Fidelity Extraction Policy - -Extract only: - -- Source-defined page, field, button, message, and role labels. -- Page/state sections and decision nodes. -- Node purpose, visible elements, user actions, system responses, states, and evidence anchors. -- IR-backed regions, controls, states, relation checks, and assertions when they satisfy `schemas/preview/mid-ir-adapter.schema.json`. -- Basic layout relationships such as header/sidebar/content/table/form/modal only when supported by artifacts or marked as `推理补齐`. -- Empty, loading, validation error, success, failure, disabled, and permission states when relevant and supported by evidence. -- Coverage evidence mapped from requirements to preview nodes, states, or review questions. - -Use non-branded wireframe styling. Do not invent brand visual design, icons, shadows, images, final typography, animation, or production component names. - -## Procedure - -1. Summarize the feature goal, personas, primary scenarios, and constraints from loaded artifacts. -2. Select the preview focus from `$ARGUMENTS`; if absent, cover the highest-priority user story and primary alternate flow state. -3. Map optional structured IR inputs into `schemas/preview/mid-ir-adapter.schema.json` and validate the mapped adapter payload against that schema; if mapping or validation fails or is partial, keep the failure non-blocking and record `IR_UNMAPPABLE` or `IR_PARTIAL` as the evidence gap. -4. Extract evidence-backed pages, tasks, fields, controls, states, decisions, relation checks, assertions, and system responses. -5. Fill the mid-fidelity HTML template slots for metadata, evidence summary, wireflow, node inventory, state inventory, branches, coverage, preserved review records, and unresolved review questions. -6. Escape user-provided content and source excerpts before inserting them into HTML. -7. Write `specs//preview/wireflow-mid.html`, preserving existing review content as described above. -8. Report output path, fidelity, input sources, structured IR mapping status, flows covered, inferred assumptions, unsupported items, evidence gap entries, and unresolved review questions. diff --git a/extensions/preview/commands/speckit.preview.mid-md.md b/extensions/preview/commands/speckit.preview.mid-md.md deleted file mode 100644 index 4e867c963b..0000000000 --- a/extensions/preview/commands/speckit.preview.mid-md.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -description: Generate a mid-fidelity evidence-backed Markdown wireflow preview from Spec Kit artifacts. ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** evaluate the user input before proceeding. Treat it as preview focus, audience, device, flow, or review criteria. - -If `$ARGUMENTS` requests a page, role, device, state, interaction, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only for the minimal traceable inference required to preserve preview coherence. - -## Goal - -Generate or update `specs//preview/wireflow-mid.md`. - -Mid fidelity is the baseline product, UX, and engineering review artifact. It represents page structure, source-defined labels, basic layout relationships, states, and evidence-backed behavior, excluding final visual design treatment. - -## Command Responsibilities - -- Resolve the active feature and load source artifacts. -- Apply evidence policy and fidelity-specific extraction rules. -- Load the output template from `.specify/extensions/preview/templates/preview/mid.md`; when running from this extension repository, use `templates/preview/mid.md`. -- Populate template slots with evidence-backed content only. -- Write only `specs//preview/wireflow-mid.md`. Create `specs//preview/` if it is missing; do not create any other files or directories. - -Do not redefine template sections, table columns, or output structure in this command. The template is the source of truth for Markdown shape and required tables. - -## Boundaries - -- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. -- Do not create HTML, Figma files, images, screenshots, or production UI. -- Do not invent business rules, roles, fields, states, visual details, or interactions. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. -- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. - -## Context Loading - -1. Verify the current directory is a Spec Kit project by checking for `.specify/`. -2. Identify the active feature: - - Prefer `SPECIFY_FEATURE` when set. - - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. - - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. - - Do not choose by most recent timestamp when multiple feature directories exist. - - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. -3. Read these files when present: - - `specs//spec.md` (required) - - `specs//plan.md` - - `specs//research.md` - - `specs//data-model.md` - - `specs//contracts/` - - `specs//quickstart.md` - - `specs//intake/**/structured-ir.yaml` - - `specs//intake/**/ir-assertions.yaml` - - `specs//intake/**/ir-evidence-packet.md` -4. Read `.specify/memory/constitution.md` if present. -5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. -6. If `specs//preview/wireflow-mid.md` already exists, read it before writing. Preserve user-authored review notes, decisions, and unresolved questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. - -## Evidence Policy - -Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. - -Every requirement, page, node, field, state, branch, and system response included in the preview must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. - -Coverage evidence must identify the source with a precise anchor: file path, heading, section id, line number, table row, or short quoted source excerpt. Use `输入未说明` when no source supports the requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. - -## Structured IR Adapter Input - -Use `schemas/preview/mid-ir-adapter.schema.json` as the preview-owned adapter contract for mid-fidelity structured input. This schema defines the minimum payload needed to render an evidence-backed mid preview; it is not the upstream `spec-kit-intake` structured IR authority and must not be treated as a copy of the upstream IR schema. - -When `specs//intake/**/structured-ir.yaml`, `specs//intake/**/ir-assertions.yaml`, or `specs//intake/**/ir-evidence-packet.md` are present, attempt to map source-backed `source_artifacts`, `pages`, `pages[].roles`, `pages[].viewports`, `regions`, `fields`, `controls`, `states`, `relations`, `assertions`, `evidence_gaps`, and `visual_enhancement_refs` into the adapter contract. Ignore upstream `contract_type`; do not use it as the preview validation target. Validate the mapped adapter payload against `schemas/preview/mid-ir-adapter.schema.json` before treating it as IR-backed preview input. Require only that the mapped payload contains enough adapter-compatible structure and provenance to support this preview. - -If the mapped payload passes adapter schema validation, prefer IR-backed pages, regions, fields, controls, states, relations, and assertions over looser extraction from prose artifacts. Each IR-backed item still requires a coverage label and provenance. If an item lacks `source_refs`, use it only when a minimal `推理补齐` explanation is available; otherwise mark it as `输入未说明` or record it as an evidence gap. - -If structured IR files are missing, unreadable, blocked, cannot be mapped, cannot be validated, or fail validation against `schemas/preview/mid-ir-adapter.schema.json`, do not fail solely for that reason. Continue from `spec.md`, `plan.md`, `contracts/`, and other available artifacts, then record the IR limitation as an evidence gap with one of these stable codes: `IR_MISSING`, `IR_UNMAPPABLE`, or `IR_PARTIAL`. - -Distinguish IR-backed structure from visual screenshot, HTML SSOT, design, or token enhancement refs. Visual enhancement refs may support layout review only; they do not create business rules, interactions, states, relations, assertions, coverage conclusions, or acceptance evidence by themselves. - -## Mid-Fidelity Extraction Policy - -Extract only: - -- Source-defined page, field, button, message, and role labels. -- Page/state nodes and decision nodes. -- Node purpose, visible elements, user actions, system responses, states, and evidence anchors. -- IR-backed regions, controls, states, relation checks, and assertions when they satisfy `schemas/preview/mid-ir-adapter.schema.json`. -- Basic layout relationships such as header/sidebar/content/table/form/modal only when supported by artifacts or marked as `推理补齐`. -- Empty, loading, validation error, success, failure, disabled, and permission states when relevant and supported by evidence. -- Coverage evidence mapped from requirements to preview nodes, states, or review questions. - -Use monochrome wireframe notation. Do not invent brand visual design, icons, shadows, images, final typography, animation, or production component names. - -## Procedure - -1. Summarize the feature goal, personas, primary scenarios, and constraints from loaded artifacts. -2. Select the preview focus from `$ARGUMENTS`; if absent, cover the highest-priority user story and primary alternate flow state. -3. Map optional structured IR inputs into `schemas/preview/mid-ir-adapter.schema.json` and validate the mapped adapter payload against that schema; if mapping or validation fails or is partial, keep the failure non-blocking and record `IR_UNMAPPABLE` or `IR_PARTIAL` as the evidence gap. -4. Extract evidence-backed pages, tasks, fields, controls, states, decisions, relation checks, assertions, and system responses. -5. Fill the mid-fidelity Markdown template slots for metadata, evidence summary, wireflow, node inventory, state inventory, branches, coverage, preserved review records, and unresolved review questions. -6. Write `specs//preview/wireflow-mid.md`, preserving existing review content as described above. -7. Report output path, fidelity, input sources, structured IR mapping status, flows covered, inferred assumptions, unsupported items, evidence gap entries, and unresolved review questions. diff --git a/extensions/preview/commands/speckit.preview.wireflow.md b/extensions/preview/commands/speckit.preview.wireflow.md new file mode 100644 index 0000000000..9c05e23a5b --- /dev/null +++ b/extensions/preview/commands/speckit.preview.wireflow.md @@ -0,0 +1,154 @@ +--- +description: Generate one fidelity-specific HTML design artifact from spec.md and uc.md inputs. First argument must be low, mid, or high. +--- + +## User Input + +```text +$ARGUMENTS +``` + +## Fidelity Parameter + +You **MUST** parse `$ARGUMENTS` before loading or writing preview output. + +The first token is required and must be exactly one of `low|mid|high`: + +- `low`: convert inputs into a low-fidelity design artifact with actor intent, core journey, major nodes, branch points, and delivery-relevant gaps. +- `mid`: convert inputs into a mid-fidelity design artifact with source-defined pages, fields, controls, layout relationships, state inventory, and delivery-relevant gaps. +- `high`: convert inputs into a high-fidelity design artifact with documented interactions, observable state transitions, validation feedback, permissions, responsive states, and delivery-relevant gaps. + +If the first token is missing or is not exactly `low`, `mid`, or `high`, stop and do not write output. Report this usage: + +```text +/speckit.preview.wireflow [design focus] +``` + +Treat all remaining tokens as optional design focus, audience, device, flow, interaction, or output constraint. If `$ARGUMENTS` requests a page, role, device, state, interaction, validation rule, permission, or business rule that is not supported by the loaded artifacts, do not invent it. Mark it as `输入未说明`, or use `推理补齐` only when a minimal traceable inference is required to preserve design artifact coherence. + +## Goal + +Generate or update `specs//preview/wireflow.html`. + +The only goal is to synthesize `spec.md`, `uc.md`, and supporting feature inputs into a high-quality self-contained HTML design artifact that matches the required fidelity parameter. Evidence, provenance, and coverage conclusions are quality controls for the design artifact; they are not separate deliverables. + +## Command Responsibilities + +- Resolve the active feature and load source artifacts. +- Validate the required fidelity parameter before writing output. +- Apply evidence policy, Input-to-Design Synthesis Pass, and fidelity-specific Design Artifact Policy. +- Load the output template from `.specify/extensions/preview/templates/preview/wireflow.html`; when running from this extension repository, use `templates/preview/wireflow.html`. +- Populate template slots with source-grounded design content only. +- Write only `specs//preview/wireflow.html`. Create `specs//preview/` if it is missing; do not create any other files or directories. + +Do not redefine template sections, table columns, CSS shell, JavaScript hook names, or output structure in this command. The template is the source of truth for HTML shape and required tables. + +## Boundaries + +- Do not modify source code, tests, app assets, package manifests, build configuration, feature specs, plans, tasks, or memory files. +- Do not create Markdown, Figma files, images, screenshots, or production UI. +- Do not invent business rules, roles, fields, states, copy, data rules, or interactions. Mark unsupported items as `输入未说明`; mark only minimal traceable inferences as `推理补齐`. +- HTML output must be self-contained and network-free. Use embedded CSS only and inline JavaScript only for documented interactions, fidelity gating, disclosure controls, and state changes. +- If an interaction is not documented or minimally inferable from source evidence, record it as an open design question instead of making it clickable. +- Do not claim that HTML is production-ready. +- If the template file cannot be read, stop with an error explaining that the preview extension template is missing. + +## Context Loading + +1. Verify the current directory is a Spec Kit project by checking for `.specify/`. +2. Identify the active feature: + - Prefer `SPECIFY_FEATURE` when set. + - Otherwise use the current Git branch name when it exactly matches a directory under `specs/`. + - Otherwise inspect `specs/` and use it only when there is exactly one unambiguous candidate directory. + - Do not choose by most recent timestamp when multiple feature directories exist. + - If the feature cannot be identified, stop and ask the user to set `SPECIFY_FEATURE` or run from the feature branch. +3. Read these files: + - `specs//spec.md` (required) + - `specs//uc.md` (required) + - `specs//plan.md` (supporting, when present) + - `specs//research.md` (supporting, when present) + - `specs//data-model.md` (supporting, when present) + - `specs//contracts/` (supporting, when present) + - `specs//quickstart.md` (supporting, when present) + - `intake/**/structured-ir.yaml` (supporting for `mid`, when present) + - `intake/**/ir-assertions.yaml` (supporting for `mid`, when present) + - `intake/**/ir-evidence-packet.md` (supporting for `mid`, when present) +4. Read `.specify/memory/constitution.md` if present. +5. If `spec.md` is missing, stop with an error explaining that `/speckit.specify` must run first. +6. If `uc.md` is missing, stop with an error explaining that this preview command requires use-case input before design synthesis. +7. If `specs//preview/wireflow.html` already exists, read it before writing. Preserve user-authored design notes, decisions, and unresolved design questions when they remain consistent with current source artifacts; label changed items as `UPDATED` and superseded items as `SUPERSEDED`. + +## Source Priority + +Use `spec.md` and `uc.md` as the primary design inputs. + +Supporting files may refine design synthesis only in these ways: + +- `plan.md`: architecture context, platform constraints, and implementation boundaries that affect design feasibility. +- `research.md`: source-backed product, user, accessibility, or technical decisions that affect design choices. +- `data-model.md`: entity names, fields, states, relationships, and lifecycle constraints. +- `contracts/`: request/response fields, error states, validation rules, and permission boundaries. +- `quickstart.md`: user-visible setup, workflow, or operational assumptions. +- `intake/**/structured-ir.yaml`, `intake/**/ir-assertions.yaml`, and `intake/**/ir-evidence-packet.md`: optional `mid` fidelity support when they can be mapped to `schemas/preview/mid-ir-adapter.schema.json`. +- `.specify/memory/constitution.md`: project principles that constrain design output. + +When a supporting file conflicts with `spec.md` or `uc.md`, do not let it override the primary inputs. Record the conflict as a design question or delivery quality issue. + +## Evidence Policy + +Use these coverage labels exactly: `已覆盖`, `部分覆盖`, `未覆盖`, `输入未说明`, `推理补齐`. + +Use evidence to keep the design artifact grounded in the loaded inputs. Evidence and coverage labels support design quality, gap visibility, and handoff confidence; they must not become the primary output. + +Every requirement, use case, acceptance scenario, screen, node, field, interaction, state, branch, permission, validation rule, and system response included in the generated artifact must include a coverage label and provenance. Provenance must be either a source anchor or a `推理补齐` explanation. + +Use `输入未说明` when no source supports a requested item. Use `推理补齐` only when a minimal inference connects two supported facts; include the reasoning bridge and keep it non-authoritative. + +## Input-to-Design Synthesis Pass + +Before composing the design artifact, translate the loaded inputs into design decisions for the selected fidelity. The pass exists to improve the completeness, usefulness, and handoff quality of the HTML design artifact. The optional design focus changes ordering, emphasis, and first-screen selection only; it must not hide source-backed flows, constraints, states, or gaps that affect design delivery quality. + +### spec.md Design Inputs + +Extract every source-backed item from `specs//spec.md` when present: + +- feature goal, scope, user roles, and constraints +- every user story, priority, persona, and independent test +- every acceptance scenario, Given/When/Then block, edge case, and exception path +- every functional requirement, data requirement, validation rule, permission, and user-visible system response +- every non-functional requirement, success criterion, platform/device constraint, accessibility constraint, localization constraint, and compliance note +- every source-defined entity, field, relationship, status, lifecycle state, and external dependency + +Each extracted item must be considered during design composition. Group related items when they map to the same screen, state, interaction, or design decision, but do not silently drop unsupported, conflicting, or delivery-relevant items. Surface those items in `spec.md` design input mapping, the delivery quality conclusion, a design node/control/state, or a design question. + +### uc.md Design Inputs + +Extract every source-backed item from `specs//uc.md` when present: + +- every use case ID, use case name, actor, supporting actor, trigger, and goal +- every precondition, postcondition, main success flow step, alternate flow, exception flow, cancellation path, and retry path +- every business rule, permission rule, validation rule, data condition, error condition, and user-visible feedback requirement +- every included or extended use case relationship + +Each extracted item must be considered during design composition. Group related items when they map to the same flow, branch, state, interaction, or design decision, but do not silently drop unsupported, conflicting, or delivery-relevant items. Surface those items in `uc.md` design input mapping, the delivery quality conclusion, a design node/control/state, or a design question. + +## Design Artifact Policy + +Apply this policy after the Input-to-Design Synthesis Pass: + +- `low` MUST include: a core journey map, actor intent and trigger, abstract node list, major branch points, outcome summary, delivery-relevant gaps, and unresolved design questions. Do not add source-undefined page chrome, fields, visual styling, or interactions. +- `mid` MUST include: screen or node inventory, layout regions, visible controls, source-defined fields, representative empty/loading/success/error states, branch handling, delivery-relevant gaps, and unresolved design questions. Only include labels, fields, buttons, and states supported by source evidence or marked as `推理补齐`. +- `high` MUST include: primary interactive surface, documented control behavior, interaction matrix, state transition matrix, validation and permission feedback, responsive mobile and desktop notes, delivery-relevant gaps, and unresolved design questions. Simulate only documented interactions. + +For all fidelity levels, preserve unsupported requested focus items as design questions instead of omitting them. + +## Procedure + +1. Parse the required fidelity parameter and optional design focus from `$ARGUMENTS`. +2. Summarize the feature goal, personas, use cases, primary scenarios, constraints, and source availability from loaded artifacts. +3. Run the Input-to-Design Synthesis Pass for `spec.md` and `uc.md`. +4. Extract source-grounded pages, tasks, fields, controls, roles, permissions, data conditions, states, decisions, and system responses according to the selected fidelity. +5. Fill the HTML template slots for metadata, fidelity, input sources, evidence summary, design surface, wireflow, node inventory, interaction matrix, state matrix, branch handling, `spec.md` design input mapping, `uc.md` design input mapping, delivery quality conclusion, preserved design records, and unresolved design questions. +6. Escape user-provided content and source excerpts before inserting them into HTML. +7. Write `specs//preview/wireflow.html`, preserving existing design content as described above. +8. Report output path, fidelity, input sources, design synthesis summary for `spec.md` and `uc.md`, flows represented, interactions represented, inferred assumptions, unsupported items, and unresolved design questions. diff --git a/extensions/preview/extension.yml b/extensions/preview/extension.yml index fc78f05792..509de93811 100644 --- a/extensions/preview/extension.yml +++ b/extensions/preview/extension.yml @@ -3,8 +3,8 @@ schema_version: "1.0" extension: id: preview name: "Spec Kit Preview" - version: "1.2.0" - description: "Generate evidence-backed low, mid, or high fidelity previews from Spec Kit artifacts as Markdown or self-contained HTML" + version: "1.3.0" + description: "Generate one fidelity-specific HTML design artifact from spec.md and uc.md inputs with required low, mid, or high fidelity" author: bigsmartben repository: https://github.com/bigsmartben/spec-kit-preview homepage: https://github.com/bigsmartben/spec-kit-preview @@ -15,30 +15,13 @@ requires: provides: commands: - - name: speckit.preview.low-md - file: commands/speckit.preview.low-md.md - description: "Generate a low-fidelity evidence-backed Markdown wireflow preview" - - name: speckit.preview.low-html - file: commands/speckit.preview.low-html.md - description: "Generate a low-fidelity evidence-backed static HTML wireflow preview" - - name: speckit.preview.mid-md - file: commands/speckit.preview.mid-md.md - description: "Generate a mid-fidelity evidence-backed Markdown wireflow preview with optional structured IR adaptation" - - name: speckit.preview.mid-html - file: commands/speckit.preview.mid-html.md - description: "Generate a mid-fidelity evidence-backed static HTML wireflow preview with optional structured IR adaptation" - - name: speckit.preview.high-md - file: commands/speckit.preview.high-md.md - description: "Generate a high-fidelity evidence-backed Markdown interaction preview" - - name: speckit.preview.high-html - file: commands/speckit.preview.high-html.md - description: "Generate a high-fidelity evidence-backed interactive HTML preview" + - name: speckit.preview.wireflow + file: commands/speckit.preview.wireflow.md + description: "Generate a single fidelity-specific HTML design artifact; first argument must be low, mid, or high" tags: - "preview" - "prototype" - "html" - - "markdown" - "wireflow" - "ux" - diff --git a/extensions/preview/schemas/preview/contract.json b/extensions/preview/schemas/preview/contract.json index ff87b0a245..bdc13c9e58 100644 --- a/extensions/preview/schemas/preview/contract.json +++ b/extensions/preview/schemas/preview/contract.json @@ -2,7 +2,7 @@ "schemaVersion": "1.0.0", "extension": { "id": "preview", - "version": "1.2.0", + "version": "1.3.0", "repository": "https://github.com/bigsmartben/spec-kit-preview" }, "schemas": [ @@ -40,160 +40,40 @@ ], "commands": [ { - "name": "speckit.preview.low-md", - "file": "commands/speckit.preview.low-md.md", - "target": "specs//preview/wireflow-low.md", - "format": "md", - "fidelity": "low", - "template": "templates/preview/low.md", - "requiredPhrases": [ - "Low-Fidelity Extraction Policy", - "Core actor, trigger", - "Do not create HTML" - ], - "forbiddenPhrases": [ - "Do not create Markdown" - ] - }, - { - "name": "speckit.preview.low-html", - "file": "commands/speckit.preview.low-html.md", - "target": "specs//preview/wireflow-low.html", + "name": "speckit.preview.wireflow", + "file": "commands/speckit.preview.wireflow.md", + "target": "specs//preview/wireflow.html", "format": "html", - "fidelity": "low", - "template": "templates/preview/low.html", + "fidelityParameter": "required", + "template": "templates/preview/wireflow.html", "requiredPhrases": [ - "Low-Fidelity Extraction Policy", - "Core actor, trigger", + "Fidelity Parameter", + "low|mid|high", + "Input-to-Design Synthesis Pass", + "spec.md Design Inputs", + "uc.md Design Inputs", "Do not create Markdown", "self-contained", "network-free", "Escape user-provided content and source excerpts", "Use embedded CSS only", - "do not use external fonts" - ], - "forbiddenPhrases": [ - "Do not create HTML" - ] - }, - { - "name": "speckit.preview.mid-md", - "file": "commands/speckit.preview.mid-md.md", - "target": "specs//preview/wireflow-mid.md", - "format": "md", - "fidelity": "mid", - "template": "templates/preview/mid.md", - "requiredPhrases": [ - "Mid-Fidelity Extraction Policy", - "Structured IR Adapter Input", - "schemas/preview/mid-ir-adapter.schema.json", - "structured-ir.yaml", - "ir-assertions.yaml", - "ir-evidence-packet.md", - "evidence gap", - "Validate the mapped adapter payload against", - "passes adapter schema validation", - "cannot be validated", - "IR_MISSING", - "IR_UNMAPPABLE", - "IR_PARTIAL", - "Source-defined page, field, button", - "primary alternate flow state", - "Do not create HTML" - ], - "forbiddenPhrases": [ - "Do not create Markdown" - ] - }, - { - "name": "speckit.preview.mid-html", - "file": "commands/speckit.preview.mid-html.md", - "target": "specs//preview/wireflow-mid.html", - "format": "html", - "fidelity": "mid", - "template": "templates/preview/mid.html", - "requiredPhrases": [ - "Mid-Fidelity Extraction Policy", - "Structured IR Adapter Input", - "schemas/preview/mid-ir-adapter.schema.json", - "structured-ir.yaml", - "ir-assertions.yaml", - "ir-evidence-packet.md", - "evidence gap", - "Validate the mapped adapter payload against", - "passes adapter schema validation", - "cannot be validated", - "IR_MISSING", - "IR_UNMAPPABLE", - "IR_PARTIAL", - "Source-defined page, field, button", - "primary alternate flow state", - "Do not create Markdown", - "self-contained", - "network-free", - "Escape user-provided content and source excerpts", - "minimal JavaScript", - "do not create an end-to-end interactive prototype", - "Do not simulate undocumented navigation" - ], - "forbiddenPhrases": [ - "Do not create HTML" - ] - }, - { - "name": "speckit.preview.high-md", - "file": "commands/speckit.preview.high-md.md", - "target": "specs//preview/wireflow-high.md", - "format": "md", - "fidelity": "high", - "template": "templates/preview/high.md", - "requiredPhrases": [ - "High-Fidelity Extraction Policy", - "Interaction matrix content", - "State matrix content", - "covered interactions", - "primary alternate flow state", - "Do not create HTML" - ], - "forbiddenPhrases": [ - "Do not create Markdown" - ] - }, - { - "name": "speckit.preview.high-html", - "file": "commands/speckit.preview.high-html.md", - "target": "specs//preview/wireflow-high.html", - "format": "html", - "fidelity": "high", - "template": "templates/preview/high.html", - "requiredPhrases": [ - "High-Fidelity Extraction Policy", - "Interaction matrix content", - "State matrix content", - "covered interactions", - "primary alternate flow state", - "Do not create Markdown", - "self-contained", - "network-free", - "Escape user-provided content and source excerpts", - "inline CSS and JavaScript", "documented interactions", - "source evidence", - "review question instead of making it clickable", - "observable state transitions", - "Responsive mobile and desktop review states", + "open design question instead of making it clickable", "Do not claim that HTML is production-ready" ], "forbiddenPhrases": [ - "Do not create HTML" + "wireflow-low", + "wireflow-mid", + "wireflow-high" ] } ], "sharedCommandRequiredPhrases": [ "Command Responsibilities", "Evidence Policy", - "Extraction Policy", + "Design Artifact Policy", "specs//spec.md", + "specs//uc.md", "Do not modify source code", "推理补齐", "已覆盖", @@ -211,7 +91,8 @@ "source of truth", "template slots", "already exists, read it before writing", - "Preserve user-authored review notes", + "Preserve user-authored design notes", + "Source Priority", "UPDATED", "SUPERSEDED", "Prefer `SPECIFY_FEATURE` when set.", @@ -235,76 +116,29 @@ ], "templates": [ { - "path": "templates/preview/low.md", - "format": "md", - "requiredPhrases": [ - "# Low-Fidelity Preview", - "## 已保留评审记录", - "| ID | 节点 | 目的 | 用户动作 | 系统响应 | 覆盖标签 | 证据/推理 |", - "| 需求/场景 | 预览位置 | 覆盖标签 | 证据/推理 | 缺口或问题 |", - "{{preserved_review_records}}" - ] - }, - { - "path": "templates/preview/mid.md", - "format": "md", - "requiredPhrases": [ - "# Mid-Fidelity Preview", - "## 状态清单", - "## 已保留评审记录", - "| ID | 页面/节点 | 目的 | 可见元素 | 用户动作 | 系统响应 | 状态 | 覆盖标签 | 证据/推理 |", - "| 状态 | 触发条件 | 用户可见反馈 | 恢复/下一步 | 覆盖标签 | 证据/推理 |" - ] - }, - { - "path": "templates/preview/high.md", - "format": "md", - "requiredPhrases": [ - "# High-Fidelity Preview", - "## 交互矩阵", - "## 状态矩阵", - "## 已保留评审记录", - "| 事件 | 目标 | 前置条件 | 反馈 | 状态变化 | 错误处理 | 覆盖标签 | 证据/推理 |", - "| 状态 | 触发条件 | 用户可见反馈 | 恢复/下一步 | 覆盖标签 | 证据/推理 |" - ] - }, - { - "path": "templates/preview/low.html", - "format": "html", - "requiredPhrases": [ - "", - "Low-Fidelity Preview", - "已保留评审记录", - "{{node_inventory_rows}}", - "{{coverage_rows}}", - " - - -
-
-

Low-Fidelity Preview

-
- {{metadata}} -
-
- -
-

输入来源与读取范围

- {{input_sources}} -
- -
-

需求证据摘要

- {{evidence_summary}} -
- -
-

Wireflow

-
{{wireflow}}
-
- -
-

页面/节点清单

- - - - - - - - - - - - - - {{node_inventory_rows}} - -
ID节点目的用户动作系统响应覆盖标签证据/推理
-
- -
-

分支、状态与异常路径

- {{branches_states_exceptions}} -
- -
-

覆盖度证据结论

- - - - - - - - - - - - {{coverage_rows}} - -
需求/场景预览位置覆盖标签证据/推理缺口或问题
-
- -
-

已保留评审记录

- {{preserved_review_records}} -
- -
-

未覆盖项、未知项与评审问题

- {{review_questions}} -
-
- - diff --git a/extensions/preview/templates/preview/low.md b/extensions/preview/templates/preview/low.md deleted file mode 100644 index a872c04fdb..0000000000 --- a/extensions/preview/templates/preview/low.md +++ /dev/null @@ -1,41 +0,0 @@ -# Low-Fidelity Preview - -## 保真级别与评审场景 - -{{metadata}} - -## 输入来源与读取范围 - -{{input_sources}} - -## 需求证据摘要 - -{{evidence_summary}} - -## Wireflow - -{{wireflow}} - -## 页面/节点清单 - -| ID | 节点 | 目的 | 用户动作 | 系统响应 | 覆盖标签 | 证据/推理 | -|----|------|------|----------|----------|----------|-----------| -{{node_inventory_rows}} - -## 分支、状态与异常路径 - -{{branches_states_exceptions}} - -## 覆盖度证据结论 - -| 需求/场景 | 预览位置 | 覆盖标签 | 证据/推理 | 缺口或问题 | -|-----------|----------|----------|-----------|------------| -{{coverage_rows}} - -## 已保留评审记录 - -{{preserved_review_records}} - -## 未覆盖项、未知项与评审问题 - -{{review_questions}} diff --git a/extensions/preview/templates/preview/mid.html b/extensions/preview/templates/preview/mid.html deleted file mode 100644 index fba64ec668..0000000000 --- a/extensions/preview/templates/preview/mid.html +++ /dev/null @@ -1,191 +0,0 @@ - - - - - - Mid-Fidelity Preview - - - -
-
-

Mid-Fidelity Preview

-
{{metadata}}
-
- -
-

输入来源与读取范围

- {{input_sources}} -
- -
-

需求证据摘要

- {{evidence_summary}} -
- -
-

Wireflow

-
{{wireflow}}
-
- -
-

页面/节点清单

- - - - - - - - - - - - - - - {{node_inventory_rows}} -
ID页面/节点目的可见元素用户动作系统响应状态覆盖标签证据/推理
-
- -
-

状态清单

- -
- {{state_examples}} -
- - - - - - - - - - - - {{state_inventory_rows}} -
状态触发条件用户可见反馈恢复/下一步覆盖标签证据/推理
-
- -
-

分支、状态与异常路径

- {{branches_states_exceptions}} -
- -
-

覆盖度证据结论

- - - - - - - - - - - {{coverage_rows}} -
需求/场景预览位置覆盖标签证据/推理缺口或问题
-
- -
-

已保留评审记录

- {{preserved_review_records}} -
- -
-

未覆盖项、未知项与评审问题

- {{review_questions}} -
-
- - - diff --git a/extensions/preview/templates/preview/mid.md b/extensions/preview/templates/preview/mid.md deleted file mode 100644 index b880ed5cd9..0000000000 --- a/extensions/preview/templates/preview/mid.md +++ /dev/null @@ -1,47 +0,0 @@ -# Mid-Fidelity Preview - -## 保真级别与评审场景 - -{{metadata}} - -## 输入来源与读取范围 - -{{input_sources}} - -## 需求证据摘要 - -{{evidence_summary}} - -## Wireflow - -{{wireflow}} - -## 页面/节点清单 - -| ID | 页面/节点 | 目的 | 可见元素 | 用户动作 | 系统响应 | 状态 | 覆盖标签 | 证据/推理 | -|----|-----------|------|----------|----------|----------|------|----------|-----------| -{{node_inventory_rows}} - -## 状态清单 - -| 状态 | 触发条件 | 用户可见反馈 | 恢复/下一步 | 覆盖标签 | 证据/推理 | -|------|----------|--------------|-------------|----------|-----------| -{{state_inventory_rows}} - -## 分支、状态与异常路径 - -{{branches_states_exceptions}} - -## 覆盖度证据结论 - -| 需求/场景 | 预览位置 | 覆盖标签 | 证据/推理 | 缺口或问题 | -|-----------|----------|----------|-----------|------------| -{{coverage_rows}} - -## 已保留评审记录 - -{{preserved_review_records}} - -## 未覆盖项、未知项与评审问题 - -{{review_questions}} diff --git a/extensions/preview/templates/preview/high.html b/extensions/preview/templates/preview/wireflow.html similarity index 65% rename from extensions/preview/templates/preview/high.html rename to extensions/preview/templates/preview/wireflow.html index a23d7e595d..c1daf9ed53 100644 --- a/extensions/preview/templates/preview/high.html +++ b/extensions/preview/templates/preview/wireflow.html @@ -1,21 +1,22 @@ - + - High-Fidelity Preview + Spec Kit Preview - Fidelity: {{fidelity}} @@ -101,24 +108,18 @@
-

High-Fidelity Preview

-
{{metadata}}
+

Spec Kit Preview

+
+
Fidelity: {{fidelity}}
+ {{metadata}} +
-
-

输入来源与读取范围

- {{input_sources}} -
- -
-

需求证据摘要

- {{evidence_summary}} -
- -
-

首屏与交互预览

-
-
{{initial_screen}}
+
+

设计物预览

+
{{fidelity_note}}
+
+
{{design_surface}}
{{interaction_controls}}
@@ -128,13 +129,23 @@

Wireflow

{{wireflow}}
+
+

输入来源与读取范围

+ {{input_sources}} +
+ +
+

需求证据摘要

+
{{evidence_summary}}
+
+

页面/节点清单

- + @@ -189,8 +200,41 @@

分支、状态与异常路径

{{branches_states_exceptions}} +
+

输入到设计映射

+

spec.md 设计输入映射

+
ID屏幕/节点页面/节点 目的 可见元素 用户动作
+ + + + + + + + + + + {{spec_design_mapping_rows}} +
来源项类型设计映射覆盖标签证据/推理缺口或问题
+ +

uc.md 设计输入映射

+ + + + + + + + + + + + {{uc_design_mapping_rows}} +
来源项类型设计映射覆盖标签证据/推理缺口或问题
+
+
-

覆盖度证据结论

+

交付质量结论

@@ -201,24 +245,25 @@

覆盖度证据结论

- {{coverage_rows}} + {{quality_conclusion_rows}}
缺口或问题
-
-

已保留评审记录

- {{preserved_review_records}} +
+

已保留设计记录

+ {{preserved_design_records}}
-
-

未覆盖项、未知项与评审问题

- {{review_questions}} +
+

未覆盖项、未知项与设计问题

+ {{design_questions}}