foundry-implement

SDD-Implement: Concise Playbook

Overview

• Purpose: Task execution workflow - select tasks, plan implementation, and track progress within an active spec.
• Scope: Single-task execution with user approval at key checkpoints.
• Entry: Invoked via skill system after spec has been identified.

Flow

[x?]=decision · (GATE)=user approval · →=sequence · ↻=loop · §=section ref

- **Entry** → LoadConfig → `environment action="get-config" sections=["autonomy","git"]` → Merge config
  - [unattended?] → Skip user gates
  - Task selection → [selection mode?]
    - [interactive?] → SelectTask
    - [recommend?] → `task action="prepare"` → ShowRecommendation
    - [browse?] → `task action="query"` → (GATE: task selection)
  - Type dispatch → [type?]
    - [verify?] → §VerifyWorkflow
    - [task?] → DeepDive
      - `task action="prepare"` → ExtractContext
      - DraftPlan → (GATE: approve plan)
        - [approved] → PreImpl
        - [changes] → ↻ back to DraftPlan
        - [defer] → **Exit**
      - PreImpl → LSP analysis → Explore subagent
      - `task action="update-status" status="in_progress"` → **Implement**
      - PostImpl → `task action="complete"` → Journal (auto)
      - [success?] → SurfaceNext → `task action="prepare"` → ShowNextTask → (GATE: continue?)
        - [yes] → ↻ back to SelectTask
        - [else] → **Exit**
      - [blocked?] → HandleBlocker → `task action="block"` → (GATE: alternatives)
        - [add-dep?] → `task action="add-dependency"`
        - [add-requirement?] → `task action="add-requirement"`
        - [resolve] → ↻ back to **Implement**
        - [skip] → SurfaceNext
  - [batch execution?] → §BatchExecution (agent decides based on task characteristics)

§VerifyWorkflow → see references/verification.md

§BatchExecution flow:

- **Entry** → `task action="prepare-batch"` → IdentifyEligible
  - [conflicts?] → ExcludeConflicting
  - `task action="start-batch"` → SpawnSubagents
  - For each subagent → Task(general-purpose, run_in_background=true)
  - TaskOutput(block=true) → CollectResults
  - `task action="complete-batch"` → AggregateResults
  - [failures?] → HandlePartialFailure
  - [more batches?] → ↻ back to prepare-batch
  - [else] → **Exit**

Flow notation: see dev_docs/flow-notation.md

---

MCP Tooling

This skill interacts solely with the Foundry MCP server (foundry-mcp). Tools use the router+action pattern: mcp__plugin_foundry_foundry-mcp__<router> with action="<action>".

Router	Key Actions
task	prepare, query, info, start, complete, update-status, block, unblock, add-dependency, add-requirement, session, session-step, session-events, fix-verification-types, gate-waiver, prepare-batch, start-batch, complete-batch, reset-batch
research	node-status, node-execute, node-record, node-findings
journal	add, list
lifecycle	activate, move, complete
spec	find, list
journal	add, list
environment	get-config

Critical Rules:

• The agent never invokes the CLI directly
• Stay inside the repo root, avoid chained shell commands
• NEVER read raw spec JSON outside of MCP helpers

---

Autonomy-Driven Execution

Execution behavior is driven by the autonomy posture configured in foundry-mcp.toml, not by command flags. The posture determines how the skill interacts with users and makes decisions.

Config Loading: At entry, call the environment tool to read configuration. Returns autonomy (posture, security, session defaults) and git (commit cadence, auto_push) sections. If no autonomy config is present, defaults to supervised posture with strict gates.

Posture-to-Behavior Mapping

Posture	User Prompts	Task Selection	Plan Approval	Continue Gate
unattended	Skipped	Auto (recommended)	Auto (use generated plan)	Auto-continue
supervised (default)	AskUserQuestion	User chooses	User approves	User confirms
debug	AskUserQuestion	User chooses	User approves	User confirms

Session Defaults Govern Limits

Limits are sourced from autonomy.session_defaults rather than hardcoded values:

Setting	Effect	Default
max_tasks_per_session	Task count before checkpoint pause	100
max_consecutive_errors	Error threshold before pause	3
stop_on_phase_completion	Pause at phase boundaries	false
auto_retry_fidelity_gate	Auto-retry failed fidelity reviews	false
max_fidelity_review_cycles_per_phase	Cap on fidelity retry loops	3

Agent-Driven Delegation and Parallelism

Use your best judgment on whether to delegate tasks to subagents and whether to parallelize. Consider:

