AGENT SKILL

sp-prd-build

Use when `sp-prd-scan` has produced a complete reconstruction package and the final PRD suite must be compiled from it.

License 许可
MIT
最近更新
2026-08-07
Stars
★ 0
Forks
0

01 前言 Front Matter

name
sp-prd-build
metadata
{ "author": "github-spec-kit", "source": "templates/commands/prd-build.md" }
description
Use when `sp-prd-scan` has produced a complete reconstruction package and the final PRD suite must be compiled from it.
compatibility
Requires spec-kit project structure with .specify/ directory

03 SKILL.md 正文

Invocation Syntax

  • In this integration, invoke workflow skills with $sp-plan-style syntax.
  • References such as /sp.plan, /sp.tasks, or next_command: /sp.plan are 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-build Reconstruction Build

Workflow Contract Summary

This summary is routing metadata only. The full workflow contract is the frontmatter plus the sections below.

  • Use sp-prd-build after sp-prd-scan has produced a validated reconstruction package.
  • Primary truth source: the scan package under .specify/prd-runs/<run-id>/, not a fresh repository crawl.
  • Primary terminal state: completed master pack and exports, or explicit refusal back to sp-prd-scan.

Project Learning

The CLI is the only agent-facing Learning read surface:

  1. Run uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning start --command '<classic-command-name>' --format json before deeper non-trivial work.
  2. 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 json only to filter or page.
  3. 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, and team: 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.

Objective

[AGENT] Compile the reconstruction package into a delivery-grade PRD suite and prove reverse coverage validation.

sp-prd-build must not become a second repository scan. It must not silently fill critical evidence gaps. When the scan package is incomplete, stop and route back to sp-prd-scan. Final outputs must preserve Evidence, Inference, and Unknown labels rather than flattening them during synthesis. Before writing exports, the build step must collect and validate the scan evidence bundle: scan packets, worker results, and the machine-readable reconstruction contracts produced by sp-prd-scan. That intake includes results returned by mandatory subagents before any export synthesis begins.

Context

Required build inputs:

  • The scan workspace under .specify/prd-runs/<run-id>/
  • Core scan artifacts:
    • workflow-state.md
    • prd-scan.md
    • coverage-ledger.json
    • capability-ledger.json
    • artifact-contracts.json
    • reconstruction-checklist.json
  • Machine-readable reconstruction contracts:
    • entrypoint-ledger.json
    • config-contracts.json
    • protocol-contracts.json
    • state-machines.json
    • error-semantics.json
    • verification-surfaces.json
  • Scan packets under scan-packets/<lane-id>.md
  • Project classification from the scan package: ui, service, or mixed

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 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.

Build-support lanes operate on the run bundle, not the live repository.

Required Inputs

