foundry-implement-auto

Purpose

Run exactly one autonomous implementation phase for a spec in unattended mode, then stop deterministically at the phase boundary or any escalation condition.

Reference:

• Runtime contract: src/foundry_mcp/skills/foundry_implement_auto.py
• Supervisor runbook: docs/guides/autonomy-supervisor-runbook.md
• Agent isolation: docs/guides/autonomy-agent-isolation.md

Flow

[x?]=decision (GATE)=server gate →=sequence ↻=loop !=escalation §=section ref

Entry → [spec_id arg present?]
  → [no] → ! SPEC_ID_MISSING → EXIT
  → [yes] → §Preflight (6 checks)
  → [all pass?]
    → [no] → ! FoundryImplementAutoError + remediation → EXIT
    → [yes] → SessionStart
      → [SPEC_SESSION_EXISTS?]
        → [yes] → §SessionReuse → §StaleSessionRecovery (replay probe) → StepLoop
        → [no]  → StepLoop (fresh session, no stale steps possible)
  → StepLoop (max 200 iterations) ↻
    → task(session-step, command="next")
    → [loop_signal?]
      → [phase_complete] → EXIT success
      → [spec_complete] → EXIT success
      → [paused|failed|blocked_runtime] → ! EXIT escalation
      → [continue] → Dispatch(next_step.type)
        → [implement_task] → §ImplementTask
        → [execute_verification] → §ExecuteVerification
        → [run_fidelity_gate] → §RunFidelityGate
        → [address_fidelity_feedback] → §AddressFidelityFeedback
        → [pause|complete_spec] → EXIT
      → Report outcome → ↻ StepLoop
  → [max_iterations exceeded] → ! LOOP_LIMIT_EXCEEDED → EXIT
→ Emit exit packet

MCP Tooling

All interactions use the Foundry MCP router+action pattern: mcp__plugin_foundry_foundry-mcp__<router>.

Non-Negotiable Rules

1. Zero interaction. Never use AskUserQuestion or any interactive prompt. This skill runs fully unattended. If any required input is missing (spec_id, environment), emit a structured error and EXIT immediately — do not ask, guess, or offer choices.
2. Runtime truth only. Use MCP tool responses as the source of truth for feature flags, posture, and role. Never trust discovery metadata or manifest alone.
3. Server-driven sequencing. The session-step orchestrator is the sole authority on task ordering, phase boundaries, and gate timing. Never infer or override task sequence.
4. No privilege escalation. Never set allow_lock_bypass=true, allow_gate_waiver=true, or request elevated role. Always pass enforce_autonomy_write_lock=true on session start.
5. Fail fast on policy violations. Any preflight failure terminates immediately with structured remediation.
6. Deterministic exit. Stop on phase_complete or spec_complete. Escalate on all other terminal loop_signal values. Never continue on ambiguous state.
7. Bounded execution. Hard limit of max_iterations=200. If exceeded without terminal signal, stop and escalate.

Invocation

claude -p /foundry-implement-auto <spec-id> .

• Arg 1: spec_id — required. The spec to execute. If missing or empty, emit SPEC_ID_MISSING error and EXIT immediately. Never prompt, list specs, or offer choices.
• Arg 2: workspace path (default .).

Argument extraction: After skill expansion, the spec_id appears as text in the user's message — typically the remaining content after the skill name or command tag. To extract it:

1. Look in the user message for any text following /foundry-implement-auto or any <command-name> tag. The spec_id is the first whitespace-delimited token after the skill name.
2. Scan the full conversation turn for a string matching a spec ID pattern (hyphenated slug, e.g., hello-world-python-2026-02-18-001 or hello-world-python-2026-02-18-001.json).
3. Strip any .json suffix if present (e.g., hello-world-python-2026-02-18-001.json → hello-world-python-2026-02-18-001).

If no spec_id is found after checking all locations, emit SPEC_ID_MISSING error and EXIT.

Preflight

All checks must pass before session start. Any failure produces a structured error with error code and remediation hint. Never prompt the user on failure — emit the error and EXIT.