• Task complexity: Simple single-file tasks can run inline. Complex multi-file tasks benefit from delegation (fresh context).
• Batch characteristics: Independent tasks with no file conflicts can run in parallel. Tasks with shared files or sequential dependencies should run serially.
• Context pressure: When context usage is high, delegation to subagents preserves main context.
• Model selection: Use the smallest model appropriate for the task complexity (haiku for simple, sonnet for moderate, opus for complex).

The batch MCP actions (prepare-batch, start-batch, complete-batch, reset-batch) are available tools — use them when the task characteristics warrant it.

Batch execution details: references/parallel-mode.md Subagent patterns: references/subagent-patterns.md

Unattended Posture Behavior

When autonomy.posture.profile is "unattended", the skill executes tasks continuously without user prompts.

Key behaviors:

• Auto-selects recommended tasks via task action="prepare"
• Skips plan approval gates (uses generated plan)
• Auto-continues after task completion
• Pauses on: context >= 85%, consecutive error threshold, blocked tasks, task limit

Session tracking: Uses canonical task action="session" with commands: start, status, pause, resume, end. Step orchestration via task action="session-step" with commands: next, report, replay, heartbeat.

Full documentation: references/autonomous-mode.md Session management: references/session-management.md

---

CRITICAL: Global Requirements

Config Loading (NEVER SKIP)

At entry, IMMEDIATELY call the environment tool before any other action:

mcp__plugin_foundry_foundry-mcp__environment action="get-config" sections='["autonomy", "git"]'

This returns:

• autonomy section: posture profile, security settings (role, lock bypass, gate waiver), session defaults (task limits, error thresholds, fidelity cycles)
• git section: commit_cadence, auto_push

Defaults when no autonomy config present: posture profile = null (supervised behavior), role = "maintainer", gate_policy = "strict", safe limits (100 tasks, 3 errors, 3 fidelity cycles).

Why mandatory: Without this call, the skill cannot determine the correct posture for user interaction gates and session limits.

Spec Reading Rules (NEVER VIOLATE)

The skill only interacts with specs via MCP tools:

• mcp__plugin_foundry_foundry-mcp__task action="prepare"
• mcp__plugin_foundry_foundry-mcp__task action="info"
• mcp__plugin_foundry_foundry-mcp__spec action="find"
• mcp__plugin_foundry_foundry-mcp__task action="query"

Direct JSON access (Read(), cat, jq, grep, etc.) is prohibited.

User Interaction Requirements

Gate key decisions with AskUserQuestion (when posture is supervised or debug):

• Spec selection (when multiple available)
• Task selection (recommended vs alternatives)
• Plan approval (before implementation)
• Blocker handling (alternative tasks or resolve)
• Completion verification (for verify tasks)
• Continuation after task completion (when context < 85% and more tasks remain)

When posture is unattended: All gates above are skipped. The skill auto-selects recommended tasks, uses generated plans, and auto-continues. See references/autonomous-mode.md.

Anti-Pattern: Never use text-based numbered lists. Always use AskUserQuestion for structured choices (in supervised/debug posture).

Anti-Recursion Rule (NEVER VIOLATE)

This skill must NEVER invoke itself or Skill(foundry-implement). The only valid callers are:

• The skill system (entry point)
• Direct user invocation

If you find yourself about to call Skill(foundry-implement) from within this skill, STOP and proceed with the workflow instead. The skill handles the complete task lifecycle - there is no need to re-invoke it.

For detailed context gathering patterns, see references/context-gathering.md For agent delegation patterns (when to use foundry-spec), see references/agent-delegation.md

---

Task Workflow

Execute one task at a time with explicit user approval.

Assumption: The active spec has been identified (either via skill auto-discovery or passed during invocation).

Select Task

• Recommendation path: mcp__plugin_foundry_foundry-mcp__task action="prepare" -> surface task id, file, complexity, blockers
• Browsing path: Use mcp__plugin_foundry_foundry-mcp__task action="query" -> present shortlist via AskUserQuestion

Task Type Dispatch

After selecting a task, check its type to determine the workflow path.

Check task type from the task action="prepare" response or via mcp__plugin_foundry_foundry-mcp__task action="info":

Task Type	Workflow Path
type: "verify"	Go to Verification Task Workflow
type: "research"	Go to Research Node Workflow
type: "task" (default)	Continue to Deep Dive & Plan Approval

CRITICAL: Verification and research tasks must NOT go through the implementation workflow. They require MCP tool invocation, not code changes.

Deep Dive & Plan Approval (Implementation Tasks Only)