Before writing final exports, read:

  • .specify/prd-runs/<run-id>/workflow-state.md
  • .specify/prd-runs/<run-id>/prd-scan.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>/worker-results/**

PRD Run State Protocol

  • workflow-state.md under .specify/prd-runs/<run-id>/ is the resumable state surface for sp-prd-scan and sp-prd-build.
  • [AGENT] Create or resume workflow-state.md before substantial build work.
  • If workflow-state.md exists with active_command: sp-prd-build and a non-terminal build state, resume from it instead of rebuilding intent from chat memory.
  • Track at least:
    • active_command: sp-prd-build
    • status: validating | executing-packets | synthesizing | reverse-validating | blocked | complete
    • scan_status
    • build_status: pending | executing | blocked | complete
    • classification
    • current_packet
    • accepted_packet_results
    • rejected_packet_results
    • failed_readiness_checks
    • failed_reverse_coverage_checks
    • next_action
    • next_command
    • handoff_reason
    • open_gaps

Process

  1. Validate that the sp-prd-scan package is complete enough to build.
  2. Perform packet evidence intake across scan packets, ledgers, JSON contracts, and worker results returned by mandatory subagent lanes.
  3. Compile .specify/prd-runs/<run-id>/master/master-pack.md from scan outputs only.
  4. Render .specify/prd-runs/<run-id>/exports/README.md, .specify/prd-runs/<run-id>/exports/prd.md, and the supporting exports.
  5. Respect classification-aware export semantics: ui, service, and mixed runs must keep the final package grounded in the scan classification even when the fixed export set is used.
  6. Run reverse coverage validation across capabilities, artifacts, field-level contracts, and Evidence / Inference / Unknown labels.
  7. Refuse completion and route back to sp-prd-scan when critical gaps remain.

Validate Scan Inputs Before Execution

  • Refuse build execution if required scan artifacts are missing or malformed.
  • Treat the scan workspace under .specify/prd-runs/<run-id>/ as the only authoritative fact source for sp-prd-build.
  • Do not reread the repository to fill gaps.

Compile And Validate PrdBuildPacket Inputs

  • [AGENT] Compile a validated PrdBuildPacket before dispatch or subagent-blocked status.
  • A valid PrdBuildPacket must include:
    • lane_id
    • mode: bundle_only
    • packet_scope
    • required_scan_inputs
    • required_contract_files
    • required_worker_results
    • expected_exports
    • traceability_targets
    • forbidden_actions
    • minimum_verification
    • result_handoff_path
  • Hard rule: do not dispatch from raw scan prose alone.

Readiness Refusal Rules

sp-prd-build must refuse completion when:

  • required scan artifacts are missing or malformed
  • worker results are absent or structurally shallow
  • critical reconstruction claims cannot be traced back to scan-package evidence
  • export landing for critical artifacts is missing
  • unresolved critical unknowns remain in the bundle
  • the build would need new repository facts to complete honestly

When refusal happens, report the smallest safe repair and route back to sp-prd-scan.

Execution Dispatch

  • [AGENT] Before build-support packet dispatch begins, assess workload shape and the current agent capability snapshot, then apply the shared policy contract: choose_subagent_dispatch(command_name="prd-build", 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 intake or validation lane -> one-subagent on native-subagents when available.
    • Two or more isolated bundle-processing lanes -> parallel-subagents on native-subagents when available.
    • Any need for new repository facts, missing build packet, or unavailable delegation -> subagent-blocked with a recorded reason.

Build Packet Dispatch

  • subagent-blocked stops substantive build work. Record the blocker and stop for escalation or recovery. Do not continue by turning sp-prd-build into a second repository scan.
  • Required join points:
    • before writing master/master-pack.md
    • before writing or finalizing exports/**
    • before reverse coverage / traceability validation
  • Idle subagent output is not an accepted result.
  • The leader must wait for every dispatched build-support lane and integrate the returned evidence before writing exports or declaring the build complete.

Build Worker Result Contract

Every build-support lane result must include:

  • lane_id
  • reported_status
  • bundle_inputs_read
  • traceability_findings
  • export_landing_findings
  • confidence
  • unknowns
  • recommended_repairs
  • minimum_verification
  • result_handoff_path

Reject any build-lane output that lacks concrete bundle inputs, omits critical unknowns, or relies on live repository rereads instead of bundle inputs.

Output Contract

The build phase writes:

  • .specify/prd-runs/<run-id>/workflow-state.md
  • .specify/prd-runs/<run-id>/master/master-pack.md
  • .specify/prd-runs/<run-id>/exports/README.md - package navigation entry for the PRD suite
  • .specify/prd-runs/<run-id>/exports/prd.md - primary reader-facing PRD
  • .specify/prd-runs/<run-id>/exports/reconstruction-appendix.md
  • .specify/prd-runs/<run-id>/exports/data-model.md
  • .specify/prd-runs/<run-id>/exports/integration-contracts.md
  • .specify/prd-runs/<run-id>/exports/runtime-behaviors.md
  • .specify/prd-runs/<run-id>/exports/config-contracts.md
  • .specify/prd-runs/<run-id>/exports/protocol-contracts.md
  • .specify/prd-runs/<run-id>/exports/state-machines.md
  • .specify/prd-runs/<run-id>/exports/error-semantics.md
  • .specify/prd-runs/<run-id>/exports/verification-surface.md
  • .specify/prd-runs/<run-id>/exports/reconstruction-risks.md

Classification-aware export rule:

  • ui runs must keep UI-facing behaviors explicit in the exported package.
  • service runs must keep service, API, CLI, and runtime contract behaviors explicit in the exported package.
  • mixed runs must preserve both UI and service surfaces rather than collapsing to one side.

Quality Gates

  • No New Facts Gate: final exports must be grounded in the scan package rather than new repository rereads.
  • Artifact Landing Gate: critical artifacts from artifact-contracts.json must land in the master pack and appropriate exports.
  • Field-Level Coverage Gate: field, schema, mapping, and transition details must not be flattened into prose-only summaries.
  • Inference Ceiling Gate: inference can summarize evidence, but it cannot replace missing critical facts.
  • Evidence Label Gate: outputs and build validation must preserve Evidence, Inference, and Unknown handling.
  • Classification Export Gate: ui, service, and mixed classification semantics must survive into the final export package.
  • Critical Unknown Refusal Gate: unresolved critical unknowns in the validated scan evidence bundle block final export completion.
  • Traceability Gate: every reconstruction claim in the master pack and exports must trace back to scan-package evidence.
  • Reconstruction Readiness Gate: the compiled archive must preserve enough L4-level detail to recreate critical behavior.
  • Navigation Entry Gate: the compiled archive must include a package navigation entry so the supporting exports are usable as a coherent PRD suite.

Traceability Validation

  • Every reconstruction claim in the master pack and exports must trace back to scan-package evidence.
  • Reject any build-lane output that relies on live repository rereads instead of bundle inputs.

Report Completion

  • Before reporting success, confirm that workflow-state.md records the final build status, accepted packet results, rejected packet results, readiness failures, reverse-coverage outcomes, and the final handoff decision.
  • Successful completion must name the bundle inputs read, the accepted packet results that informed master/master-pack.md and exports/**, and any remaining non-critical unknowns.
  • Blocked completion must name the failed readiness or traceability check, the affected packet or export target, and the smallest safe repair to resume through sp-prd-scan or the current build run.

Guardrails

  • sp-prd-build must not become a second repository scan.
  • sp-prd-build must not silently fill critical evidence gaps.
  • sp-prd-build must not strip Evidence, Inference, or Unknown labels from consequential claims.
  • If the scan package is incomplete, route back to sp-prd-scan instead of guessing.

Codex Subagent Capability Discovery

  • Execution model: preserve the workflow's existing subagent-mandatory, subagents-first, adaptive, or subagent-assisted policy.
  • Dispatch shape: preserve the workflow's existing dispatch shape; use subagent-blocked only after the discovery step below fails or is unsafe.
  • Execution surface: prefer native-subagents when the current runtime supports it; use none only after recording the unavailable or unsafe surface.
  • Native subagent capability discovery: Before recording subagent-blocked, confirm the current runtime exposes spawn_agent, wait_agent, and close_agent; if they are not visible, use the active tool discovery mechanism for multi-agent or subagent tools first.
  • Do not record subagent-blocked until 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, then close_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

chenziyang110
chenziyang110/launchdeck

launchdeck-agent

Codex host adapter contract fixture for Launchdeck.

★ 0
chenziyang110
chenziyang110/launchdeck

launchdeck-agent

Claude host adapter contract fixture for Launchdeck.

★ 0
chenziyang110
chenziyang110/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.

★ 0
chenziyang110
chenziyang110/launchdeck

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.

★ 0
chenziyang110
chenziyang110/launchdeck

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.

★ 0
chenziyang110
chenziyang110/launchdeck

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

★ 0