Implement Feature (SAM Workflow Execution) Skill

Implement Feature (SAM Workflow Execution)

As you review code, update your agent memory with patterns, conventions, and recurring issues you discover.

This workflow continues from add-new-feature. It executes tasks from a SAM task file until complete (or blocked).

<feature_input>$ARGUMENTS</feature_input>

MCP server availability: This skill uses both mcp__plugin_dh_backlog__* and mcp__plugin_dh_sam__* tools. Both servers take 10–30 seconds to initialize after a session restart. If either is unavailable or ToolSearch reports "still connecting", follow mcp-connection-check.md before proceeding.

Resolve Task File

Rules:

If <feature_input/> ends with .md, treat it as the task file path and extract the plan address P{N} from the filename (e.g., plan/tasks-3-integrate-sam-schema.md → P3).
Otherwise, treat it as a feature slug (or partial slug) and resolve plan address via sam_plan:

mcp__plugin_dh_sam__sam_plan(config={"action": "status"}, plan="<feature_input/>")

Progress Loop

Query status:

mcp__plugin_dh_sam__sam_plan(config={"action": "status"}, plan="P{N}")

After receiving the status response, extract and store the autonomy mode:

autonomy_mode = status["autonomy"]

This value governs gate behavior throughout the remainder of the Progress Loop for this plan. Pre-existing plans that omit the autonomy field return "full_auto" (the Pydantic default), so no gate fires and the loop behaves identically to the previous behavior.

If tasks remain, query ready tasks once and store the result as the current batch:

If parent story issue number is known (str | int — GitHub integer ID such as 42 or beads string ID such as "bd-a3f8"), prefer the MCP tool:

backlog_get_ready_sam_tasks(parent_issue_number=N)
Output shape: {"feature": "...", "ready_tasks": [...], "count": N}
Falls back to local cache if GitHub unavailable.

If parent issue number is unknown, use the SAM MCP tool:

mcp__plugin_dh_sam__sam_plan(config={"action": "ready"}, plan="P{N}")

Call sam_plan(action='ready') (or backlog_get_ready_sam_tasks) ONCE per batch. Store the returned task list. Loop over the stored list — do NOT call sam_plan(action='ready') again within the loop. After all tasks in the current batch are dispatched and completed, use mcp__plugin_dh_sam__sam_plan(config={"action": "status"}, plan="P{N}") to check whether more tasks remain. Only call sam_plan(action='ready') again when the previous batch is fully dispatched and you need the next batch of ready tasks.

Dispatch based on autonomy_mode:

If autonomy_mode == "per_task":

Process tasks from the ready list one at a time:

Dispatch task N via a single Agent call (not TeamCreate).
Complete steps 4, 4a, 4b for task N.
Present the per-task gate (after step 4b, described below) before dispatching task N+1.

Else (autonomy_mode is "full_auto" or "checkpoint"):

When multiple tasks are simultaneously ready (non-zero count with 2+ tasks in the ready list), dispatch them in parallel using TeamCreate:

TeamCreate(team_name: "impl-{slug}")

The team name follows the pattern impl-{slug} where {slug} is the feature slug derived from the task file path. This team name is reused by complete-implementation for QG agent dispatch and is shut down in the Final Step of that skill.

Spawn one teammate per ready task. When only one task is ready, a single Agent call is acceptable. TeamCreate is the standard parallel dispatch mechanism — use it whenever 2+ tasks are ready at the same time.

For each task being dispatched:

Always dispatch dh:task-worker as the subagent_type. The agent: field in the task YAML is NOT a routing directive for the orchestrator — it is read internally by task-worker via the SAM MCP (sam_task action) and passed to profile_load to specialize task-worker's behavior. The orchestrator passes only the task reference (plan address + task ID).
Check the task's skills list from the ready-tasks JSON output.
If skills is non-empty, include skill-loading instructions in the delegation prompt:

Before starting work, load these skills: {comma-separated skill names}.
For each skill, call: Skill(skill="{skill-name}")

If skills is empty or missing, do not add skill-loading instructions (backward compatible).
Launch dh:task-worker with a prompt that invokes start-task:

Skill(skill="start-task", args="{plan_address} --task {task_id}")

Note: Task-level skills are additive to agent-level skills. If the agent definition already declares skills via its frontmatter, task-level skills supplement them (they do not replace agent-level skills). Loading the same skill twice is a no-op.

Agent Health Check (While Waiting)

After dispatching a batch, the orchestrator waits for completion messages. Trigger a health check when any of these occur:

No message received from any dispatched agent after ~10 minutes of silence
User asks about agent status
git log shows no new commits when implementation work should be in progress

Never read JSONL session files directly in the orchestrator context. Session files can exceed 40K tokens. Always delegate to agentskill-kaizen:transcript-analyst with an empty context window.