Note: This section is for type: "task" only. Verification tasks (type: "verify") use the Verification Task Workflow.

Invoke mcp__plugin_foundry_foundry-mcp__task action="prepare" with the target spec_id. The response contains:

• task_data: title, metadata, instructions
• dependencies: blocking status (can_start, blocked_by list)
• context: previous sibling, parent task, phase, sibling files, journal, dependencies

Treat context as the authoritative source. Only fall back to mcp__plugin_foundry_foundry-mcp__task action="info" when the spec explicitly requires absent data.

For context field details and JSON structure, see references/context-structure.md

Draft execution plan:

1. Confirm previous edits in context.sibling_files
2. Align deliverables with context.parent_task
3. Call out open risks via context.phase
4. Reference context.previous_sibling.summary for continuity

Present plan via AskUserQuestion:

• Options: "Approve & Start", "Request Changes", "More Details", "Defer"

Subagent Guidance (Pre-Implementation Exploration)

Before implementing, use Claude Code's built-in subagents for efficient codebase exploration:

Scenario	Subagent	Thoroughness
Find related files/patterns	Explore	medium
Understand unfamiliar code areas	Explore	very thorough
Complex multi-file investigation	general-purpose	N/A

Example invocation:

Use the Explore agent (medium thoroughness) to find:
- Existing implementations of similar patterns
- Test files for the target module
- Related documentation that may need updates

Benefits of subagent exploration:

• Prevents context bloat in main conversation
• Small model size (haiku) is faster for search operations
• Returns focused results for detailed analysis
• Keeps main context available for implementation

For more subagent patterns including delegation guidance, see references/subagent-patterns.md

LSP Dependency Analysis

Before implementing, use LSP tools to verify dependencies and preview impact:

1. Verify dependencies exist: Use goToDefinition on symbols the task modifies
2. Preview impact: Use findReferences to identify all affected files and call sites
3. Include in plan: Surface LSP findings (usage count, affected files, test coverage) in plan approval
4. Fallback: If LSP unavailable for file type, use Explore agent to find imports and usages

Verification Scoping

Before implementing, check context.parent_task.children for sibling verify tasks to determine appropriate verification scope:

Phase Has Verify Task?	Implementation Task Should
Yes (e.g., "Run tests")	Defer formal testing to verify task. Only do basic checks: imports work, no syntax errors, code compiles
No	Run tests as part of implementation (include results in journal)

Detection: Look for siblings with type: "verify" in the task action="prepare" response's context.parent_task.children array.

Rationale: When the spec author created a verify task, they intended testing to be a separate tracked step. Respect this structure by deferring formal test execution to the verify task.

Include in plan: State verification scope in the execution plan presented for approval (e.g., "Basic verification only - full tests handled by verify-1-1").

Implementation Handoff

Before coding:

mcp__plugin_foundry_foundry-mcp__task action="update-status" spec_id={spec-id} task_id={task-id} status="in_progress" note="context"

During implementation:

• Follow execution plan
• Document any deviations immediately

After implementation:

Mark task complete using the atomic complete action (updates status AND journals automatically):

mcp__plugin_foundry_foundry-mcp__task action="complete" spec_id={spec-id} task_id={task-id} completion_note="Summary of what was accomplished, tests run, verification performed"

This atomically:

1. Updates task status to completed
2. Records completion timestamp
3. Creates a journal entry
4. Auto-journals parent nodes (phases) when they complete

Note (Autonomous Capture)

Proactively add journal entries when you encounter:

• Ideas/improvements beyond current task scope
• Bugs noticed but not immediately actionable
• Documentation gaps or confusing behavior

mcp__plugin_foundry_foundry-mcp__journal action="add" spec_id={spec-id} title="[Type] description" content="Details"

Do NOT prompt the user. Silently capture and continue working.

Surface Next Recommendation

Context Awareness: The context-monitor hook fires when context exceeds 85%. The remaining ~15% is sufficient headroom to finish your current task at full quality. Do not rush, skip steps, or reduce quality in response to this warning. After completing the current task normally, do not start a new task -- instead recommend /clear then foundry-implement.

Surface next recommendation:

mcp__plugin_foundry_foundry-mcp__task action="prepare" spec_id={spec-id}

• Summarize next task's scope and blockers
• If no pending work or spec complete, surface that clearly and exit

MANDATORY: Continuation Gate

After surfacing the next task:

