sp-implement-teams
Execute implementation through Claude Code Agent Teams when you explicitly want durable team execution.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sp-implement-teams
- metadata
- { "author": "github-spec-kit", "source": "src/specify_cli/integrations/claude/templates/implement-teams.md" }
- description
- Execute implementation through Claude Code Agent Teams when you explicitly want durable team execution.
- argument-hint
- Optional implementation scope or coordination guidance for the Agent Teams run
- compatibility
- Requires spec-kit project structure with .specify/ directory
- user-invocable
- true
02 资源文件 2
- 参考文档references/INDEX.md620 B
- 参考文档references/semantic-work-contract.md55.9 KB
03 SKILL.md 正文
Claude Code Agent Teams
User-facing workflow skill:
/sp-implement-teams
[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read references/semantic-work-contract.md.
Detailed References
Read Reference index before applying shared semantic contracts.
Team Bootstrap Gate
This gate is mandatory and precedes all broad implementation-context recovery.
- After
.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasksresolvesFEATURE_DIRand confirmstasks.mdexists, the first non-prerequisite action is creating or resuming the Claude Agent Team. - Do not read
plan.md,tasks.mdbeyond the minimum existence/status check, project cognition runtime files, compatibility/export files such asPROJECT-HANDBOOK.md, implementation files, or test files before this gate passes. - Do not run validation, edit files, or inspect broad implementation context before this gate passes.
- If a Claude Agent Team for the same feature slug already exists, resume that team and inspect only its ledger and shared task list until the leader has confirmed the team state.
- If
TeamCreate, team resume, shared task records, or native teammate launch is unavailable, stop and report that Claude Agent Teams is unavailable for this/sp-implement-teamsrun. - Do not fall back to
/sp-implement, ordinary subagents, ordinaryAgenttool calls, or leader-inline implementation from this gate.
Boundary
- Claude-only
- Implementation-phase entry point only; use it after
tasks.mdis ready - Use Claude Code's built-in Agent Teams surface, not the Codex runtime surface
- Keep
sp-teamsand Codex extension commands out of Claude guidance - The ordinary
Agenttool must not be used as a teammate substitute./sp-implement-teamsrequires team-managed teammates that join the shared Agent Teams ledger.
When To Use
Use this when:
/sp-implementwould otherwise run aleader-inline-fallbackor native subagent flow- you want durable coordinated execution with a shared task list and explicit teammate messaging
- the implementation work is already decomposed into task-ready execution slices
Shared Contract With /sp-implement
/sp-implement remains the canonical implementation workflow. /sp-implement-teams is the same execution contract with the concrete team-managed work pinned to Claude Code Agent Teams.
When you use /sp-implement-teams, keep the same leader-owned execution semantics that /sp-implement requires:
- keep canonical task status, compact execution state, and one lifecycle record per executed task aligned
- compile and validate a
WorkerTaskPacketjust in time before assigning each team-managed execution task - for implementation-oriented teams flows, preserve the user-visible fields
execution_model,dispatch_shape, andexecution_surface - preserve explicit join behavior, blocker/recovery reporting, event-triggered review, and completion checks
- preserve the team result contract and canonical result file handoff path
- preserve final-completion truthfulness: do not describe
core implementation complete,implementation complete, orready for integration testingas overall feature completion while required E2E, Polish, documentation, quickstart, or validation work remains
Every team-managed task in the teams-backed flow must still behave like an explicit execution packet, not a chat-only summary. Preserve these fields whenever the backend exposes task records, mailbox messages, or equivalent runtime-managed assignments:
- task id and subject
- write set and shared surfaces
- required references and forbidden drift
- explicit verification command or acceptance check
- canonical result handoff path or runtime-managed result channel expectation
- completion-handoff protocol covering start, blocker, and final completion evidence
- platform guardrails such as supported platforms, conditional compilation requirements, or other environment-sensitive constraints
Before Claude Code Agent Teams starts concrete work, ensure the current ready batch is prepared the same way /sp-implement would prepare it:
- the current batch is recorded in canonical task and compact execution state
- each team-managed task has a validated
WorkerTaskPacket - join point expectations and result handoff expectations are explicit
- the team-managed lane cannot be treated as complete from a status flip alone; the leader still needs the promised completion handoff or result evidence
Before assigning team-managed work, preserve the same project cognition compass contract that sp-implement uses:
- run
project-cognition compass --intent implement --query="$ARGUMENTS" --format jsonand include the compass packet in the execution context bundle - Read and carry
epistemic_contract; 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; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; evenverified_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; bounded live evidence and the separate workflow final-claim gate remain required. Carryepistemic_contractin every teammate context packet. - read top-level
minimal_live_readsfirst, then use lane-levelfirst_pass_pathsreasons, evidence hints,verification_hints,followup_surfaces, andbefore_fix_claimchecks - preserve
coverage_diagnosticsas confidence and closeout signals, not route candidates - treat
expansion_refas a normal continuation path and runproject-cognition expand --id <id> --section <section> --format jsononly when coverage state or live evidence requires more map detail - do not infer final edit scope from
minimal_live_readsorfirst_pass_paths; carry them as advisory first-pass evidence routes in every teammate context packet - use the advanced
lexicon -> semantic_intake -> querypath only when explicit concept decisions are needed or coverage cannot be resolved from the default compass packet - in that precision escalation, normalize user input and write a
semantic_intakeobject withworkflow_intent,normalized_query,intent_facets,negative_constraints,alias_interpretations, andopen_semantic_questions - treat
agent_normalization.required=trueas a non-intelligent CLI reminder to writesemantic_intakefrom the alias catalog (raw lexicon ranking is only a bootstrap; action: write_semantic_intake_from_alias_catalog); ifagent_normalizationis omitted, treat it asrequired=false, not as proof that raw lexical ranking is authoritative - keep CJK or mixed CJK/ASCII input in agent-owned normalization even when positive raw lexical matches exist because embedded project tokens do not translate the surrounding user language; the agent still owns translation and
agent_normalizationis advisory guidance, not a route decision - keep
alias_interpretationsobject-shaped, for example{"alias": "<user term>", "meaning": "<project term>", "confidence": "medium"}, never as a string array - build a
query_planwithselected_concepts,rejected_concepts,concept_decisions,covered_facets,missing_facets,match_sources,lexicon_generation_id,expanded_queries,repository_search_terms, and justifiedpaths - derive project-language search terms from the alias catalog before source search; do not search only the raw user words; include component names, state names, file names, command names, UI labels, and route names from candidates, aliases, matched terms, returned paths,
normalized_query, andexpanded_queries - run
project-cognition query --intent implement --query-plan "<query_plan_json>" --format jsononly for that precision escalation, and preserve returned readiness,minimal_live_reads,first_pass_paths, and the task-local bundle in every teammate context packet - if the query reports diagnostics, preserve
warnings,repair_hints, normalizedquery_plan, structurederrors, andexpected_shapeso the leader can repair the plan instead of losing the diagnostics in team chat
The only intended difference is the dispatch path:
/sp-implementmay route the current ready batch through subagents first/sp-implement-teamsforces the concrete team-managed execution through Claude Code Agent Teams for the same batch and join-point semantics- Claude Code Agent Teams must not weaken the tracker, packet, validation, or completion contract
Execution Contract
- Run
.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasksfrom repo root and parseFEATURE_DIRandAVAILABLE_DOCSlist. All paths must be absolute. - If the prerequisites output does not resolve a
FEATURE_DIRwithtasks.md, stop and run/sp-tasksfirst instead of guessing from chat state. - Confirm the current project is using the Claude integration and that
tasks.mdis ready. - Confirm Claude Agent Teams is actually enabled before you try to use it:
- confirm the current Claude Code configuration enables Agent Teams, whether that configuration lives in
settings.jsonor the environment - treat
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSas the canonical Claude Code setting/env key for that feature gate when you need to name the switch explicitly - if the Agent Teams surface is unavailable, or if the first
TeamCreate/ Agent Teams call fails as though the feature is disabled, stop and explicitly remind the user to enable Agent Teams in Claude Code settings or environment instead of continuing with a broken team setup - treat this as a hard prerequisite for
/sp-implement-teams, not as an optional hint
- confirm the current Claude Code configuration enables Agent Teams, whether that configuration lives in
- Create or resume a Claude Agent Team for the feature:
- if a team for the same feature slug is already active, reuse or resume it instead of creating a second parallel team for the same feature
- if the first
TeamCreatecall fails because you are already leading the team, treat that as a recoverable resume signal rather than a terminal failure - inspect the existing team ledger, shared task list, and pending work first, then continue from the recorded ready batch
- do not create a second parallel team for the same feature just to get unstuck
TeamCreate({
team_name: "<feature-slug>",
description: "Implementing <feature>",
agent_type: "researcher"
})
- Treat the team ledger as shared state:
- team membership lives in
~/.claude/teams/{team-name}/config.json - shared tasks live under
~/.claude/tasks/{team-name}/
- team membership lives in
- Before the first
TaskCreate, compile an execution context bundle for the current batch:- run
C:\Users\11034\.specify\bin\project-cognition.exe compass --intent implement --query=\"$ARGUMENTS\" --format jsonfirst and include the compass packet in teammate context - read top-level
minimal_live_readsfirst, then use lane-levelfirst_pass_pathsreasons, evidence hints,verification_hints,followup_surfaces, andbefore_fix_claimchecks - carry
coverage_diagnosticsas confidence and closeout signals, not route candidates - treat
expansion_refas a normal continuation path and runproject-cognition expand --id <id> --section <section> --format jsononly when coverage state or live evidence requires more map detail - do not infer final edit scope from
minimal_live_readsorfirst_pass_paths; carry them as advisory first-pass evidence routes in every teammate context packet - preserve advanced
lexicon -> semantic_intake -> query/project-cognition query --query-planonly as conditional precision escalation when explicit concept decisions are needed or coverage cannot be resolved from the default compass packet - in that precision escalation, derive project-language search terms from the alias catalog before source search; do not search only the raw user words
- candidate selection in the precision escalation must satisfy facet coverage through
covered_facets,missing_facets, andmatch_sources; do not trust top similarity alone - run
C:\Users\11034\.specify\bin\project-cognition.exe query --intent implement --query-plan \"<query_plan_json>\" --format jsononly for that precision escalation - if the precision escalation runs, include returned readiness, the task-local bundle, and only the returned
minimal_live_readsneeded for the lane - include
.specify/project-cognition/status.jsonand.specify/project-cognition/project-cognition.dbas the runtime freshness/store boundary when the teammate must acknowledge the underlying cognition runtime - include compatibility/export files such as
PROJECT-HANDBOOK.mdonly when the task explicitly depends on handbook/export parity, downstream compatibility, or exported handbook wording - for each bundled item, preserve the path or query source, why it matters, and a read order so the teammate knows which query results are primary and which compatibility/export artifacts are supplementary
- run
- Convert the ready implementation slices into explicit shared tasks with
TaskCreate.- every shared task must carry the execution context bundle, not just the task summary
- the task body must tell the teammate which context items are required, what each item is for, and which ones must be read before work starts
- create the full task set before wiring
blockedBy/blocksdependencies; do not point one task at another task record that does not exist yet - every shared task must preserve an explicit execution packet shape, not just prose:
- task id and subject
- write set and shared surfaces
- required references and forbidden drift
- deliverables
- explicit verification command or acceptance check
- canonical result handoff path when the leader expects a file handoff
- completion protocol covering start, blocker, and final completion evidence
- platform guardrails such as supported platforms or required conditional compilation for platform-specific code
- use a standardized task body shape such as:
Task ID: T001
Subject: Protocol update for foreground process payload
Write Set:
- apps/local-agent/src/protocol.rs
- apps/relay-server/src/protocol.rs
Required References:
- .specify/project-cognition/status.json
- project-cognition compass intake packet with top-level `minimal_live_reads` and lane-level `first_pass_paths`
- PROJECT-HANDBOOK.md (only when compatibility/export parity matters)
Deliverables:
- matching protocol definitions on both sides
- focused tests updated
Verification:
- cargo test -p local-agent
Result Handoff:
- write the normalized result envelope to FEATURE_DIR/worker-results/T001.json when the leader requests a file handoff
Completion Protocol:
1. SendMessage({ type: "task_started", task_id: "T001" })
2. run the required verification
3. TaskUpdate({ taskId: "T001", status: "completed" })
4. SendMessage({ type: "task_completed", task_id: "T001", summary: "...", verification: "...", files_changed: [...] })
Platform Guardrails:
- supported_platforms: windows, linux
- use conditional compilation for platform-specific code instead of assuming unix-only APIs are always available
Join Point:
- Join Point 1.1
8b. Team Wave Protocol: plan the team wave before launching teammates.
- Each execution wave must identify:
- implementation teammate ownership for concrete write tasks
- review teammate ownership for shared surfaces, schema/API changes, risky refactors, or cross-module changes
- verification teammate ownership for test execution, E2E checks, build checks, or scripted validation
- leader integration responsibility for final synthesis and next-wave planning
- A wave may omit a review teammate or verification teammate only when the leader records why the batch is low risk and what validation evidence will replace that role.
- Treat the team wave as a collaboration protocol, not just parallel task dispatch.
- Require these team messages when applicable:
interface_changebefore a teammate changes a shared API, schema, protocol, config surface, or boundary contractreview_requestedwhen an implementation teammate finishes a risky or shared-surface taskverification_startedbefore a verification teammate begins the validation laneteam_synthesisfrom the leader after every join point, summarizing completed work, open blockers, interface changes, verification evidence, and the next ready wave
- Encode dependencies and ownership with
TaskUpdate:- use
blockedBy/blocksfor ordering - use
ownerto assign each task to a named teammate - finish all
TaskCreatecalls for the current ready batch first, then wire dependency edges and ownership in a second pass so dependency references never point at missing task records
- use
- Inherit Claude Code's configured subagent model behavior before teammate creation:
- rely on Claude Code's current subagent configuration instead of resolving teammate model choice manually for this workflow
- if
CLAUDE_CODE_SUBAGENT_MODELis configured in the environment, treat it as the active subagent model hint for this run - when subagent model behavior is configured through Claude Code settings, trust that configuration instead of re-deriving or copying model values into teammate setup
- do not derive teammate model from
ANTHROPIC_MODEL - do not ask the user for an explicit teammate model just to launch the team
- do not require local
.claude/agents/<team-name>-<role>.mdteammate definitions solely to force a model choice
- Create the teammates on the native Agent Teams surface:
- this step requires the current Claude Code Agent Teams teammate launch surface, not the ordinary
Agenttool - the ordinary
Agenttool must not be used as a teammate substitute, even if it can read or update shared tasks - if no native Agent Teams teammate launch surface is available, stop instead of falling back to ordinary subagents and report that Agent Teams is unavailable for this run
- reference a generated teammate definition name when the current Claude build supports it and you genuinely need reusable teammate packaging
- prompt-only specialization is acceptable when you do not need a persisted custom teammate definition
- use read-only style teammate definitions for analysis or planning lanes and implementation-oriented teammate definitions for write lanes
- set
team_nameso every teammate joins the same shared ledger - prefer
run_in_background: truefor long-running execution - use
isolation: "worktree"when the lane needs isolated edits
- Verify the launched teammate instead of assuming startup succeeded:
- inspect the team ledger and shared task state after teammate creation and confirm the teammate joined the intended team
- if the runtime cannot use the chosen teammate configuration, simplify the launch path instead of forcing an explicit model override
- if the teammate enters
idlewithout consuming its first probe message, treat startup as failed rather than successful - use a minimal readiness probe message before task assignment so an idle lane is detected early and does not silently absorb a real task
- the readiness probe must confirm the teammate consumed the execution context bundle and can echo a
context_ackcontaining the required paths or read-order items before any real work is assigned
- Tell every teammate to call
TaskList, claim or inspect its assigned work, and useSendMessagefor coordination instead of silent progress.
- ack the context bundle before claiming work; a teammate must not claim work until it has confirmed the required paths
- after claiming work, the teammate must emit an explicit
task_startedmessage before settling into background execution so the leader can distinguish real execution from a silent idle lane - implementation teammates must announce
interface_changebefore changing shared contracts - review teammates must use
review_requested/review_completedmessages instead of relying on task status alone - verification teammates must send
verification_startedandverification_completedwith commands, exit status, and evidence paths
- Track progress through the shared task list:
TaskUpdate({ taskId, status: "in_progress" })TaskUpdate({ taskId, status: "completed" })TaskList()andTaskGet(taskId: "...")to inspect team state- treat
TaskUpdate({ status: "completed" })as necessary but not sufficient when the task promised a completion handoff, verification summary, or result file
- Use
SendMessagefor handoffs, blockers, dependency releases, and context acknowledgement receipts. Approve structured messages such ascontext_ack,shutdown_request, orplan_approval_requestwhen they arrive.
- when execution actually begins, prefer
task_startedmessages with the task id and a short execution note - when blocked, require a
task_blockedmessage naming the blocker, failed assumption, and smallest safe recovery step - when complete, require a
task_completedmessage that includes task id, summary, verification run, files changed, and any residual concern even if the task status is already markedcompleted - when a result handoff path was promised, the teammate must write that result before entering
idle; a completion message without the promised handoff is incomplete
- Keep the same completion discipline as
/sp-implement: do not cross the join point or declare completion until structured handoffs are consumed, the tracker/result state is updated, and every teammate has confirmed the required context bundle for its lane.- after each completed join point or ready batch, immediately re-read the shared task ledger, select the next ready batch and continue automatically
- stop only when no ready work remains, a real blocker stops progress, or an explicit human approval gate is reached
- planned validation tasks are still ready work; if the remaining tasks are executable tests, E2E checks, security verification, quickstart validation, or other scripted validation work already present in
tasks.md, continue automatically instead of asking whether validation should start - do not stop to ask whether validation should start unless a manual-only check or approval step is explicitly recorded in the tracker or task plan
- do not stop after a single completed batch just because the current assignee went idle
- Only after the shared completion contract is fully satisfied may you request shutdown for each teammate, then clean up the team with
TeamDelete().
- if the team has only finished core implementation or is merely ready for integration testing while required E2E, Polish, documentation, or validation tasks remain, report partial progress and keep the remaining work explicit instead of declaring overall feature completion
- a
shutdown_responseor other approval signal means the teammate accepted shutdown, not that it already left the team; confirm active membership before treating cleanup as complete
Output Expectations
Successful runs should leave the user with:
- a Claude-native team config under
~/.claude/teams/{team-name}/config.json - a shared task ledger under
~/.claude/tasks/{team-name}/ - explicit teammate ownership, status transitions, and dependency tracking
- the same implementation lifecycle semantics as
/sp-implement, including tracker continuity, join point visibility, and result handoff discipline - implementation framed as Claude Code Agent Teams execution, not as Codex runtime or extension plumbing
- explicit evidence that teammates inherited Claude Code's configured subagent model behavior when applicable, without ad hoc model-guessing or forced local teammate model files
Claude Agent Teams Teammate Result Contract
- Preferred result contract: WorkerTaskResult contract with status, changed files, validation evidence, blockers, failed assumptions, and recovery guidance.
- Result file handoff path: FEATURE_DIR/worker-results/<task-id>.json
- For filesystem handoffs, use
specify result pathwith the concrete workflow identifiers such as--feature-dir/--task-id,--workspace/--lane-id, or--session-slug/--lane-id. specify result pathemits JSON and does not accept--format; do not append--format.- Normalize teammate-reported statuses like
DONE,DONE_WITH_CONCERNS,BLOCKED, andNEEDS_CONTEXTinto the sharedWorkerTaskResultcontract before the leader accepts the handoff. - Keep
reported_statuswhen normalization occurs so the leader can distinguish raw teammate language from canonical orchestration state. - Wait for every Agent Teams teammate's structured handoff before accepting the join point, closing the team wave, or declaring completion.
- Do not treat an idle teammate as done work; idle without a consumed handoff means the team result channel is still unresolved.
- Do not interrupt or shut down teammate work before the handoff has been written or explicitly reported as
BLOCKEDorNEEDS_CONTEXT. - Treat
DONE_WITH_CONCERNSas completed work plus follow-up concerns, not as silent success. - Treat
NEEDS_CONTEXTas a blocked handoff that must carry the missing context or failed assumption explicitly.
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