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>

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_status:

mcp__plugin_dh_sam__sam_status(plan="<feature_input/>")

Progress Loop

1. Query status:

mcp__plugin_dh_sam__sam_status(plan="P{N}")

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

If parent story issue number is known, 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_ready(plan="P{N}")

Call sam_ready (or backlog_get_ready_sam_tasks) ONCE per batch. Store the returned task list. Loop over the stored list — do NOT call sam_ready again within the loop. After all tasks in the current batch are dispatched and completed, use mcp__plugin_dh_sam__sam_status (~270 chars) to check whether more tasks remain. Only call sam_ready again when the previous batch is fully dispatched and you need the next batch of ready tasks.

3. For each ready task (or batch of ready tasks):

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:

• Route to the agent named in the task's agent field (or resolved from role).
• 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 the agent with a prompt that invokes start-task:

Skill(skill="start-task", args="{task_file_path} --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_claim with no further turns"| Confirm
    Confirm["Confirm task state via<br>mcp__plugin_dh_sam__sam_read(task_id)<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"]

4. 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}",
    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, attempt contract verification against the architect spec:

mcp__plugin_dh_backlog__artifact_read(issue_number=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, return an empty response 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.

5. After all tasks in the current batch complete, call mcp__plugin_dh_sam__sam_status to check plan progress. If tasks remain, return to step 2 to fetch the next batch of ready tasks. Do NOT call sam_ready again until the previous batch is fully dispatched.

Hook behavior on SubagentStop: When a sub-agent finishes, task_status_hook.py marks the task complete in the local task file. After marking the task complete locally, the hook calls backlog_core.github.update_task_status() to sync the completion to the GitHub sub-issue (if github_issue field is set in the task YAML). GitHub sync failure does not affect the hook exit code.

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 write YAML result files to ~/.dh/projects/{project-slug}/plan/T0-baseline-{slug}.yaml and ~/.dh/projects/{project-slug}/plan/TN-verification-{slug}.yaml (resolved via dh_paths.plan_dir()). These files are read by /complete-implementation in its pre-Phase 1 check.

Bookend Artifact Registration

When the parent story issue number is known, 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:

After writing plan/T0-baseline-{slug}.yaml, register it:
  mcp__plugin_dh_backlog__artifact_register(issue_number=N, artifact_type="T0-baseline", path="plan/T0-baseline-{slug}.yaml", agent="t0-baseline-capture")

TN delegation prompt addition:

After writing plan/TN-verification-{slug}.yaml, register it:
  mcp__plugin_dh_backlog__artifact_register(issue_number=N, artifact_type="TN-verification", path="plan/TN-verification-{slug}.yaml", agent="tn-verification-gate")

If the issue number is not known, skip registration. The artifacts remain discoverable via filesystem conventions.

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}")