• Unattended posture: Auto-continue to next task (no prompt). Still respect pause triggers (context >= 85%, error threshold, task limit).
• Supervised/debug posture: Prompt the user with AskUserQuestion:
  • When context < 85%: Ask "Continue to next task?" with options: "Yes, continue" / "No, exit"
  • When context >= 85%: Exit with guidance to /clear then foundry-implement
  • When spec is complete: Report completion status and exit (no prompt needed)

This gate ensures supervised users control the workflow pace while unattended execution proceeds autonomously within safety limits.

For post-implementation checklist, see references/checklist.md

---

CRITICAL: Completion Requirements

Never Mark Complete If:

• Basic checks fail (imports, syntax, compiles)
• Tests are failing (only applies if no sibling verify task - see Verification Scoping)
• Implementation is partial
• You encountered unresolved errors
• You couldn't find necessary files or dependencies
• Blockers exist that prevent verification

If Blocked or Incomplete:

• Keep task as in_progress
• Create new task describing what needs resolution
• Document blocker using mcp__plugin_foundry_foundry-mcp__task action="block"
• Present alternatives to user via AskUserQuestion

Dependency Discovery During Implementation

When you discover a missing dependency or new requirement during implementation, record it without leaving the task context:

# Discovered that this task needs another task completed first
mcp__plugin_foundry_foundry-mcp__task action="add-dependency" spec_id={spec-id} task_id={task-id} depends_on={dependency-task-id}

# Discovered a new acceptance requirement (e.g., from testing)
mcp__plugin_foundry_foundry-mcp__task action="add-requirement" spec_id={spec-id} task_id={task-id} requirement="Description of discovered requirement"

Use Cases:

• add-dependency: Task A needs Task B's output → add B as dependency
• add-requirement: Testing revealed an edge case → add as acceptance criterion

Resolving Blocked Tasks

mcp__plugin_foundry_foundry-mcp__task action="unblock" spec_id={spec-id} task_id={task-id} resolution="Brief description"

Completion Journal Requirements

MUST provide journal content describing:

• What was accomplished
• Verification performed (scope depends on sibling verify tasks - see Verification Scoping):
  • If phase has verify tasks: "Basic checks passed (imports, syntax). Full testing deferred to {verify-task-id}"
  • If no verify tasks: "Tests run and results: {summary}"
• Any deviations from plan
• Files created/modified

Example (with sibling verify task - deferred testing):

mcp__plugin_foundry_foundry-mcp__task action="complete" spec_id="my-spec-001" task_id="task-1-2" completion_note="Implemented phase-add-bulk handler. Basic verification: imports work, no syntax errors. Full test run deferred to verify-1-1. Created src/tools/authoring.py handler (200 lines)."

Example (without sibling verify task - full testing):

mcp__plugin_foundry_foundry-mcp__task action="complete" spec_id="my-spec-001" task_id="task-2-3" completion_note="Implemented JWT auth middleware with PKCE flow. All 12 unit tests passing. Manual verification: login flow works in dev environment. Created src/middleware/auth.ts (180 lines) and tests/middleware/auth.spec.ts (45 tests)."

---

Verification Task Workflow

Entry: Routed here from Task Type Dispatch when task has type: "verify"

CRITICAL: Read references/verification.md before proceeding. Contains mandatory skill dispatch rules.

---

Research Node Workflow

Entry: Routed here from Task Type Dispatch when task has type: "research"

Research nodes use AI-powered workflows (chat, consensus, thinkdeep, ideate, deep-research) to investigate questions, gather perspectives, or generate ideas before or during implementation.

Key actions:

1. Check status: research action="node-status"
2. Execute workflow: research action="node-execute"
3. Record findings: research action="node-record"
4. Retrieve findings: research action="node-findings"

Blocking modes:

• hard: Research must complete before dependents can start
• soft (default): Informational - dependents can proceed
• none: Research never blocks

CRITICAL: Read references/research-workflow.md before proceeding. Contains required command syntax and recording parameters.

---

Detailed Reference

For comprehensive documentation including:

Task Execution:

• Context gathering best practices → references/context-gathering.md
• Agent delegation patterns → references/agent-delegation.md
• Deep dive context JSON structure → references/context-structure.md
• Built-in subagent patterns → references/subagent-patterns.md
• Post-implementation checklist → references/checklist.md
• Verification task workflow → references/verification.md
• Research node workflow → references/research-workflow.md
• Note quick capture → references/note.md

Task Lifecycle:

• Task status transitions → references/task-lifecycle.md
• Progress tracking & verification → references/progress-tracking.md
• Journaling decisions & deviations → references/journaling.md
• Spec folder management → references/spec-lifecycle.md

General:

• Troubleshooting → references/troubleshooting.md