AGENT SKILL

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

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.

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.json plus project-facing plan.md; research.md, quickstart.md, data-model.md, and contracts/ only when their triggers are present; planning lane records only when delegated lanes are used. workflow-state.md remains 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, and semantic_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.md is the project-facing view. research.md, data-model.md, contracts/, and quickstart.md are 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_DIR is not explicit, run uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify lane resolve --command plan --ensure-worktree; honor a materialized worktree and stop on uncertain instead of guessing from branch state.
  • Validate spec-contract.json.status: planning-ready and 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.json so 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/, or plan-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 precise file#section context 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. Each CA-### 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_contract in spec-contract.json. Keep live-evidence-backed result inventory separate from product dispositions, and map every preserved or adapted outcome to acceptance refs and CA-### 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-* and CA-### 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 selected show_argv only. 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_delta is 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_DIR is known, run uvx --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, run uvx --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, or accept, use the current revision with uvx --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 json before writing that stage's artifacts. The command validates the completed source-stage artifacts and refuses skips, stale revisions, or incomplete handoffs with exit 10.
  • 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-terminal status: 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 transition to 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 json for the compact next action. While a stage is active its next_argv completes 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 --evidence and --invalidated-artifacts as needed. The CLI permits a strict backward move or reactivation of the same completed non-accept stage, including implement and review; an active same-stage owner simply continues. Honor any persisted blocker before retrying. Failed acceptance uses accept 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 with uvx --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-only show_argv, and a structured data.resolution_action. While evidence is missing, next_argv is intentionally empty.
  • When the recorded unblock criteria are proven, append each sanitized evidence item to the runtime-returned resolution_action.base_argv using its declared --resolution-evidence required input, then execute that argv. This invokes workflow 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 closeout command and execute its successful response's next_argv verbatim. That revision-bound argv invokes workflow 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_contract in the phase context capsule. Require graph_role=route_candidate_only, fact_source_of_truth=live_repository, live_verification_required=true, graph_only_claims_allowed=false, and unverified_claim_action=withhold. The contract cannot authorize source changes and cannot prove current behavior.
  • Graph claims are indexed assertions. Even verified_in_graph_generation is only an active graph-generation state, not current repository truth; graph claims cannot authorize source changes and cannot set workflow claim_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, lane claim_refs, coverage_diagnostics, and expansion_ref as the phase context capsule. Treat route_confidence only within confidence_scope=route_candidate; use top-level advanced-query claim_signals or C:\Users\11034\.specify\bin\project-cognition.exe expand --section claim_evidence for bounded source_path/span evidence. 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_ranking only as a bounded rerank of candidates already eligible through match_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 -1 and -2. On stale_claim_signal or contradicted_claim_signal, preserve usable_with_review, follow reconcile_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-relative source_path, bounded line span, supporting or contradicting role, and optional claim-specific verification. Run C:\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 returned apply_argv exactly (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, and partial_refresh are planning advisories. Follow returned minimal_live_reads and 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: adaptive
  • execution_mode: light | standard | heavy
  • workflow_status: ready | blocked
  • dispatch_shape: leader-inline | one-subagent | parallel-subagents | subagent-blocked
  • execution_surface: leader-inline | native-subagents | none
  • capability_degraded: false | true
  • blocked_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, and capability_degraded: false.
  • Standard mode uses native subagents when available: one validated lane records one-subagent; two or more isolated lanes record parallel-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, and blocked_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

  1. Resolve FEATURE_DIR without creating plan.md, using the explicit feature argument or uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify lane resolve --command plan --ensure-worktree. Enter plan with the deterministic workflow transition and stop on exit 10; do not edit source/runtime/test files.
  2. Only after the transition succeeds, run .specify/scripts/powershell/setup-plan.ps1 -Json to create the plan skeleton or report STATUS=noop without overwriting existing work.
  3. Read canonical spec-contract.json first. Reuse its context capsule, evidence refs, and semantic_delta; open spec.md, alignment/context views, memory, or live project files only when a required reference or stale-evidence condition demands it.
  4. 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.
  5. Resolve the feature directory to a project-relative output path. If no contract exists, scaffold canonical plan-contract.json with uvx --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 absolute FEATURE_DIR. On reruns, preserve the existing top-level or plan/plan-contract.json location. Fill phase-owned decisions and render plan.md. When research is triggered, read .specify/templates/research-template.md; generate research.md, quickstart.md, data-model.md, and contracts/ only when their documented triggers are present.
  6. Use choose_subagent_dispatch(command_name="plan", snapshot, workload_shape) only for isolated planning lanes. When lanes are delegated, write one planning/lane-manifest.json plus one result per lane under planning/handoffs/; do not duplicate the same events into evidence-index and checkpoint logs.
  7. Add Implementation Constitution, Reference Fidelity Inputs, Feature UI Brief Adoption, Design System Adoption and token strategy, Dispatch Compilation Hints, Review-Risk Notes, and Input Risks From Alignment when their triggers are present. Preserve ui-brief.md, Reference-Implementation, and visual_comparison_or_human_review refs 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.
  8. Re-check constitution, complexity, risk, locked planning decisions, and deep-research PH-### traceability, then run uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify hook validate-artifacts --command plan --feature-dir '<feature-dir>' --format json and fail closed on an incomplete planning package. Run .specify/scripts/powershell/update-agent-context.ps1 -AgentType codex to 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.

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.

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, or C:\Users\11034\.specify\bin\project-cognition.exe validate-build --format json just because sp-specify, sp-plan, or sp-tasks wrote 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 --help followed by C:\Users\11034\.specify\bin\project-cognition.exe update --delta-session '"$DELTA_SESSION_ID"' --reason workflow-finalize --format json when a delta session exists, or C:\Users\11034\.specify\bin\project-cognition.exe update --payload-file '".specify/project-cognition/updates/<update-id>.json"' --reason workflow-finalize --format json when 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_evidence and generated_surface_notes are accepted compatibility aliases.
  • Use known_unknowns only 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 as confidence_notes or boundary.initial_dirty_paths, not as blocking known_unknowns.
  • clean closeout keys on result_state, not update_id, last_update_id, or freshness alone. Treat ready and no_op as clean, partial_refresh as recorded but not fully clean, needs_rebuild as a map-scan/map-build route, blocked as blocked, and recorded as legacy recorded-only output that is never clean completion.
  • Use C:\Users\11034\.specify\bin\project-cognition.exe mark-dirty --reason '"<reason>"' --format json only when inline update cannot complete.
  • sp-map-update is for manual/external maintenance and follow-up repair, not routine cleanup for changes this workflow just made; run /sp-map-scan followed by /sp-map-build only 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.

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-inline and execution_surface: leader-inline; do not spawn planning lanes for light work.
  • Standard mode uses spawn_agent for bounded lanes when dispatch_shape is one-subagent or parallel-subagents.
  • Standard native-unavailable degradation records execution_surface: leader-inline and capability_degraded: true only when no high-risk trigger is present.
  • Heavy or safety-critical blocked work records dispatch_shape: subagent-blocked and execution_surface: none with blocked_reason.
  • Launch all independent lanes in the current parallel-subagents wave before waiting.
  • Suggested bounded lanes include research, data model design, contracts drafting, and quickstart or validation scenario generation.
  • Use wait_agent only at the documented join points before the final constitution and risk re-check and before writing the consolidated implementation plan.
  • Use close_agent after integrating finished subagent results.

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