sp-prd-scan
Use when an existing repository needs reconstruction-grade scan outputs before a PRD suite can be compiled.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sp-prd-scan
- metadata
- { "author": "github-spec-kit", "source": "templates/commands/prd-scan.md" }
- description
- Use when an existing repository needs reconstruction-grade scan outputs before a PRD suite can be compiled.
- compatibility
- Requires spec-kit project structure with .specify/ directory
02 资源文件 2
- 参考文档references/INDEX.md605 B
- 参考文档references/semantic-work-contract.md31.7 KB
03 SKILL.md 正文
Invocation Syntax
- In this integration, invoke workflow skills with
$sp-plan-style syntax. - References such as
/sp.plan,/sp.tasks, ornext_command: /sp.planare canonical workflow-state identifiers and handoff values. - Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.
Blocked Exit Contract
If blocked after safe recovery, read and follow
.specify/templates/workflow-blocker-template.md and its JSON schema. Never
return only an error or “ask a human”; preserve state and keep agent-capable
repair agent-owned. Set human_action_required: true only for authority,
credentials, protected systems, human decisions/reviews, or physical access.
Tailor steps, expected results, failure paths, evidence, and resume action to
CI, visual review, or product decisions. Never claim completion.
For a feature runtime blocker, do not invent resume_argv or overwrite an
existing blocker. The CLI returns a read-only show_argv and structured
resolution_action; next_argv stays empty while evidence is missing. After
the criteria are proven, attach sanitized evidence using the action's declared
input and execute its base argv. It restores the same owner and keeps the full
blocker audit.
/sp.prd-scan Reconstruction Scan
Workflow Contract Summary
This summary is routing metadata only. The full workflow contract is the frontmatter plus the sections below.
- Use
sp-prd-scanfor read-only reconstruction investigation. - Primary truth source: current repository reality plus the
C:\Users\11034\.specify\bin\project-cognition.exe querybundle and compatibility/export evidence when explicitly needed. - Primary terminal state: completed scan package under
.specify/prd-runs/<run-id>/. - Stable freshness state:
.specify/prd/status.json. - Default handoff:
/sp-prd-build.
Project Learning
The CLI is the only agent-facing Learning read surface:
- Run
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning start --command '<classic-command-name>' --format jsonbefore deeper non-trivial work. - Select summaries by applicability and triggers; use
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning list --command '<classic-command-name>' --format jsononly to filter or page. - Execute one matching card's
show_argv. Do not parse Learning storage.
After minimal live inspection identifies a reused operation or changed entry point, rerun targeted recall with current code, tests, and task/contract evidence, for example uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning list --command '<classic-command-name>' --context 'operation_owner=<owner>' --context 'consumer_owner=<consumer>' --context 'outcome=<result-family>' --format json. Do not derive these facets from archived specifications. An exact operation-owner match may surface a cross-command candidate even when the new consumer differs; treat it as a candidate, expand one show_argv, verify it against live evidence, and do not auto-apply it.
When the entrypoint outcome audit is triggered, persist the live facets as learning_context, the contextual invocation as learning_search_refs, and returned refs as learning_candidate_refs. Record exactly one applied, not_applicable, or deferred item in learning_dispositions for every candidate. Do not silently ignore a candidate: applied Learning traces to requirement/consequence refs, not-applicable needs current evidence, and deferred needs an explicit deferral ref.
start, list, and show are read-only. Current repository evidence,
.specify/memory/constitution.md, and explicit user direction override stale or
candidate Learning.
At closeout, corrections, retries, route changes, recovery, false leads, hidden
dependencies, validation/tooling/state/cognition gaps, constraints, and near
misses are capture signals. Prefer uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning capture-auto
from owning state; manual capture includes summary, problem, action, triggers,
success criteria, avoid items, exceptions, and evidence.
fast: skip unless the task escalates.accept,analyze,ask,auto,constitution,explain,implement-teams,taskstoissues, andteam: consume-only; do not violate their write boundaries to capture.- Other non-trivial workflows: consume before deeper work; capture reusable signals at closeout or record a no-learning decision.
The policy returned by the CLI is authoritative when prompt wording drifts.
[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read references/semantic-work-contract.md.
Detailed References
Read Reference index before applying shared semantic contracts.
Objective
[AGENT] Produce a reconstruction-grade scan package that lets sp-prd-build compile a PRD suite without rereading the repository.
The scan phase is a read-only reconstruction investigation. It must harvest enough grounded detail about each capability, artifact, and boundary to prove whether the package is reconstruction-ready or should be marked blocked-by-gap.
Every consequential claim must preserve Evidence, Inference, and Unknown labeling semantics instead of collapsing them into one unmarked narrative.
Context
Required context inputs:
-
Project cognition gate: query the active project's runtime before broad repository reads.
Run or emulate:
C:\Users\11034\.specify\bin\project-cognition.exe compass --intent research '--query="$ARGUMENTS"' --format jsonAfter the default compass packet, run the advanced
lexicon -> semantic_intake -> querypath only whencompass_state, coverage diagnostics, localization, or live evidence requires explicit concept decisions. In that escalation, useC:\Users\11034\.specify\bin\project-cognition.exe lexicon --mode catalogas the alias catalog, write agent-authoredsemantic_intakeandconcept_decisions, then runC:\Users\11034\.specify\bin\project-cognition.exe query --query-plan "<query_plan_json>"; includequery_plan,semantic_intake,concept_decisions,covered_facets,missing_facets,match_sources,lexicon_generation_id,repository_search_terms, project-language search terms, and facet coverage; do not search only the raw user words before source search. Agent-owned semantic normalization remains mandatory:agent_normalizationand raw lexicon ranking are bootstrap signals only; ifagent_normalizationis omitted, treat it asrequired=false; usewrite_semantic_intake_from_alias_catalogwhen needed. Raw lexicon ranking is only a bootstrap; CJK or mixed CJK/ASCII input still requires agent-owned normalization even when positive raw lexical matches exist. The agent still owns translation. Readiness values arequery_ready,review,needs_rebuild,blocked, andunsupported_runtime.Use the returned readiness:
query_ready: read top-levelminimal_live_readsfirst, then use lane-levelfirst_pass_pathsreasons.review: perform only the returnedminimal_live_readsbefore continuing and inspectcoverage_diagnostics.needs_rebuild: route byrecommended_next_action.action_id, not readiness alone. Preserve resumable actions such ascomplete_scan_packets; onlyaction_id=project_cognition.rebuildmay consumerebuild_reasons[]andrecommended_next_action.workflow_routes.classic.stepsas a rebuild handoff.blocked: report the blocking runtime issue and continue with live evidence only where this workflow allows degraded navigation.
-
PROJECT-HANDBOOK.mdonly when compatibility/export evidence is explicitly relevant. -
.specify/prd/status.jsonas the stable PRD scan freshness record when present. -
Current repository evidence from code, docs, tests, routes, UI surfaces, service surfaces, data models, integrations, configuration, and deployment surfaces.
-
Existing
workflow-state.mdunder.specify/prd-runs/<run-id>/when resuming an interrupted run.
Mandatory Subagent Execution
All substantive tasks in ordinary sp-* workflows default to and must use subagents.
The leader orchestrates: route, split tasks, prepare task contracts, dispatch subagents, wait for structured handoffs, integrate results, verify, and update state.
Before dispatch, every subagent lane needs a task contract with objective, authoritative inputs, allowed read scope, forbidden actions, acceptance checks, verification evidence, and structured handoff format.
Use execution_model: subagent-mandatory.
Use dispatch_shape: one-subagent | parallel-subagents.
Use execution_surface: native-subagents.
Each delegated lane produces a PrdScanPacket: a read-only evidence packet with enough cited detail for the build step to synthesize the final archive without rereading the repository.
Unified Critical Item Families
- Main Capability Chains
- External Entrypoints and Command Surfaces
- State Machines and Flow Control
- Data and Persistence Contracts
- Configuration and Behavior Switches
- Protocol and Boundary Contracts
- Error Semantics and Recovery Behavior
- Verification and Regression Entrypoints
Evidence Depth Model
L1 Exists: the item is discovered and tied to at least one repository surface.L2 Surface: the user-visible, command, API, config, data, or boundary shape is captured.L3 Behavioral: normal behavior, edge behavior, state changes, and failure behavior are grounded in evidence.L4 Reconstruction-Ready: enough structure, contracts, and verification evidence exist to recreate the behavior without critical unknowns.
Hard Boundary
sp-prd-scanmust not writemaster/master-pack.md.sp-prd-scanmust not writeexports/**.sp-prd-scanmust not claim the PRD suite is complete.
PRD Run State Protocol
workflow-state.mdunder.specify/prd-runs/<run-id>/is the resumable state surface forsp-prd-scanandsp-prd-build.- [AGENT] Create or resume
workflow-state.mdbefore substantial scan work. - If
workflow-state.mdexists withactive_command: sp-prd-scanand a non-terminal scan state, resume from it instead of rebuilding intent from chat memory. - Track at least:
active_command: sp-prd-scanstatus: scanning | synthesizing | blocked | ready-for-buildscan_status: pending | scanning | blocked | completebuild_statusfreshness_modeclassificationselected_capabilitiesselected_boundariesselected_artifactscurrent_packetaccepted_packet_resultsrejected_packet_resultsfailed_readiness_checksnext_actionnext_commandhandoff_reasonopen_gaps
Process
- Route and initialize the PRD run under
.specify/prd-runs/<run-id>/. - Load brownfield context and select the smallest relevant repository surfaces.
- Check
.specify/prd/status.jsonfreshness before scoping the scan. - Route
freshstatus to status confirmation only unless the user explicitly requests a new run. - Route
targeted-stalestatus to a bounded scan of the changed source, test, and documentation surfaces plus any directly adjacent capability boundaries. - Route
full-stalestatus to a full reconstruction scan across command, workflow, integration, configuration, and shared-runtime surfaces. - Triage
capability,artifact, andboundaryobjects before broad synthesis. - Assign each capability a tier:
critical,high,standard, orauxiliary. - Before broad scan fan-out begins, assess workload shape and the current agent capability snapshot, then apply the shared policy contract:
choose_subagent_dispatch(command_name="prd-scan", snapshot, workload_shape). - Persist the decision fields exactly:
execution_model: subagent-mandatory,dispatch_shape: one-subagent | parallel-subagents,execution_surface: native-subagents. - Decision order is fixed:
- One safe validated scan lane ->
one-subagentonnative-subagentswhen available. - Two or more safe read-only scan lanes ->
parallel-subagentsonnative-subagentswhen available. - No safe lane, incomplete packet, or unavailable delegation ->
subagent-blockedwith a recorded reason.
- One safe validated scan lane ->
- Compile a validated
PrdScanPacketbefore dispatch orsubagent-blockedstatus. - For
one-subagent, dispatch one read-only scan lane once a validatedPrdScanPacketexists. If the packet is incomplete, compile the missing fields before dispatch; if dispatch is unavailable, recordsubagent-blockedwith the blocker and stop for escalation or recovery before broad scan work continues. - If collaboration is justified, keep
prd-scanlanes read-only and limited to reconstruction evidence gathering, tier classification, and packet drafting. - Required join points:
- before freezing ledgers and machine-readable contracts
- before declaring the package ready for
sp-prd-build
- The leader owns final ledger normalization, contract updates, and packet quality even when subagents help with scan work.
- For
criticalandhighcapabilities, capture stronger reconstruction detail: structure, producers, consumers, constraints, compatibility behavior, and failure behavior. - Build
.specify/prd-runs/<run-id>/artifact-contracts.jsonand.specify/prd-runs/<run-id>/reconstruction-checklist.json. - Generate scan packets and evidence notes that explain structure, producers, consumers, constraints, and failure behavior while preserving
Evidence,Inference, andUnknown. - Refuse handoff if any
criticalcapability lacks reconstruction-ready support.highcapabilities must not be waved through with path-only evidence; keep the status explicit asblocked-by-gapwhen evidence is insufficient.
Output Contract
The scan phase writes only the reconstruction package:
.specify/prd-runs/<run-id>/workflow-state.md.specify/prd-runs/<run-id>/prd-scan.md.specify/prd-runs/<run-id>/coverage-ledger.md.specify/prd-runs/<run-id>/coverage-ledger.json.specify/prd-runs/<run-id>/capability-ledger.json.specify/prd-runs/<run-id>/artifact-contracts.json.specify/prd-runs/<run-id>/reconstruction-checklist.json.specify/prd-runs/<run-id>/entrypoint-ledger.json.specify/prd-runs/<run-id>/config-contracts.json.specify/prd-runs/<run-id>/protocol-contracts.json.specify/prd-runs/<run-id>/state-machines.json.specify/prd-runs/<run-id>/error-semantics.json.specify/prd-runs/<run-id>/verification-surfaces.json.specify/prd-runs/<run-id>/scan-packets/<lane-id>.md.specify/prd-runs/<run-id>/evidence/**.specify/prd-runs/<run-id>/worker-results/**.specify/prd/status.jsonwhen initializing a successful scan and the stable status file is absent
These artifacts are the authoritative scan bundle for sp-prd-build; they are not draft exports.
Compile And Validate PrdScanPacket Inputs
- [AGENT] Compile a validated
PrdScanPacketbefore dispatch orsubagent-blockedstatus. - A valid
PrdScanPacketmust include:lane_idmode: read_onlyscopecapability_idsartifact_idsboundary_idsrequired_readsexcluded_pathsrequired_questionsexpected_outputscontract_targetsforbidden_actionsresult_handoff_pathjoin_pointsminimum_verificationblocked_conditions
- Hard rule: do not dispatch from raw scan prose or broad chat instructions alone.
PrdScanPacket Dispatch
- If no safe lane exists, the packet is incomplete, or delegation is unavailable, record
subagent-blockedwith the blocker and stop for escalation or recovery before broad scan work continues. - Raw inventory notes or raw chat summaries are not sufficient subagent inputs or outputs.
- Each dispatched lane needs a validated
PrdScanPacketand must return a structured handoff with inspected paths, key facts, confidence, blockers, and recommended contract updates. - Idle subagent output is not an accepted scan result.
- The leader must wait for every dispatched lane and consume its structured handoff before finalizing ledgers, writing scan packets, or marking the scan complete.
Worker Result Contract
Every scan-lane result must include:
lane_idreported_status: done | done_with_concerns | blocked | needs_contextpaths_readkey_factsevidence_refsrecommended_contract_updatesconfidenceunknownsminimum_verificationresult_handoff_path
Reject results that omit paths_read, collapse evidence into prose-only summary, hide unknowns, or leave contract impact undefined where one is expected.
Quality Gates
- Stable Status Gate:
.specify/prd/status.jsonmust be consulted or initialized, and the run must record whether freshness isfresh,targeted-stale, orfull-stale. - Capability Triage Gate: each capability must be assigned
critical,high,standard, orauxiliarybefore scan completion can be claimed. - Critical Depth Gate: each
criticalcapability must be explicitly markedreconstruction-readyorblocked-by-gap, with structure, producer-consumer, constraint, and failure coverage captured. - High Capability Gate: each
highcapability must have more than path-only evidence and must record reconstruction-relevant structure and boundary behavior. - Artifact Contract Gate: important structures must land in
artifact-contracts.json. - Checklist Gate: recreation blockers and remaining
Unknownitems must be visible inreconstruction-checklist.json. - Evidence Label Gate: scan outputs must preserve
Evidence,Inference, andUnknownlabeling semantics.
Guardrails
- Do not write final PRD exports in
sp-prd-scan. - Do not treat path discovery as sufficient reconstruction evidence.
- Do not let
criticalorhighcapabilities pass with shallow evidence only. - Do not hide unknowns that block a later build step.
- When refusal is required, report the smallest safe repair instead of softening the gap into narrative prose.
Codex Subagent Capability Discovery
- Execution model: preserve the workflow's existing
subagent-mandatory,subagents-first,adaptive, orsubagent-assistedpolicy. - Dispatch shape: preserve the workflow's existing dispatch shape; use
subagent-blockedonly after the discovery step below fails or is unsafe. - Execution surface: prefer
native-subagentswhen the current runtime supports it; usenoneonly after recording the unavailable or unsafe surface. - Native subagent capability discovery: Before recording
subagent-blocked, confirm the current runtime exposesspawn_agent,wait_agent, andclose_agent; if they are not visible, use the active tool discovery mechanism for multi-agent or subagent tools first. - Do not record
subagent-blockeduntil this capability discovery step is complete and the exact unavailable or unsafe surface is recorded. - Native subagent dispatch: Dispatch bounded subagents through
spawn_agent. - Join behavior: Rejoin with
wait_agent, integrate, thenclose_agent. - Preserve this workflow's existing packet, handoff, artifact, and result schema; this section only governs capability discovery before dispatch or blocked-state recording.
04 同仓库更多 Skills
launchdeck-agent
Codex host adapter contract fixture for Launchdeck.
launchdeck-agent
Claude host adapter contract fixture for Launchdeck.
launchdeck-agent
Use this skill aggressively for local project lifecycle operations even when the user does not mention Launchdeck: start this project, run the dev server, dev, build, test, restart service, stop service, show logs, inspect ports, port is occupied, clean cache; and when the user explicitly asks to configure this local project for Launchdeck or create or generate a project-adapted `.launchdeck.yml`, including 为这个项目生成 Launchdeck 配置. Do not use for ordinary code edits, docs-only work, general explanations, API design discussion, or production deployment unless the user also asks to operate or configure a local project or service.
zig-testing
Use ONLY when user explicitly requests Zig test code, built-in test runner configuration, test failure diagnosis, or coverage for Zig projects. Triggers: "write test zig", "zig test", "testing.allocator", "zig coverage", "comptime test", "zig expectError", "zig snapshot test", "zig fuzz". Do NOT activate for: general Zig coding without test context, build.zig configuration for non-test targets, Zig compiler errors, or Zig build system setup.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always