Implementation Manager

---
name: implementation-manager
description: Manages feature implementation task state via SAM MCP tools. Use when querying task status, listing ready tasks, claiming tasks for execution, updating task timestamps, or coordinating multi-task feature rollout. Activated by the /dh:execution orchestrator to track progress — also activates directly when managing tasks or configuring hook profiles.
user-invocable: false
disable-model-invocation: false
---

# Implementation Manager

## Current Task Context

**Available features (if in project with plan/ directory):**
!`uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan list 2>/dev/null`

**Active task context (if any):**
!`python3 -c "from dh_paths import context_dir; import os; cdir = context_dir(os.environ.get('CLAUDE_CODE_SESSION_ID', '')); files = list(cdir.glob('active-task-*.json')) if cdir.exists() else []; print(files[0].read_text() if files else 'No active task')" 2>/dev/null || echo "No active task"`

A skill for querying and managing feature implementation tasks. Provides programmatic access to task status for orchestrators coordinating multi-step feature implementations.

## SAM MCP Tool Usage

Use the configured provider's native interface for native state. In a Beads workspace, use `bd` directly for CRUD, readiness, claims/status, and dependencies. Use SAM MCP or the DH CLI adapter for structured SAM plans, task metadata, artifacts, dispatch, and validation that `bd` does not provide. See [Beads and workflow usage](../../docs/beads-and-workflow-usage.md).

### Structured SAM Commands

#### list

List all features with tasks tracked in the project's `plan/` directory:

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan list
```

**Output:**

```json
{
  "items": [
    {
      "plan_id": "P1",
      "feature": "prepare-host",
      "task_count": 8
    }
  ],
  "count": 1
}
```

#### status

Get detailed status for a specific feature:

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan status --plan-address P1
```

**Output:**

```json
{
  "feature": "prepare-host",
  "total_tasks": 8,
  "completed": 8,
  "in_progress": 0,
  "not_started": 0,
  "ready_tasks": [],
  "tasks": [
    {
      "id": "1.1",
      "name": "Add Data Models to shared/models.py",
      "status": "complete",
      "dependencies": [],
      "agent": null,
      "priority": 1,
      "complexity": "low"
    }
  ]
}
```

#### ready-tasks

List tasks ready for execution (dependencies satisfied):

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan ready --plan-address P1
```

**Output:**

```json
{
  "feature": "prepare-host",
  "ready_tasks": [
    {
      "id": "1.3",
      "name": "Create core/prepare.py Business Logic",
      "agent": "{resolved_agent}"
    }
  ],
  "count": 1
}
```

#### read

Read full plan data including task fields and context:

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan read --address P1
```

#### claim

Claim a task in-progress (prevents duplicate dispatch):

```bash
uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan claim --address P1/T01
```

Returns `{"claimed": false, "error": "..."}` if task is already claimed or not found.

#### update

Update plan-level fields (e.g., context manifest):

```text
mcp__plugin_dh_sam__sam_plan(config={"action": "update", "context": "Context Manifest content"}, plan="P1")
```

Note: the CLI equivalent is `plan update --plan-address P1 [...]`, but the specific flag for
setting the plan-level `context` field is not enumerated in the current CLI-parity mapping —
verify the exact flag via `uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan update --help`
before converting this call site to CLI form.

## Task Schema

Tasks are represented as YAML frontmatter fields, defined in `sam_schema/core/models.py`. The SAM MCP tools validate all fields — do not parse tasks directly from storage.

```yaml
---
task: T01
title: "Task title"
status: not-started
agent: {resolved_agent}
dependencies: []
priority: 1
complexity: medium
accuracy-risk: low
skills: []
---
```

### Status Values

- `not-started` — task has not been started
- `in-progress` — task is claimed and being executed
- `complete` — task is done
- `blocked` — task cannot proceed
- `deferred` — task is intentionally postponed
- `skipped` — task was bypassed without execution
- `failed` — task execution ended in failure

### Dependency Resolution

A task is "ready" when:

1. Status is `not-started`
2. All dependencies have status `complete`, `deferred`, or `skipped` (or no dependencies)

## Hook Integration

The `task_status_hook.py` script provides automated task status tracking via Claude Code hooks.

### Hook Configuration

