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"` → Merge config → ModeDispatch
  - [--parallel?] → §ParallelMode
  - [--delegate?] → §DelegatedMode
  - [--auto?] → 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

§VerifyWorkflow → see references/verification.md

§ParallelMode 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>".

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

Execution Modes

Four flags control execution behavior. Defaults loaded via environment action="get-config", CLI flags override.

Config Loading: At entry, call the environment tool to read configuration from foundry-mcp.toml. Returns both implement (mode flags + model) and git (commit cadence, auto_push) sections. If the config file is missing or section not found, use defaults (all false for implement, model=small, auto_push=false).

Model sizes map to Claude tiers: small = haiku, medium = sonnet, large = opus.

Resulting combinations:

Autonomous Behavior (--auto)

Executes tasks continuously without user prompts between each task. Session state persists across /clear boundaries.

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%, 3+ consecutive errors, blocked tasks, task limit

Session tracking: Uses task action="session-config" with commands: start, status, pause, resume, end.

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

Parallel Behavior (--delegate --parallel)

Spawns multiple subagents to execute independent tasks concurrently. File-path conflicts are detected and excluded.

Key behaviors:

• •Uses task action="prepare-batch" to identify eligible tasks
• •Excludes tasks with conflicting file_path metadata
• •Spawns Task(general-purpose, run_in_background=true) per task
• •Collects results via TaskOutput and aggregates with complete-batch
• •Handles partial failures (successful tasks complete, failed tasks remain in_progress)

Batch actions: prepare-batch, start-batch, complete-batch, reset-batch

CRITICAL when using --parallel: Read references/parallel-mode.md before proceeding. Contains required JSON formats for batch operations.

Delegation Behavior (--delegate)

Uses subagent(s) for implementation. Fresh context per task while main agent handles orchestration.

Key behaviors:

• •Spawns Task(general-purpose, model={model}) for each task implementation
• •Model defaults to small (haiku); override with --model medium (sonnet) or --model large (opus)
• •Sequential by default; concurrent with --parallel
• •Main agent handles task lifecycle (status updates, journaling)
• •With --auto: skips user gates; without: preserves all gates

Subagent receives:

• •Task details, file path, acceptance criteria
• •Context from main agent (LSP findings, explore results, previous sibling)
• •Verification scope guidance
• •Constraint: subagent does NOT update spec status or write journals

When to use:

• •Large file changes where you want oversight
• •Complex tasks where fresh context helps
• •Long sessions to preserve main agent context

See also: references/subagent-patterns.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"

This returns:

• •implement section: mode flags (auto, delegate, parallel) + model
• •git section: commit_cadence, auto_push

Merge with CLI flags: CLI flags override config values. If config missing, use defaults (all flags false, model=small, auto_push=false).

Why mandatory: Without this call, the skill may use incorrect defaults for autonomous mode, delegation, and commit behavior.

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 (MANDATORY):

• •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)

Anti-Pattern: Never use text-based numbered lists. Always use AskUserQuestion for structured choices.

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, estimates, 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":

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:

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 autonomous mode usage, 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:

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 notes 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__authoring action="intake-add" title="[Type] description" source="foundry-implement"

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

For capture patterns and examples, see references/note.md

Surface Next Recommendation

Context Awareness: The context-monitor hook automatically warns when context exceeds 85%. If you see [CONTEXT X%] warnings, follow the recommendation to /clear then foundry-implement after completing the current task.

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, you MUST 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 the user controls the workflow pace and prevents runaway execution.

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