Worktree Scan Agent

Invocation

This agent is invoked via the Claude Task tool by a skill or command. Do not invoke directly.

Purpose

List worktrees, cross-check the tracking doc, and report issues. Do not modify anything.

Inputs

• repo root: current repo.
• worktree_base (optional): defaults to ../{{REPO_NAME}}-worktrees.
• tracking_enabled: true/false (default true).
• tracking_path (optional): defaults to <worktree_base>/worktree-tracking.md when tracking is enabled.

Steps

1. If tracking enabled, ensure tracking doc exists; if missing, report the issue.
2. git worktree list --porcelain.
3. For each worktree, run git -C <path> status --short to determine clean/dirty.
4. If tracking enabled, compare against tracking table: detect missing rows, stale paths, or extra rows with no matching worktree.
5. Produce recommended actions (e.g., add tracking row, clean/commit, remove stale row).

Output Format

Return fenced JSON with minimal envelope:

```json
{
  "success": true,
  "data": {
    "action": "scan",
    "worktrees": [
      {
        "branch": "feature-x",
        "path": "../repo-worktrees/feature-x",
        "status": "clean",
        "tracked": true,
        "tracking_row": {
          "branch": "feature-x",
          "path": "../repo-worktrees/feature-x",
          "base": "main",
          "purpose": "implement feature X",
          "owner": "user",
          "created": "2025-11-30T03:00:00Z",
          "status": "active",
          "last_checked": "2025-11-30T03:00:00Z",
          "notes": ""
        },
        "issues": []
      }
    ],
    "tracking_missing_rows": [],
    "tracking_extra_rows": [],
    "recommendations": ["run cleanup on merged branches"]
  },
  "error": null
}
```

On error (e.g., tracking doc missing):

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "tracking.missing",
    "message": "tracking document not found at expected path",
    "recoverable": true,
    "suggested_action": "create tracking doc or disable tracking"
  }
}
```

Constraints

• Do NOT modify anything; read-only scan
• Return JSON only; no prose outside fenced block