| Command              | Hook Event   | Matcher             | Purpose                                        |
| -------------------- | ------------ | ------------------- | ---------------------------------------------- |
| `/dh:execution` | SubagentStop | (all)               | Mark task COMPLETE, add Completed timestamp    |
| `/dh:start-task`        | PostToolUse  | `Write\|Edit\|Bash` | Update LastActivity timestamp during execution |

### How It Works

**SubagentStop (Task Completion)**:

When `/dh:execution` launches a sub-agent via `/start-task {plan} --task {id}`, the SubagentStop hook fires when the sub-agent completes. The hook script:

1. Parses the original prompt to extract the plan address and task ID
2. Updates task status from `IN PROGRESS` to `COMPLETE`
3. Adds `**Completed**: {ISO timestamp}` to the task section

**PostToolUse (Activity Tracking)**:

Only the local-YAML `ContextBackend` writes this file; the memory, GitHub, and beads backends persist `ActiveTaskContext` in their own provider and never create it, so `LastActivity` tracking below applies only to local-YAML sessions.

When `/dh:start-task` runs on the local-YAML backend, it creates a context file at `~/.dh/projects/{slug}/context/active-task-{session_id}.json` (resolved via `dh_paths.context_dir(session_id)`) containing the plan address, task ID, and task file path. On each Write, Edit, or Bash operation, the PostToolUse hook:

1. Reads the context file to identify the active task — `handle_activity_update()` has no MCP fallback and exits silently when the file is absent
2. Updates `**LastActivity**: {ISO timestamp}` in the task section

### Timestamp Field Responsibilities

| Field              | Added By                  | When                              |
| ------------------ | ------------------------- | --------------------------------- |
| `**Started**`      | Agent (via `/dh:start-task`) | When agent begins work on task    |
| `**Completed**`    | Hook (SubagentStop)       | When sub-agent finishes           |
| `**LastActivity**` | Hook (PostToolUse)        | On each Write, Edit, or Bash call |

## Hook Runtime Profile Controls

The `task_status_hook.py` script supports environment-variable-based profile controls that adjust hook behavior without editing SKILL.md files.

### CLAUDE_SKILLS_HOOK_PROFILE

Controls which hook handlers run. Case-sensitive lowercase. Default when unset or empty: `standard`.

- **`minimal`** — PostToolUse (LastActivity updates) is skipped entirely. SubagentStop (task completion) runs normally. Use this to reduce I/O during task execution when activity timestamps are not needed.
- **`standard`** — All handlers run.
- **`strict`** — All handlers run. SubagentStop additionally performs pre-completion validation checks and emits warnings to stderr. Warnings are observational only — they do not prevent task completion. Strict checks verify that the task was claimed (status was `in-progress` before completion) and that acceptance criteria were defined (non-empty).

Invalid values produce a warning to stderr and fall back to `standard`.

### CLAUDE_SKILLS_DISABLED_HOOKS

Comma-separated list of hook IDs to disable. Each ID is stripped of whitespace. Empty segments are excluded. Unknown IDs are silently ignored for forward compatibility. Default when unset or empty: no hooks disabled.

Hook IDs for this script:

- `task-status:post-tool-use` — the PostToolUse handler (LastActivity timestamp updates)
- `task-status:subagent-stop` — the SubagentStop handler (task completion marking)

Disabled hooks take precedence over profile. If both `CLAUDE_SKILLS_HOOK_PROFILE=strict` and `CLAUDE_SKILLS_DISABLED_HOOKS=task-status:subagent-stop` are set, SubagentStop is skipped entirely (no strict checks run).

Disabled hooks exit 0 (Claude Code treats non-zero hook exit as an error that kills the hook chain).

### Examples

```bash
# Skip PostToolUse activity tracking (reduces I/O during task execution)
export CLAUDE_SKILLS_HOOK_PROFILE=minimal

# Enable strict pre-completion validation warnings
export CLAUDE_SKILLS_HOOK_PROFILE=strict

# Disable a specific hook by ID
export CLAUDE_SKILLS_DISABLED_HOOKS=task-status:post-tool-use

# Disable multiple hooks
export CLAUDE_SKILLS_DISABLED_HOOKS="task-status:post-tool-use,task-status:subagent-stop"
```

## Integration with /execution

The `/dh:execution` orchestrator uses this skill to:

1. Query task status via `uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan status`
2. Find ready tasks via `uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan ready`
3. Launch appropriate agents based on task's `agent` field
4. Update timestamps via hook scripts when tasks start/complete