SDD-Implement: Concise Playbook Skill

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:

Confirm previous edits in context.sibling_files
Align deliverables with context.parent_task
Call out open risks via context.phase
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:

Verify dependencies exist: Use goToDefinition on symbols the task modifies
Preview impact: Use findReferences to identify all affected files and call sites
Include in plan: Surface LSP findings (usage count, affected files, test coverage) in plan approval
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:

Updates task status to completed
Records completion timestamp
Creates a journal entry
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:

Check status: research action="node-status"
Execute workflow: research action="node-execute"
Record findings: research action="node-record"
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

Agent Skills: SDD-Implement: Concise Playbook

Install this agent skill to your local

Skill Files