From gatekeeper
Execute tasks via TDD-first Gatekeeper loop — parallel Agent Teams
How this command is triggered — by the user, by Claude, or both
Slash command
/gatekeeper:cross-teamThis command is limited to the following tools:
The summary Claude sees in its command listing — used to decide when to auto-load this command
Execute the plan orchestrator: validate the plan, find ALL unblocked tasks, check for file scope conflicts, set up per-task sessions, and launch execution. **State management**: Use the Gatekeeper MCP tools for ALL session, token, and signal operations. Do NOT manually generate tokens with `openssl rand` or write `.secret` files. The MCP server is the single source of truth for execution state. Check the output above. Route based on the last status line: - **CROSS_TEAM_FAILED** → follow the recovery steps below - **CROSS_TEAM_OK** → proceed to team orchestration --- ## If CROSS_TEAM_...
Execute the plan orchestrator: validate the plan, find ALL unblocked tasks, check for file scope conflicts, set up per-task sessions, and launch execution.
State management: Use the Gatekeeper MCP tools for ALL session, token, and signal operations. Do NOT manually generate tokens with openssl rand or write .secret files. The MCP server is the single source of truth for execution state.
bash "${CLAUDE_PLUGIN_ROOT}/scripts/cross-team-setup.sh" "${CLAUDE_PLUGIN_ROOT}"
Check the output above. Route based on the last status line:
PLAN_NOT_FOUND — Run /gatekeeper:quest first to generate a plan.
VALIDATION_FAILED — Fix plan.yaml errors (including must_haves) and retry.
CROSS_TEAM_BLOCKED — Tasks are blocked or in_progress. Wait or use /gatekeeper:run-away to reset.
After fixing, run /gatekeeper:cross-team again.
You are now the Lead Orchestrator. You do NOT write code. You coordinate worker teammates.
Read the orchestrator prompt template and follow it:
prompt_template = open('${CLAUDE_PLUGIN_ROOT}/scripts/team-orchestrator-prompt.md').read()
Before dispatching any agents, read .planning/PROJECT.md and extract the vision context:
project_md = open('.planning/PROJECT.md').read()
# Extract key sections for the compact PROJECT_VISION_CONTEXT block
# that gets injected into every agent prompt (see team-orchestrator-prompt.md)
This is mandatory. If .planning/PROJECT.md does not exist, run /gatekeeper:quest first.
If .planning/codebase/ exists (brownfield), also read and extract summaries from STACK.md, ARCHITECTURE.md, CONVENTIONS.md, TESTING.md for the PROJECT_CODEBASE_CONTEXT block injected into all agent prompts.
After loading project context, encrypt all task spec files and skeleton files for progressive access control. This ensures the orchestrator must actually complete dependency tasks before accessing downstream task specs.
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__encrypt_task_files(
session_id="{session_id}",
project_dir="{absolute path to project}",
plan_path=".claude/plan/plan.yaml"
)
After encryption:
ENCRYPTED placeholdersLOCKED placeholdersdecrypt_task_file(session_id, task_id) — this only succeeds after all dependency tasks have GK_COMPLETE tokensBefore spawning any agent for a task, decrypt it first:
decrypted = mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__decrypt_task_file(
session_id="{session_id}",
task_id="{task_id}"
)
# decrypted.task_spec contains the full task-*.md content
# decrypted.skeleton_files contains the unlocked file paths and content
Before dispatching any task, create a Gatekeeper session via MCP. Generate the session ID as gk_YYYYMMDD_XXXXXX (date + 6 hex chars).
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__create_session(
session_id="gk_{date}_{hex}",
project_dir="{absolute path to project}",
test_command="{test command from plan.yaml}"
)
Use this session_id for ALL subsequent MCP calls during this execution run.
The per-phase flow is: Phase Assessor (defines integration contracts + format specs) → per-task: Tester → Assessor (TQG token) → Executor → Verifier (GK token) → all tasks done → Phase Verifier (PVG token) → next phase.
Phase 0.5 — Phase assessment gate (once per phase, before testers):
Task(subagent_type='gatekeeper:phase-assessor') per phase (model: opus, HAS write access for specs)PHASE_ASSESSMENT_PASS:{phase_id}:{summary} with PAG token or PHASE_ASSESSMENT_FAILmcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="PHASE_ASSESSMENT_PASS",
session_id="{session_id}",
phase_id={phase_id},
agent_id="phase-assessor",
context={"summary": "{summary}"}
)
Phase 1 — Spawn tester agents for each dispatched task:
Task(subagent_type='gatekeeper:tester') per task (model: sonnet, HAS web access)TESTS_WRITTEN:{task_id} or TESTS_WRITE_FAILED:{task_id}:{reason}mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="TESTS_WRITTEN", # or "TESTS_WRITE_FAILED"
session_id="{session_id}",
task_id="{task_id}",
agent_id="tester"
)
Phase 1.4 — Tick check (before assessment) for each task with ready tests:
Task(subagent_type='gatekeeper:tick-finder') per task (model: opus, HAS write access)TICK_CHECK_FAIL: inject crash markers into offending files, re-spawn tester with tick list — do NOT proceed to assessmentTICK_CHECK_PASS: proceed to assessment gatemcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="TICK_CHECK_PASS", # or "TICK_CHECK_FAIL"
session_id="{session_id}",
task_id="{task_id}",
agent_id="tick-finder",
context={"phase": "post-tester", "ticks_found": {count}}
)
Phase 1.5 — Assessment gate for each task with ready tests:
Task(subagent_type='gatekeeper:assessor') per task (model: opus, NO write access)ASSESSMENT_PASS:{tqg_token}:{summary} or ASSESSMENT_FAIL:{issues}mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__submit_token(
token="{tqg_token}",
session_id="{session_id}",
task_id="{task_id}"
)
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="ASSESSMENT_PASS",
session_id="{session_id}",
task_id="{task_id}",
agent_id="assessor",
context={"summary": "{summary}"}
)
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_evolution_attempt(
task_id="{task_id}",
attempt_number={n},
outcome="FAILURE",
session_id="{session_id}",
metrics={"reason": "{issues}"}
)
Phase 2 — Spawn executor agents for each task that passed assessment:
Task(subagent_type='gatekeeper:executor') per task (model: haiku, no web access)IMPLEMENTATION_READY:{task_id} or TASK_FAILED:{task_id}:{reason}mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="IMPLEMENTATION_READY", # or "TASK_FAILED"
session_id="{session_id}",
task_id="{task_id}",
agent_id="executor"
)
Phase 2.4 — Tick check (before verification) for each task with ready implementation:
Task(subagent_type='gatekeeper:tick-finder') per task (model: opus, HAS write access)TICK_CHECK_FAIL: inject crash markers into offending files, re-spawn executor with tick list — do NOT proceed to verifierTICK_CHECK_PASS: proceed to verification gatemcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="TICK_CHECK_PASS", # or "TICK_CHECK_FAIL"
session_id="{session_id}",
task_id="{task_id}",
agent_id="tick-finder",
context={"phase": "post-executor", "ticks_found": {count}}
)
Phase 2.5 — Verification gate for each task with ready implementation:
Task(subagent_type='gatekeeper:verifier') per task (model: opus, NO write access)dev_server_url (MANDATORY)dev_server_url MUST be provided to every verifier. Visual verification via Playwright is required for ALL tasks, including backend/CLI tasks. The plan must define a dev_server_command and each task must have a playwright_url.VERIFICATION_PASS, VERIFICATION_FAIL:{critique}, or VERIFICATION_PAUSED:playwright_unavailablemcp__plugin_gatekeeper_gatekeeper-evolve-mcp__submit_token(
token="GK_COMPLETE_{32 hex chars}",
session_id="{session_id}",
task_id="{task_id}"
)
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="VERIFICATION_PASS",
session_id="{session_id}",
task_id="{task_id}",
agent_id="verifier"
)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/plan_utils.py" .claude/plan/plan.yaml --complete-task {task_id} --token {gk_token}
VERIFICATION_PAUSED:playwright_unavailable: STOP all execution. Use AskUserQuestion to alert the user that Playwright is unavailable and request intervention. Do NOT proceed, do NOT skip visual verification, do NOT mark any tasks complete. Resume only after user confirms Playwright is working.mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_evolution_attempt(
task_id="{task_id}",
attempt_number={n},
outcome="FAILURE",
session_id="{session_id}",
metrics={"critique": "{critique}", "failure_type": "test_issue|impl_issue"}
)
Handle verify failures (test problem suspected):
Task(subagent_type='gatekeeper:tester', prompt="mode=reassess ...")TESTS_WRITTEN:{task_id} (tests fixed) or TESTS_OK:{task_id}:... (tests are fine)mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__get_evolution_context(
task_id="{task_id}"
)
Mark tasks completed — use MCP for token submission, plan_utils for plan.yaml update:
# Generate token hex (32 chars)
token_hex = random 32 hex chars
gk_token = "GK_COMPLETE_{token_hex}"
# Submit via MCP (source of truth for execution state)
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__submit_token(
token=gk_token,
session_id="{session_id}",
task_id="{task_id}"
)
# Update plan.yaml (source of truth for plan state)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/plan_utils.py" .claude/plan/plan.yaml --complete-task {task_id} --token {gk_token}
Phase verification gate after marking a task complete:
integration_check: true:mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__check_phase_integration(
phase_id={phase_id},
required_artifacts=["{list of artifact paths from phase must_haves}"],
project_dir="{project_dir}"
)
Task(subagent_type='gatekeeper:phase-verifier', model='opus',
prompt='phase_id: {id}, integration_specs_dir: .claude/plan/phases/phase-{id}/integration-specs/, ...')
PHASE_VERIFICATION_PASS:{phase_id}: submit PVG token via MCP:
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__submit_pvg_token(
session_id="{session_id}",
token_value="PVG_COMPLETE_{32 hex chars}",
phase_id={phase_id},
integration_check_passed=true
)
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signal(
signal_type="PHASE_VERIFICATION_PASS",
session_id="{session_id}",
phase_id={phase_id},
agent_id="phase-verifier"
)
PHASE_VERIFICATION_FAIL with CRITICAL issues: fix before next phaseCheck for newly unblocked tasks after each completion:
# Use MCP for next task suggestion
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__get_next_task(
session_id="{session_id}"
)
# Cross-reference with plan.yaml for full task details
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/get-unblocked-tasks.py" .claude/plan/plan.yaml
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__get_token_status(
session_id="{session_id}"
)
mcp__plugin_gatekeeper_gatekeeper-evolve-mcp__close_session(
session_id="{session_id}"
)
.claude/gk-team-active.claude/gk-sessions/.claude/plan-lockedplan.yaml metadata.hyperphase: true/gatekeeper:hyperphaseopenssl rand or write .secret filesmcp__plugin_gatekeeper_gatekeeper-evolve-mcp__submit_token or submit_pvg_tokenmcp__plugin_gatekeeper_gatekeeper-evolve-mcp__record_agent_signaldev_server_url to verifiers. If a verifier returns VERIFICATION_PAUSED:playwright_unavailable, STOP all execution and ask the user for help via AskUserQuestion. Do NOT skip visual verification.tests.qualitative.playwright_url — if missing, the plan is incompletenpx claudepluginhub rhizomaticrobin/gatekeeper --plugin gatekeeper