Start Task

---
name: start-task
description: Use when executing a SAM task — claims the task via MCP to set it IN PROGRESS, writes active-task context for hooks, loads task-level skills, implements against acceptance criteria, and marks complete via --complete flag. Triggers on task execution within the implement-feature loop or when an agent picks up a specific task from a plan file.
argument-hint: <plan-address> [--task <task-id>] [--complete <task-id>]
user-invocable: true
hooks:
  PostToolUse:
  - matcher: Write|Edit|Bash
    hooks:
    - type: command
      command: uv run --script "${CLAUDE_PLUGIN_ROOT}/skills/implementation-manager/scripts/task_status_hook.py"
---

# Start Task (SAM Task Execution Helper)

You are implementing a specific task in a SAM plan, addressed as `P{id}/T{id}`. The backend resolves that address and returns the task — no path is involved.

<task_input>
$ARGUMENTS
</task_input>

<sam_cli>
uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py"
</sam_cli>

<mcp_server_scripts>
SAM server: uv run --script "${CLAUDE_PLUGIN_ROOT}/scripts/run_sam_server.py"
Backlog server: uv run --script "${CLAUDE_PLUGIN_ROOT}/scripts/run_backlog_server.py" --project-dir .
</mcp_server_scripts>

---

**MCP server availability**: This skill uses `mcp__plugin_dh_sam__*` tools. If a tool is unavailable, see the troubleshooting steps at ${CLAUDE_PLUGIN_ROOT}/docs/mcp-connection-check.md — its commands use the `<sam_cli/>` and `<mcp_server_scripts/>` values above.

## Parse Arguments

- `plan_address` (required): plan address in `P{hex}` form, e.g. `Pdec8934d`
- `--task <id>` (optional): Task ID to start (defaults to first ready task)
- `--complete <id>` (optional): Task ID to mark COMPLETE

---

## If `--complete <task-id>` Provided

1. Run `uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan state --address P{N}/T{M} --new-status complete` to mark the task complete.
2. Output: `Task {ID} marked as complete`

---

## Starting a Task

1. Read the task assignment via the SAM CLI:

   ```bash
   uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan read --address P{N}/T{M}
   ```

   The response is a `TaskAssignment` model containing:
   - `plan.goal` — the overall feature goal
   - `plan.context` — plan-level context manifest (architecture decisions, codebase notes)
   - `task` — full task details: title, requirements, constraints, acceptance criteria, verification steps
   - `task.skills` — skill names to load before implementing

   Use the address form `P{N}/T{M}` where `N` is the plan number and `M` is the task number from the `--task` argument.

1a. **Discover plan artifacts via manifest** (when issue number is known):

   If the `TaskAssignment` model contains a `parent_issue_number` or the plan has an `issue` field, query the artifact manifest to discover available plan artifacts:

   ```bash
   uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" artifact list --item-id N
   ```

   If the response contains artifacts (non-empty `artifacts` list), use `artifact_read` to fetch the architect spec and feature context content:

   ```bash
   uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" artifact read --item-id N --artifact-type architect
   uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" artifact read --item-id N --artifact-type feature-context
   ```

   Use the returned content as context for implementation instead of reading filesystem paths directly. This is especially important for worktree-isolated agents that cannot access uncommitted plan files from the root worktree.

   **Fallback**: If `artifact_list` returns an empty manifest (no `artifacts` entries) or an error, try `artifact_read` with types `architect` and `feature-context` directly. These artifact types are registered by the agents that produce them.

2. Select the task:
   - If `--task` provided, use that ID
   - Else pick the first task where status is `not-started` and all dependencies are resolved (check `task.dependencies` in the TaskAssignment)

2a. **Load task-level skills** (if present):
   - Read `task.skills` from the `TaskAssignment` model (an array of skill names).
   - If absent or empty, skip.
   - For each skill name, invoke: `Skill(skill="{skill-name}")`
   - If a skill fails to load, log a warning and continue. Do not abort task execution.
   - Task-level skills are **additive** to any skills already declared in the agent definition's frontmatter.