Session JSONL files are at ~/.claude/projects/{project-slug}/*.jsonl, filterable by agentId field. The {project-slug} is the absolute project path with / replaced by - (e.g. /home/user/repos/myproject → -home-user-repos-myproject).

flowchart TD
    Trigger([Health check triggered]) --> Spawn
    Spawn["Task is session health summary<br>subagent_type='agentskill-kaizen:transcript-analyst'<br>Context: agent name or teammate ID to check,<br>JSONL dir ~/.claude/projects/{project-slug}/*.jsonl<br>Report: last turn timestamp, last tool call,<br>verdict of crashed / idle / active"]
    Spawn --> Verdict{Analyst verdict}
    Verdict -->|"Crashed — session ended abruptly<br>after sam_task(action=claim) with no further turns"| Confirm
    Confirm["Confirm task state via<br>mcp__plugin_dh_sam__sam_task(plan, task, config={action:read})<br>Verify task is still CLAIMED"] --> Respawn
    Respawn["Re-spawn agent with same task file path and task ID<br>SubagentStop hook updates status on completion"]
    Verdict -->|"Idle — no tool calls for 5+ min<br>agent appears stuck mid-task"| TeamCheck{Agent is a teammate<br>in an active team?}
    TeamCheck -->|Yes| SendMsg["SendMessage to teammate<br>'Are you blocked? What is your current status?'<br>Wait 2 minutes for response"]
    TeamCheck -->|"No — spawned via single Agent call"| Respawn
    SendMsg --> MsgCheck{Response received<br>within 2 min?}
    MsgCheck -->|Yes — agent responds| Waiting
    MsgCheck -->|No — still silent| Respawn
    Verdict -->|"Active — tool calls within last 2–3 min"| Waiting
    Waiting[Continue waiting] --> Later["Re-check after 5–10 min<br>if completion message still absent"]

After each agent returns, check its output for a <concerns> block. If present, append each concern to the backlog item as a checklist entry:

mcp__plugin_dh_backlog__backlog_groom(
    selector="#{issue}",  # {issue} is str | int — GitHub integer ID or beads string ID
    section="Concerns",
    content="- [ ] {concern text} (reported by {agent_name} on {task_id})",
    append=True
)

Concerns accumulate across all task agents. They feed into the validation stage in /complete-implementation — each verified concern becomes a new backlog item.

4a. If a parent issue number is known (str | int — GitHub integer ID or beads string ID), attempt contract verification against the architect spec:

mcp__plugin_dh_backlog__artifact_read(item_id=N, artifact_type="architect")

If artifact_read returns content (architect spec exists), resolve the files modified by the just-completed task:

git diff --name-only HEAD~1..HEAD

Then spawn the contract-verification agent:

Agent(
    subagent_type="dh:contract-verification",
    prompt="""
Verify the just-completed task against the architect spec.

Task ID: {task_id}
Plan: {plan_address}
Architect spec: {architect_spec_content_or_path}
Modified files:
{modified_files_list}

Read the architect spec's Component Design and Type System Design sections.
For each modified file, grep for function/class definitions and extract actual signatures.
Compare against the contracts defined in the spec.
Report mismatches in a <concerns> block with severity CONTRACT VIOLATION (signature mismatch)
or CONTRACT GAP (spec defines contract but implementation is silent).
If no mismatches are found, output `No contract concerns — all contracts in scope are satisfied.` with no <concerns> block.
"""
)

If the contract-verification agent returns a <concerns> block, append each concern to the backlog item with a CONTRACT: prefix:

mcp__plugin_dh_backlog__backlog_groom(
    selector="#{issue}",
    section="Concerns",
    content="- [ ] CONTRACT: {concern text} (reported by contract-verification on {task_id})",
    append=True
)

If artifact_read fails or returns no content (no architect spec for this issue), skip step 4a entirely. Proportional quality gate items without an architect spec automatically skip this step with zero overhead.

4b. Shut down the completed teammate

After concerns and contract verification are handled for a task, send a shutdown request to the agent if it was dispatched as a teammate via TeamCreate:

SendMessage(to="{teammate_name}", message={"type": "shutdown_request"})

This terminates the teammate immediately rather than leaving it idle. Idle teammates emit periodic notifications and hold resources without contributing further work.

Skip when: the agent was dispatched via a single Agent call (not TeamCreate) — subagents terminate automatically when their prompt completes.

Commit Ownership

Commit responsibility depends on which execution mode is active.

Same-worktree mode (default — no isolation flag): The orchestrator owns all commits. Commit timing depends on autonomy_mode:

per_task mode: The Per-task Confirmation Gate (below) ensures only one task runs at a time. Commit after step 4b, before dispatching the next task — no concurrent agents are writing:
```
git add -A
git commit -m "<type>(task): {task_id} — {task_title}"
```
full_auto and checkpoint modes: Multiple tasks in a batch execute concurrently. Do NOT commit after each individual step 4b — other batch agents may still be writing to the worktree. Commit once after step 5 confirms all tasks in the current batch are complete:
```
git add -A
git commit -m "<type>(task-batch): {plan_address} — {task_ids}"
```

In both cases, choose <type> to match the dominant change in the committed work (feat, fix, docs, refactor, etc.). Do NOT include Fixes #N, Closes #N, or Resolves #N trailers — see start-task/SKILL.md step 6. Issue closure is handled exclusively by /complete-implementation.

Why the orchestrator commits: Multiple agents write to the same filesystem concurrently. An agent committing mid-task risks including another agent's in-progress changes. The orchestrator is the only actor that knows when a batch is fully settled, making it the safe commit point.

Isolated-worktree mode (via /dh:work-milestone): Each agent owns its own commits. The agent commits in its isolated worktree after completing its task. The orchestrator merges each worktree back when the completion message arrives. The orchestrator does NOT issue commit calls in this mode.

Per-task Confirmation Gate (active when autonomy_mode == "per_task" only):

After task N completes (steps 4 through 4b finished), before dispatching task N+1:

Display a compact task result summary:
- Task ID and title
- Completion status (complete / error)
- Any concerns raised (from the concerns block check in step 4)
Present a confirmation prompt to the user. The exact wording is implementation-defined; examples include "Ready to dispatch the next task? (yes/no)" or a numbered menu of options. The prompt must make clear which task will be dispatched next (task ID and title).
Await explicit user confirmation before proceeding.
- If confirmed: dispatch the next task from the stored batch (or query the next batch if the batch is exhausted).
- If declined or cancelled: stop the Progress Loop. Report the current plan state via mcp__plugin_dh_sam__sam_plan(config={"action": "status"}, plan="P{N}") and exit.

Skip this gate when autonomy_mode is "full_auto" or "checkpoint".

After all tasks in the current batch complete, call mcp__plugin_dh_sam__sam_plan(config={"action": "status"}, plan="P{N}") to check plan progress. If tasks remain, return to step 2 to fetch the next batch of ready tasks. Do NOT call sam_plan(action='ready') again until the previous batch is fully dispatched.

5a. Wave-Completion Confirmation Gate (active when autonomy_mode == "checkpoint" only):

After all tasks in the current batch complete and sam_plan(action='status') confirms that tasks remain (step 5 result: tasks remaining > 0):

Display a compact wave-completion summary:
- Number of tasks completed in this wave
- Current plan completion percentage (from status["completion_pct"])
- Number of tasks remaining
- Next ready tasks (from status["ready_tasks"] list — task IDs only)
Present a confirmation prompt to the user. The exact wording is implementation-defined; examples include "Wave complete. Proceed with the next wave? (yes/no)".
Await explicit user confirmation before calling sam_plan(action='ready') again.
- If confirmed: proceed to step 2 to fetch the next batch.
- If declined or cancelled: stop the Progress Loop. Report the current plan state and exit. The plan remains in its current state and can be resumed later.

Skip this gate when autonomy_mode is "full_auto" or "per_task".

Note: under "per_task", per-task gates already fire for each task; no additional wave gate is needed.

Hook behavior on SubagentStop: When a sub-agent finishes, task_status_hook.py marks the task complete via the SAM MCP server (backend-agnostic). After updating the SAM state, the hook syncs completion to the external tracker (if parent_issue_number is set in the active-task context). External tracker sync failure does not affect the hook exit code. parent_issue_number accepts str | int — GitHub integer IDs and beads string IDs are both supported.

Bookend Task Ordering

When the plan contains acceptance-criteria-structured entries, swarm-task-planner generates T0 and TN bookend tasks. No special handling is needed in this loop — existing readiness logic dispatches them in the correct order automatically:

T0 has priority: 1 and dependencies: [], so it is the first ready task and dispatches before any implementation task.
TN has dependencies: [all non-bookend task IDs], so it becomes ready only after all implementation tasks complete and dispatches last.

T0 runs agent t0-baseline-capture. TN runs agent tn-verification-gate. Both agents register their results as artifacts via artifact_register (types T0-baseline and TN-verification). These artifacts are read by /complete-implementation in its pre-Phase 1 check via artifact_read.

Bookend Artifact Registration

When the parent story issue number is known (str | int — GitHub integer ID or beads string ID), include artifact_register instructions in each bookend task's delegation prompt so the bookend artifacts are registered in the issue's artifact manifest:

T0 delegation prompt addition:

Register the baseline content directly via MCP (no file write):
  mcp__plugin_dh_backlog__artifact_register(item_id=N, artifact_type="T0-baseline", content=<baseline yaml string>, agent="t0-baseline-capture")

TN delegation prompt addition:

Register the verification content directly via MCP (no file write):
  mcp__plugin_dh_backlog__artifact_register(item_id=N, artifact_type="TN-verification", content=<verification yaml string>, agent="tn-verification-gate")

If the issue number is not known, skip registration.

Variant: Worktree Isolation

Worktree isolation variant: For milestone-scoped execution where each item gets its own worktree, use /work-milestone instead. See work-milestone SKILL.md.

Completion Gate

When all tasks show COMPLETE, invoke:

Skill(skill="complete-implementation", args="{task_file_path}")

Agent Skills: Implement Feature (SAM Workflow Execution)

Install this agent skill to your local

Skill Files