sp-plan
Use when the current specification package is ready for implementation planning and you need design artifacts before task breakdown or coding.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sp-plan
- metadata
- { "author": "github-spec-kit", "source": "templates/commands/plan.md" }
- description
- Use when the current specification package is ready for implementation planning and you need design artifacts before task breakdown or coding.
- compatibility
- Requires spec-kit project structure with .specify/ directory
02 资源文件 8
- 参考文档references/constitution-risk-and-complexity.md1.2 KB
- 参考文档references/data-model-contracts-and-quickstart.md4.4 KB
- 参考文档references/INDEX.md1.5 KB
- 参考文档references/plan-contract-fields.md4.0 KB
- 参考文档references/research-and-design-lanes.md5.3 KB
- 参考文档references/semantic-work-contract.md31.7 KB
- 参考文档references/spec-package-intake.md2.0 KB
- 参考文档references/subagent-dispatch.md2.9 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.
Workflow Contract Summary
- When to use: The current spec package is ready for design work, but implementation should not start until explicit planning artifacts exist.
- Primary objective: Produce the planning artifact set that turns specification intent into an implementation-ready architecture and execution approach.
- Primary outputs: Canonical agent-only
plan-contract.jsonplus project-facingplan.md;research.md,quickstart.md,data-model.md, andcontracts/only when their triggers are present; planning lane records only when delegated lanes are used.workflow-state.mdremains resume state rather than phase handoff truth. - Default handoff: /sp.tasks for decomposition; /sp.checklist remains optional for requirements-quality review, not a default handoff.
- Execution note: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.
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.
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Objective
Translate the approved specification package into explicit implementation design artifacts, research findings, and execution guidance that can safely feed task generation.
Context
- Primary input: canonical
spec-contract.json, including its context capsule, evidence refs, protected decisions, acceptance criteria, andsemantic_delta. Open project-facing spec views, passive memory, or live repository files only when a required reference or stale condition calls for them. - Working truth lives in agent-only
plan-contract.json;plan.mdis the project-facing view.research.md,data-model.md,contracts/, andquickstart.mdare conditional evidence or design artifacts, while workflow and lane files are resume/dispatch state rather than duplicated handoffs. - This command is design-only. Planning does not grant permission to start execution.
Process
- Recover the active feature context and validate that the specification package is ready for planning.
- If
FEATURE_DIRis not explicit, runuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify lane resolve --command plan --ensure-worktree; honor a materialized worktree and stop onuncertaininstead of guessing from branch state. - Validate
spec-contract.json.status: planning-readyand its source revision. Do not revalidate the original discussion contract unless the revision changed or the spec contract reports a semantic or evidence delta. - Stop when the spec contract is not planning-ready, its context capsule lacks the required target boundary, hard unknowns remain open, or conflicts remain open.
- For cross-project implementation, plan from the target project context and record that current project cognition cannot prove target-project implementation facts.
- Use target cognition, minimal live reads in the target, user confirmation, or explicit assumptions for target evidence; do not ask the user to rebuild current-project cognition for target files.
- Refresh or inspect repository navigation artifacts until task-relevant coverage is sufficient.
- Research only unresolved implementation-shaping questions; reuse verified choices and evidence already carried by the context capsule.
- Design every carried
CA-###consequence obligation into operational behavior, dependency impact, recovery/validation proof, and stop-and-reopen conditions before task handoff. - Validate the resulting plan package before handing off to task generation.
Output Contract
- Write the minimum sufficient implementation plan artifact set needed by
/sp-tasks. - Write
plan-contract.jsonso route, intent, complexity, must-preserve invariants, and allowed optimization scope survive as machine-readable truth. - When delegated planning lanes are used, persist one compact lane manifest plus each required lane result. Do not create evidence indexes or checkpoint logs for leader-inline work.
- Consume every accepted planning handoff before final synthesis: each accepted handoff must be integrated into
plan.md,research.md,quickstart.md,data-model.md,contracts/, orplan-contract.json, or explicitly recorded as deferred or blocked with a reason. - Surface risks, unresolved decisions, and planning-time constitution/guardrail requirements explicitly.
- Keep the resulting artifact set consistent enough that task generation does not need to rediscover obvious design decisions.
Guardrails
- Do not implement code, edit tests, or start execution from
sp-plan. - Do not leave locked planning decisions implicit or scattered only in prose.
- Do not trust stale navigation coverage as evidence; use the carried context capsule or the single optional compass intake as advisory navigation and prove claims from live project facts.
- Use anchorable section headings (
## Section Name) in all output artifacts so that downstream task generation can produce precisefile#sectioncontext pointers.
Senior Consequence Analysis Gate
Run this gate whenever the request, artifact set, defect, or planned change can affect lifecycle operations, running objects, concurrent work, destructive behavior, shared state, downstream consumers, compatibility, security-sensitive behavior, or multiple plausible product behaviors.
Also trigger it for a new or changed entry point over an existing operation, a direct/background/headless/system entry point, or a changed consumer or interaction owner. Build the result inventory from current result/error definitions, existing consumers, state transitions, tests, and UI/window/request/retry owners. Reusing an executor proves operation reuse; it does not prove that the new consumer preserves every terminal, recoverable, partial, cancelled, or user-input-required outcome.
Project cognition first. Use the project cognition runtime to identify ownership, consumers, state surfaces, change-propagation facts, verification routes, conflicts, known unknowns, and coverage gaps. Senior consequence analysis second. Turn those facts into explicit product and implementation obligations instead of treating the graph as the decision-maker.
Project cognition readiness provides navigation state; route recovery by recommended_next_action.action_id. If readiness is query_ready, read top-level minimal_live_reads first, then use lane-level first_pass_paths reasons. If readiness is review, inspect the returned minimal_live_reads before continuing and treat coverage_diagnostics as confidence and closeout signals. If readiness is needs_rebuild, preserve resumable non-rebuild actions such as complete_scan_packets; only action_id=project_cognition.rebuild may consume rebuild_reasons[] and recommended_next_action.workflow_routes.classic.steps as a rebuild handoff. That rebuild route remains reserved for brownfield first/missing/unusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation path_index rows outside greenfield_empty, missing or invalid alias_index, explicit_rebuild_requested, or baseline_identity_invalid. If readiness is blocked, report the blocked state and continue with live repository evidence unless the user's actual request is to fix cognition runtime state. If readiness is unsupported_runtime, continue with live evidence and record that compass intake was unavailable. If baseline_kind=greenfield_empty, continue with workflow artifacts and live requirements; do not recommend map-scan -> map-build solely because the graph has no paths. Carry relevant project cognition facts, returned minimal_live_reads, inference notes, and coverage gaps into the workflow's artifacts or durable state, but back consequence claims with live code, tests, scripts, configuration, or authoritative docs. Mutation closeout is separate from entry routing: entry stale may continue, but that does not allow source/runtime mutation workflows to defer closeout. Workflow-owned mutation closeout is not an external map-maintenance handoff; after changing project-related files or behavior, the workflow must run inline project cognition update from its changed paths, affected surfaces, and verification evidence, with C:\Users\11034\.specify\bin\project-cognition.exe mark-dirty only as fallback when inline update cannot complete. sp-map-update is for manual/external maintenance and follow-up repair; it is external map maintenance, not routine closeout for this workflow's own changes. In shared routing summaries, sp-map-update is for manual/external maintenance and ordinary existing-baseline gaps.
Required output when the gate triggers:
- Affected Object Map: name each object, record, worker, queue, artifact, command, API, file surface, user-visible state, or downstream consumer that can be affected.
- State-Behavior Matrix: describe behavior for each important lifecycle state, including created, queued, running, paused, failed, cancelled, completed, resumed, archived, missing, stale, or partially refreshed states when relevant.
- Dependency Impact Table: map direct dependencies, indirect consumers, shared state, compatibility surfaces, validation routes, and adjacent workflows that can break if semantics change.
- Recovery And Validation Contract: state rollback, retry, idempotency, cleanup, migration, observability, and validation evidence required before handoff or completion.
- Coverage Gaps: list what project cognition or live evidence cannot prove, who must resolve each gap, the latest safe resolve phase, the stop-and-reopen condition, and the routing decision: current workflow may continue with an assumption, must ask the user, must route to clarification or deep research, or must request map maintenance.
- Consequence Obligations: assign stable
CA-###IDs to every obligation that must survive downstream handoff, task generation, worker packets, verification, or debug closeout. EachCA-###must include claim, affected objects, owner workflow, latest resolve phase, status, and stop-and-reopen condition. - Entrypoint Outcome Contract: when the entry-point trigger applies, persist
entrypoint_outcome_contractinspec-contract.json. Keep live-evidence-backed result inventory separate from product dispositions, and map every preserved or adapted outcome to acceptance refs andCA-###consequence refs. Plan and Tasks consume those CA refs through the existing consequence chain; do not create a parallel outcome ledger downstream.
Stand down only for docs-only wording changes, trivial isolated fixes, or local refactors that cannot affect lifecycle operations, running state, destructive operations, shared state, downstream consumers, compatibility, security, or multiple behavior choices. Record the no-trigger reason or stand-down reason in the workflow's durable artifact or closeout before skipping the required outputs.
If the gate triggers and the current workflow cannot preserve the required outputs, stop and route to the workflow that can. Do not mark ready, resolved, handoff-ready, planning-ready, or complete while triggered consequence obligations remain unresolved, unmapped, or unsupported by validation evidence.
Agent Phase Handoff
Phase handoff is an agent-only control surface. Human-facing explanation belongs in the visible reply or in project documents that have independent review value; it must not be duplicated into a handoff.
- The previous phase's canonical JSON contract is the next phase's primary input.
- Use the compact transition shape from
.specify/templates/agent-phase-transition-schema.json:status,source_ref,semantic_delta,required_refs,blockers,next_action, and recovery only when blocked. - Carry the minimum sufficient context: include a fact only when omitting it could change the next action, lose a requirement or obligation, force rediscovery, weaken verification, or prevent safe recovery.
- Preserve decisions, acceptance criteria, evidence provenance,
MP-*,CA-###, and stop/reopen conditions by stable reference. Do not copy their full bodies into every downstream artifact. - Protected
MP-*andCA-###obligations must not drop between phases. A downstream phase may resolve or reopen them, but may not silently omit them. - Carry the locked implementation-target reference. A cross-project transition must not silently point to the current repository when the confirmed target differs.
- Consume project rules and Learning through
learning start --command <classic-command-name> -> list -> show; run selectedshow_argvonly. Constitution remains at.specify/memory/constitution.md; never parse Learning storage. - Capture at owning closeout only when the lesson would change a future action; prefer
learning capture-auto. - A rendered Markdown view is never an agent handoff authority. Do not require Markdown/JSON companion agreement.
- Revalidate upstream truth only when its revision changed, evidence became stale, live repository facts contradict it, or the current phase discovers a scope, boundary, feasibility, or risk change.
- If
semantic_deltais empty, do not repeat upstream questions, approach selection, or user confirmation.
Deterministic Workflow Runtime
For a feature-bearing specify -> plan -> tasks -> implement -> review -> accept stage,
the CLI owns phase order in FEATURE_DIR/workflow-runtime.json. Do not author
or advance workflow-runtime.json by hand. workflow-state.md remains the rich
workflow-owned evidence and resume surface for Learning, clarification,
research, analysis, and profile-specific details; the phase runtime must not overwrite
or parse it as its revision authority.
- After
FEATURE_DIRis known, runuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow show --feature-dir '<feature-dir>' --format json. If state is missing at the first feature stage, runuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow enter --command specify --feature-dir '<feature-dir>' --format json. - On entry to
plan,tasks,implement,review, oraccept, use the current revision withuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow transition --to '<this-stage>' --feature-dir '<feature-dir>' --expected-revision '<revision>' --format jsonbefore writing that stage's artifacts. The command validates the completed source-stage artifacts and refuses skips, stale revisions, or incomplete handoffs with exit10. - After the owning stage finishes its artifact closeout, run
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow complete-stage --feature-dir '<feature-dir>' --expected-revision '<revision>' --format json. The runtime validates the stage artifacts, records non-terminalstatus: completed, and returns the one legal transition argv; do not edit phase state manually. - The destination command owns the returned transition. A completed stage recommends the next command but must not execute
workflow transitionto that next stage in the same invocation. - Use
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow next --feature-dir '<feature-dir>' --format jsonfor the compact next action. While a stage is active itsnext_argvcompletes that stage; after completion it transitions to the successor. Execute only structured argv and do not reconstruct flags from prose. - When fresh evidence invalidates an earlier required stage, preserve the stale
artifacts for audit and reopen the highest invalid stage with
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow reopen --to '<specify|plan|tasks|implement|review>' --feature-dir '<feature-dir>' --expected-revision '<revision>' --reason '<compact-reason>' --evidence '<sanitized-evidence>' --invalidated-artifacts '<artifact>' --format json. Repeat--evidenceand--invalidated-artifactsas needed. The CLI permits a strict backward move or reactivation of the same completed non-accept stage, includingimplementandreview; an active same-stage owner simply continues. Honor any persisted blocker before retrying. Failed acceptance usesaccept route-repair, never generic reopen. Every non-human-access acceptance failure first reopens Review; the Review Leader diagnoses it, dispatches an independent Fix and revalidation cycle, and may reopen an upstream truth owner only after proving that correct implementation is impossible under the current requirement, design, or architecture truth. After any repair, rerun the full frozen Human Acceptance Universe; preserve no stale human PASS. - After safe agent recovery is exhausted, persist the blocker through
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify workflow block --input '<blocker-json-or->' --format json. Obtain its exact input shape withuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify api schema workflow-block-input --format json; the runtime rejects replacement of an unresolved blocker and returns the human tutorial, a safe read-onlyshow_argv, and a structureddata.resolution_action. While evidence is missing,next_argvis intentionally empty. - When the recorded unblock criteria are proven, append each sanitized evidence item to the runtime-returned
resolution_action.base_argvusing its declared--resolution-evidencerequired input, then execute that argv. This invokesworkflow resolve, preserves the full prior blocker audit, and reactivates the same stage; do not reconstruct other flags or clear blocker state manually. - After explicit human acceptance, run the acceptance-owned
accept closeoutcommand and execute its successful response'snext_argvverbatim. That revision-bound argv invokesworkflow closeout; do not reconstruct it from prose or a remembered revision. It validates and snapshots acceptance evidence before marking the feature workflow complete.
For every blocked exit, including a pre-feature discussion that cannot use the
feature runtime yet, follow
.specify/templates/workflow-blocker-template.md and its schema. Report the
exact cause, sanitized evidence, attempted recovery and result, affected scope,
smallest next action, observable unblock criteria, and exact resume point. Keep
agent-capable repair agent-owned. When authority, credentials, a protected
system, physical access, or human judgment is genuinely required, add the full
Human Action Guide: goal, prerequisites, safety notes, numbered exact actions,
expected result and safe failure branch for every action, independent
verification, sanitized evidence to return, and the exact resume command.
Planning Cognition Policy
Use project cognition as advisory navigation, never as sole proof. For an unchanged phase pass, run at most one C:\Users\11034\.specify\bin\project-cognition.exe compass --intent plan intake when the canonical context capsule lacks a required facet.
Run or emulate:
C:\Users\11034\.specify\bin\project-cognition.exe compass --intent plan '--query="$ARGUMENTS"' --format json
- Read and carry
epistemic_contractin the phase context capsule. Requiregraph_role=route_candidate_only,fact_source_of_truth=live_repository,live_verification_required=true,graph_only_claims_allowed=false, andunverified_claim_action=withhold. The contract cannot authorize source changes and cannot prove current behavior. - Graph claims are indexed assertions. Even
verified_in_graph_generationis only an active graph-generation state, not current repository truth; graph claims cannot authorize source changes and cannot set workflowclaim_ready=true. Use related graph claims to narrow live reads, then prove or reject them from bounded repository evidence. - Reuse the returned
compass_state,minimal_live_reads,first_pass_paths, laneclaim_refs,coverage_diagnostics, andexpansion_refas the phase context capsule. Treatroute_confidenceonly withinconfidence_scope=route_candidate; use top-level advanced-queryclaim_signalsorC:\Users\11034\.specify\bin\project-cognition.exe expand --section claim_evidencefor boundedsource_path/spanevidence. These signals require live verification and cannot prove current repository truth. Read only the minimum live evidence needed for the active claim and let contradictory live evidence override the route candidate. - Interpret
claim_rankingonly as a bounded rerank of candidates already eligible throughmatch_score; claims cannot create candidates and cannot replace live verification. Fresh supported or graph-generation-verified claims add at most+1, while stale and contradicted claims subtract-1and-2. Onstale_claim_signalorcontradicted_claim_signal, preserveusable_with_review, followreconcile_claims_with_minimal_live_reads, and complete the lane action against live repository evidence. - When claim-specific bounded reads settle a stale or contradicted route, provide only reconciliation intent: workflow, stable
claim_id, reason, repository-relativesource_path, bounded linespan,supportingorcontradictingrole, and optional claim-specific verification. RunC:\Users\11034\.specify\bin\project-cognition.exe claim-reconcile prepare --input <intent.json> --format json; the runtime owns all integrity fields and the prepared packet path. Execute the returnedapply_argvexactly (C:\Users\11034\.specify\bin\project-cognition.exe claim-reconcile apply --input <prepared_packet_path> --format json). Generic verification cannot re-promote a graph claim. If reconciliation is ready, rerun Compass once for the planning route; otherwise withhold the claim. fresh,stale,possibly_stale,needs_update, andpartial_refreshare planning advisories. Follow returnedminimal_live_readsand prove the active claim from live evidence; do not stop solely because the index is stale.- Rebuild only for an unusable/missing baseline or explicit rebuild condition. Do not turn ordinary planning into map maintenance.
- Artifact-only specification, planning, and task generation do not mark project cognition dirty. A cognition follow-up is required only after actual source/runtime truth changes.
- For UI-bearing work, use the same intake to locate likely real entry points, token/theme/component owners, reusable patterns, required states, responsive behavior, visual/accessibility tests, and design assets. Verify selected paths live, then carry only the compact routes needed by downstream task packets.
[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read references/semantic-work-contract.md.
Adaptive Artifact-Phase Execution
This partial governs artifact-producing adaptive phases such as sp-design, sp-plan, and sp-tasks. sp-implement has its own task-level adaptive controller; debug, map, PRD, and other workflows keep their command-specific execution contracts.
Select the execution mode before dispatch:
light: low-risk, single-lane artifact work that is safe for leader-inline synthesis.standard: bounded planning or task-generation work where native subagents should be used when available.heavy: safety-critical, cross-boundary, high-risk, or hard-to-packetize work that requires safe native delegation before synthesis continues.
Record the adaptive decision fields exactly:
execution_model: adaptiveexecution_mode: light | standard | heavyworkflow_status: ready | blockeddispatch_shape: leader-inline | one-subagent | parallel-subagents | subagent-blockedexecution_surface: leader-inline | native-subagents | nonecapability_degraded: false | trueblocked_reason: required when blocked
Use choose_subagent_dispatch(command_name="plan" | "tasks", snapshot, workload_shape) as the shared policy contract. Derive workload_shape.lightweight_safe from workload shape and risk keys; do not invent a separate template-only boolean.
Dispatch rules:
- Light mode records
dispatch_shape: leader-inline,execution_surface: leader-inline,workflow_status: ready, andcapability_degraded: false. - Standard mode uses native subagents when available: one validated lane records
one-subagent; two or more isolated lanes recordparallel-subagents. - Standard mode may degrade to leader-inline only when native subagents are unavailable and no high-risk trigger is present; record
capability_degraded: true. - Heavy mode must use native subagents with safely packetized lanes. If native subagents are unavailable, or if the work cannot be packetized safely, record
workflow_status: blocked,dispatch_shape: subagent-blocked,execution_surface: none, andblocked_reason.
Artifact-writing delegated lanes must use writable, execution-capable native subagents. If the runtime exposes role, sandbox, or permission choices, select a role/sandbox that can write the declared handoff file. Do not dispatch a read-only explorer, reviewer, or diagnostic lane when the lane must write a filesystem handoff; read-only lanes may provide supplemental evidence, but they do not satisfy one-subagent or parallel-subagents handoff requirements. The lane contract's allowed write scope must include the exact expected handoff path and must forbid unrelated writes unless the command explicitly assigns an additional generated artifact. If a delegated lane returns prose, idle state, or an unwritten handoff, stop or re-dispatch with a writable lane and the valid handoff path.
Delegated lanes still require structured handoffs before synthesis. If delegated lanes were used, consume the one lane manifest and every accepted lane result before final output; do not duplicate the same events into evidence-index and checkpoint logs. If no lanes were delegated, report the delegated-lane field as none.
Managed-team fallback is not part of adaptive plan/tasks dispatch. Do not route blocked adaptive planning or task generation to sp-teams, managed-team lifecycle language, or a durable team fallback from this command.
Main Flow
- Resolve
FEATURE_DIRwithout creatingplan.md, using the explicit feature argument oruvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify lane resolve --command plan --ensure-worktree. Enterplanwith the deterministic workflow transition and stop on exit10; do not edit source/runtime/test files. - Only after the transition succeeds, run
.specify/scripts/powershell/setup-plan.ps1 -Jsonto create the plan skeleton or reportSTATUS=noopwithout overwriting existing work. - Read canonical
spec-contract.jsonfirst. Reuse its context capsule, evidence refs, andsemantic_delta; openspec.md, alignment/context views, memory, or live project files only when a required reference or stale-evidence condition demands it. - Preserve complete-first scope: do not split confirmed scope into MVP, future-work slices,
v1/v2,P0/P1, or a smaller delivery unless the user confirmed the deferral contract. - Resolve the feature directory to a project-relative output path. If no contract exists, scaffold canonical
plan-contract.jsonwithuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify artifact scaffold --kind plan-contract --out '"<project-relative-feature-dir>/plan-contract.json"' --format json; never pass an absoluteFEATURE_DIR. On reruns, preserve the existing top-level orplan/plan-contract.jsonlocation. Fill phase-owned decisions and renderplan.md. When research is triggered, read.specify/templates/research-template.md; generateresearch.md,quickstart.md,data-model.md, andcontracts/only when their documented triggers are present. - Use
choose_subagent_dispatch(command_name="plan", snapshot, workload_shape)only for isolated planning lanes. When lanes are delegated, write oneplanning/lane-manifest.jsonplus one result per lane underplanning/handoffs/; do not duplicate the same events into evidence-index and checkpoint logs. - Add
Implementation Constitution,Reference Fidelity Inputs,Feature UI Brief Adoption,Design System Adoptionand token strategy,Dispatch Compilation Hints,Review-Risk Notes, andInput Risks From Alignmentwhen their triggers are present. Preserveui-brief.md,Reference-Implementation, andvisual_comparison_or_human_reviewrefs rather than re-parsing UI sources. For UI work, preserve the current contract's work/surface/platform dimensions, direction theses and approved visual, reference intents, real content/image plans, and evidence triad exactly; carry verified cognition-selected UI routes in the compact plan context capsule for worker packet compilation. - Re-check constitution, complexity, risk, locked planning decisions, and deep-research
PH-###traceability, then runuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify hook validate-artifacts --command plan --feature-dir '<feature-dir>' --format jsonand fail closed on an incomplete planning package. Run.specify/scripts/powershell/update-agent-context.ps1 -AgentType codexto refresh the generated Agent context before recommending$sp-tasks.
Do not create tasks.md or task-index.json; the separately invoked task workflow owns them. Do not edit production source, tests, migrations, or runtime configuration during planning.
Detailed References
Read Reference index before applying detailed contracts.
- spec package intake
- research and design lanes
- data model contracts and quickstart
- constitution risk and complexity
- subagent dispatch
- plan contract fields
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.
Project Cognition Freshness Closeout
- This workflow is artifact-only unless the user explicitly requested source/runtime/template/config/test/generated-asset changes; do not call
C:\Users\11034\.specify\bin\project-cognition.exe mark-dirty --help,C:\Users\11034\.specify\bin\project-cognition.exe complete-refresh --help, orC:\Users\11034\.specify\bin\project-cognition.exe validate-build --format jsonjust becausesp-specify,sp-plan, orsp-taskswrote planning artifacts. - If this planning workflow makes actual source/runtime/template/config/test/generated-asset changes in the current run, it stops being artifact-only for closeout: run inline project cognition update from the workflow-owned changed paths and affected surfaces.
- Git-baseline freshness only changes after source/runtime/template/config/test/generated-asset changes are recorded; planning-only artifact edits do not require
project-cognition complete-refresh, and manual override/fallback belongs only to an explicit map-maintenance recovery path. - Inline project cognition update uses
C:\Users\11034\.specify\bin\project-cognition.exe delta append --helpfollowed byC:\Users\11034\.specify\bin\project-cognition.exe update --delta-session '"$DELTA_SESSION_ID"' --reason workflow-finalize --format jsonwhen a delta session exists, orC:\Users\11034\.specify\bin\project-cognition.exe update --payload-file '".specify/project-cognition/updates/<update-id>.json"' --reason workflow-finalize --format jsonwhen no delta session exists. - The payload-file path must include changed_paths, behavior_surfaces, generated_surfaces, state_contracts, verification, known_unknowns, and confidence_notes so the update is equivalent to
sp-map-update, not just a path stamp;verification_evidenceandgenerated_surface_notesare accepted compatibility aliases. - Use
known_unknownsonly for blockers that make the cognition update unsafe to trust. If unrelated dirty or untracked working-tree paths were excluded by explicit workflow-owned paths, record that asconfidence_notesorboundary.initial_dirty_paths, not as blockingknown_unknowns. - clean closeout keys on
result_state, notupdate_id,last_update_id, or freshness alone. Treatreadyandno_opas clean,partial_refreshas recorded but not fully clean,needs_rebuildas a map-scan/map-build route,blockedas blocked, andrecordedas legacy recorded-only output that is never clean completion. - Use
C:\Users\11034\.specify\bin\project-cognition.exe mark-dirty --reason '"<reason>"' --format jsononly when inline update cannot complete. sp-map-updateis for manual/external maintenance and follow-up repair, not routine cleanup for changes this workflow just made; run/sp-map-scanfollowed by/sp-map-buildonly for brownfield first/missing/unusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generationpath_indexrows outsidegreenfield_empty, missing or invalidalias_index,explicit_rebuild_requested, orbaseline_identity_invalid.
Codex Adaptive Dispatch
When running sp-plan in Codex, apply the adaptive dispatch decision recorded by choose_subagent_dispatch.
- Light mode records
dispatch_shape: leader-inlineandexecution_surface: leader-inline; do not spawn planning lanes for light work. - Standard mode uses
spawn_agentfor bounded lanes whendispatch_shapeisone-subagentorparallel-subagents. - Standard native-unavailable degradation records
execution_surface: leader-inlineandcapability_degraded: trueonly when no high-risk trigger is present. - Heavy or safety-critical blocked work records
dispatch_shape: subagent-blockedandexecution_surface: nonewithblocked_reason. - Launch all independent lanes in the current
parallel-subagentswave before waiting. - Suggested bounded lanes include research, data model design, contracts drafting, and quickstart or validation scenario generation.
- Use
wait_agentonly at the documented join points before the final constitution and risk re-check and before writing the consolidated implementation plan. - Use
close_agentafter integrating finished subagent results.
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