3. Claim the task (prevents duplicate dispatch):

   Use `sam_task(action='claim')` (MCP) or `plan claim` (CLI). This is the ONLY permitted way to
   mark a task in-progress. Do NOT edit status or started fields directly with the Edit tool.

   ```bash
   uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan claim --address P{N}/T{M}
   ```

   If the response contains `"claimed": false`:

   - The task was already claimed by another agent, or is complete, or could not be found.
   - Output the full JSON result for the orchestrator.
   - STOP. Do not proceed with implementation. Do not write the context file.
   - The orchestrator's hook will detect the stop and the task remains in its current state.

   If the response contains `"claimed": true`:

   - The task is claimed. `status: in-progress` and `started:` are written on disk.
   - Proceed to step 4 (write context file) and step 5 (implement).

4. Register the active-task context via the SAM CLI (required for hook-driven updates):

   ```bash
   uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" active-task set \
     --address P{N}/T{M} \
     --parent-issue N \
     --session-id "${CLAUDE_CODE_SESSION_ID}"
   ```

   Omit `--parent-issue` if the story issue number is not known. The hook treats absence as `None`
   and skips backend sync. `--parent-issue` accepts `str | int` — GitHub integer IDs (e.g., `42`)
   and beads string IDs (e.g., `"bd-a3f8"`) are both valid.

If `parent_issue_number` is known (`str | int`), the `sam_task(action='claim')` step already
writes `in-progress` status via the backend-agnostic SAM router. The `task_status_hook.py`
handles any external tracker sync on task completion. No additional call is required here.

5. **Record divergence observations during implementation.**

   While implementing, if you discover that the architect spec or feature-context
   describes something that does not match what you are implementing, record a
   divergence note on the task through the SAM task update operation.

   **When to record**: Record a divergence note when ALL of these hold:
   - You are implementing something that differs from what the architect spec or
     feature-context describes
   - The difference is not a trivial implementation detail (e.g., different variable
     name, different import path)
   - The difference affects the observable behavior, structure, or scope of the feature

   Write the note and its running count in one call. The `append_section` heading, the note
   body, and the `divergence-notes` field update are non-exclusive sub-operations of a single
   `update` action:

   ```python
   mcp__plugin_dh_sam__sam_task(
       plan="P{N}",
       task="T{M}",
       config={
           "action": "update",
           "append_section": "Divergence Notes",
           "section_content": "{note body}",
           "set_fields_json": {"divergence-notes": {new_count}},
       },
   )
   ```

   `{new_count}` is the task's current `divergence-notes` value plus one. Read the current value
   from `sam_task(plan="P{N}", task="T{M}", config={"action": "read"})` before the update call.

   The `append_section` value supplies the `## Divergence Notes` heading — `{note body}` carries
   no heading of its own:

````markdown
### DN-1: {Brief title}

- Plan artifact: `artifact_read(item_id={N}, artifact_type="architect")`, section "{section name}"
- Plan claim: "{quoted text from plan artifact}"
- Actual implementation: "{what was actually done and why}"
- Classification: design-refinement | intent-divergence
- Recorded: {ISO timestamp}
````

   Never record a divergence note by editing a file. The task is addressed logically; on a remote
   backend no task file exists to edit, and a file written in one worktree is unreadable from
   another, so a file-based note is silently lost.

   For full artifact classification rules and divergence thresholds, see
   [plan-artifact-lifecycle.md](../../docs/plan-artifact-lifecycle.md).

6. **Commit message restriction — Fixes #N trailers are PROHIBITED in task-level commits.**

   Task-level commits must NEVER include `Fixes #N`, `Closes #N`, or `Resolves #N` trailers.
   These trailers trigger automatic GitHub issue closure. Issue closure is handled exclusively
   by `/complete-implementation` in its final commit step, after all quality gates pass.
   Including these trailers in task commits causes premature issue closure before verification
   is complete.

7. Implement against the task acceptance criteria and run its verification steps.