1. Extract spec_id from the user's message. Scan the user's message text in the current conversation turn for the spec_id (see Argument extraction above). If none found, emit SPEC_ID_MISSING error and EXIT. Do not list specs, offer choices, or ask for input.
2. Resolve spec via spec(action="find")
3. Detect action shape (canonical vs legacy)
4. Verify feature flags via server(action="capabilities")
5. Verify posture profile (reject debug, accept unattended/supervised)
6. Verify role authorization
7. Confirm shape detection and role verification are separate probes

Full preflight sequence with error codes: references/preflight.md

Session Start

Start a session with hardened one-phase defaults:

{
  "action": "session", "command": "start", "spec_id": "...",
  "gate_policy": "strict",
  "stop_on_phase_completion": true,
  "auto_retry_fidelity_gate": true,
  "enforce_autonomy_write_lock": true,
  "idempotency_key": "..."
}

These parameters are hardcoded — never configurable, never weakened.

Session reuse and rebase handling: references/session-management.md Stale session recovery: references/session-management.md

Step Loop

Repeat up to max_iterations=200:

1. Call task(action="session-step", command="next", session_id=..., heartbeat=true).
2. Read data.loop_signal — apply deterministic exit (see table below).
3. If no terminal signal, extract data.next_step and dispatch by next_step.type.
4. If next_step.step_proof is present, pass it through verbatim in last_step_result.step_proof.
5. Report outcome via last_step_result envelope (always use the extended transport — see references/step-handlers.md).

Heartbeat protocol: Always pass heartbeat=true on every session-step call (both initial next and reporting via last_step_result). This keeps the session alive during long operations like fidelity gate reviews (~90s each). Without heartbeats, the session will pause with heartbeat_stale after the grace window expires (default 5 minutes).

Step handler details: references/step-handlers.md Verification receipt construction: references/verification-receipts.md Step proof protocol: references/step-proofs.md

Recovered-step entry: When stale session recovery returns a pending step (see references/session-management.md), that step becomes the first iteration of the step loop. Dispatch it through the same step handler path (step 3 above) using the recovered next_step and step_proof. No special handling is needed — the step loop is agnostic to whether a step came from next or replay. The report response provides a fresh proof for subsequent iterations.

Deterministic Exit Table

Error Handling

1. Transport retries: Use task(action="session-step", command="replay") for cached response without re-execution.
2. Spec drift: Surface session-rebase guidance to operator. Only maintainer role can rebase.
3. No direct state mutation. Never call task(action="complete") or task(action="update") directly — the orchestrator manages task state.

Full error code taxonomy: references/error-codes.md

Agent Isolation

The MCP server enforces authorization for MCP tool calls. Native Claude Code tools (Write, Edit, Bash) are constrained by caller hooks and environment configuration.

Allowed: Write/Edit to source files (src/, tests/), Bash for tests/linting, Read/Glob/Grep unrestricted, read-only git operations.

Prohibited: Writing to specs/config/sessions/audit, destructive git operations.

Full isolation rules and guard scripts: references/agent-isolation.md

Exit Payload

The exit packet is the skill's only output. The supervisor uses it to decide next actions — it must be machine-parseable.

Format: Emit one brief human-readable summary line, then a fenced JSON block containing the complete exit packet. The JSON block must be present and complete on every exit — never replace it with a table, bullet list, or prose.

Deterministic exit: <loop_signal>.

{ "spec_id": "<spec-id>", "session_id": "<session-id>", "final_status": "paused | completed | failed", "loop_signal": "phase_complete | spec_complete | paused_needs_attention | failed | blocked_runtime", "pause_reason": "<string or null>", "active_phase_id": "<phase-id or null>", "last_step_id": "<step-id or null>", "gates_satisfied": ["<phase-id>", "..."], "steps_executed": "<count> (<step_type>, ...)", "summary": "<1-2 sentence description of outcome>", "details": { "response_success": true, "error_code": "<string or null>", "recommended_actions": [ { "action": "<action-key>", "description": "<human-readable remediation>", "command": "<canonical MCP tool invocation or null>" } ] } }

Rules:

• Populate every field. Use null for absent values, [] for empty lists.
• recommended_actions is [] when there are no escalation actions — never omit the key.
• Do not add keys beyond those shown above. The schema is fixed.
• The summary line before the JSON block is for human convenience only — supervisors parse the JSON.