work

What this skill does

<!-- Governing: ADR-0017 (Parallel Agent Coordination), ADR-0020 (Governing Comments), SPEC-0015 REQ "Issue Lifecycle Labels", SPEC-0015 REQ "Pre-Flight PR Awareness", SPEC-0015 REQ "Topological Merge Ordering", SPEC-0015 REQ "Design Document Isolation" -->
<!-- Governing: ADR-0015 (Markdown-Native Configuration), SPEC-0014 REQ "Config Resolution Pattern" -->

# Work on Issues

You are picking up tracker issues and implementing them in parallel using git worktrees. Each issue gets its own worktree and worker agent.

<!-- Governing: ADR-0028 (/loop Autonomous Mode), SPEC-0020 REQ "Lockfile Schema and Acquisition", SPEC-0020 REQ "Budget Schema and Persistence", SPEC-0020 REQ "Telemetry Schema", SPEC-0020 REQ "Resume Contract", SPEC-0020 REQ "Resume Contract Reconciliation" -->

> **Loop Mode (V1, opt-in).** When invoked under `/loop` with the `--loop` flag, this skill enters autonomous-mode and uses the lockfile + budget primitives documented in `references/loop-primitives.md` (acquired on entry, released on exit) and the telemetry + resume contract documented in `references/loop-telemetry.md` (every iteration appends a `history.jsonl` line and emits a stdout status block; `--resume` reconciles `tracked_prs[]` and `active_worktrees[]` from the last line). The full CLI surface, all 12 stop conditions, and all 6 AskUserQuestion gates are wired in story #144 (SPEC-0020). Without `--loop`, behavior is unchanged from the rest of this document and no `.sdd/loop/` artifacts are created.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the ADR and spec directories. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module. The resolved spec directory is `{spec-dir}`.

1. **Parse arguments**: Parse `$ARGUMENTS`.

   **Target resolution:**
   - If a SPEC number is provided (e.g., `SPEC-0003`), find all open tracker issues referencing that spec.
   - If issue numbers are provided (e.g., `42 43 47`), work on those specific issues.
   - If `$ARGUMENTS` is empty (ignoring flags), **review the backlog** (see step 4) and propose a work plan (see step 1a below) — do NOT require a spec.

   **1a. Backlog proposal (no arguments):** After discovering workable issues in step 4, analyze the backlog with a bias toward **unblocking work and feature development**:
   - Prefer issues that are blocking other issues over isolated work.
   - Prefer feature/enhancement issues over maintenance or chore issues when all else is equal.
   - Prefer issues with no dependencies (immediately startable) over blocked ones.
   - Group by epic or project when available to cluster related work.
   - Select up to `--max-agents` issues (default 4) as the proposed batch.

   Present the proposed batch to the user using `AskUserQuestion`:
   > "Here are the issues I'd like to work on. Approve or adjust before I start."

   Show a table:
   ```
   | # | Issue | Project/Epic | Rationale |
   |---|-------|-------------|-----------|
   | 1 | #42 JWT Token Generation | Auth Module | Unblocks #43 and #44 |
   | 2 | #47 Setup DB Schema | Core | No dependencies, foundational |
   | 3 | #51 User Registration API | Auth Module | High priority feature |
   ```

   Options: "Approve this batch" / "Let me pick manually" (if chosen, present full backlog and ask for issue numbers).

   **Flag parsing:**
   - `--max-agents N`: Maximum concurrent worker agents. Default: 4 (or CLAUDE.md `Worktrees > Max Agents`).
   - `--draft`: Create draft PRs instead of regular PRs. Default: off (or CLAUDE.md `Worktrees > PR Mode`).
   - `--dry-run`: Preview what would happen without creating worktrees or doing any work. Default: off.
   - `--no-tests`: Skip test execution in workers. Default: off.
   - `--module <name>`: Resolve artifact paths relative to the named module. Default: none.

2. **Load architecture context** (when a spec is provided or issues reference a spec): Read the spec's `spec.md` and `design.md`. Validate spec pairing per `references/shared-patterns.md` § "Spec Pairing Validation". Scan for referenced ADRs (e.g., `ADR-0001`) and read those too. This context will be sent to every worker. If no spec is associated with the selected issues, skip this step — workers will rely on issue body and codebase context alone.

3. **Detect tracker**: Follow the "Tracker Detection" flow in the plugin's `references/shared-patterns.md`. Fallback to `tasks.md` parsing if no tracker is found.

3a. **Ensure lifecycle labels exist** (Governing: SPEC-0015 REQ "Issue Lifecycle Labels"):

   Create the lifecycle labels using the try-then-create pattern (see `references/shared-patterns.md`) — attempt to use each label, and only create it if it doesn't exist. This avoids failures on repeated runs.

   | Label | Color | Meaning |
   |-------|-------|---------|
   | `queued` | `#CCCCCC` | Issue is in the work queue, not yet started |
   | `in-progress` | `#FBCA04` | An agent is actively working on this issue |
   | `in-review` | `#0E8A16` | A PR has been created and is awaiting review |
   | `merged` | `#6E40C9` | The PR has been merged |

   **For GitHub:**
   ```bash
   gh label create "queued" --color "CCCCCC" --description "Issue is queued for work" --force
   gh label create "in-progress" --color "FBCA04" --description "Agent is actively working" --force
   gh label create "in-review" --color "0E8A16" --description "PR created, awaiting review" --force
   gh label create "merged" --color "6E40C9" --description "PR has been merged" --force
   ```

   **For Gitea:** Use `ToolSearch` to discover label MCP tools (e.g., `mcp__gitea__label_write`). Create labels via the API equivalent. If labels already exist, the API will return an error — ignore it and proceed.

   **For `tasks.md` fallback:** Skip label creation (labels are not applicable to file-based tracking).

3b. **Define protected paths** (Governing: ADR-0017, ADR-0020, SPEC-0015 REQ "Design Document Isolation"):

   The following paths are **protected** and MUST NOT be modified by worker agents in feature branches:

   | Protected Path | Reason |
   |---------------|--------|
   | `{spec-dir}` | Spec changes require coordinated review |
   | `{adr-dir}` | ADR changes require coordinated review |
   | `CLAUDE.md` (project root) | Shared configuration — concurrent edits cause conflicts |
   | `.claude-plugin-design.json` | Plugin configuration — concurrent edits cause conflicts |

   **Exception:** Governing comments (per ADR-0020) MUST be added in feature PRs, not deferred. These are inline code comments (e.g., `// Governing: ADR-XXXX, SPEC-XXXX REQ "..."`) and are NOT considered design document modifications.

   This list is passed to every worker in step 9.4 and enforced in worker step 7a.

3c. **Tier 4 issues sync** (v5.0.0+):

   <!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 4 Always-Sync Issues for Sprint Skills" -->

   Before discovering workable issues (Step 4), sync the `{repo}-issues` qmd collection from the tracker so the lead and all workers see current issue state. This also feeds the Sibling PR Manifest (Step 8a) with fresh data. Subject to the 5-min dedup window per `references/tracker-sync.md` § "Cursor Management".

   1. Read `.sdd/issues/_meta.json`. If `last_sync` is within the last 5 minutes, skip the sync silently.
   2. Otherwise, invoke per-tracker fetch+normalize per `references/tracker-sync.md`. Print: "Syncing N issues from {tracker}…".
   3. On sync failure, surface a one-line warning per `tracker-sync.md` § "Failure Modes and Degradation" and proceed with live tracker queries (the pre-v5 path) for this run. Do NOT block; work dispatch is the user's primary intent.

4. **Discover workable issues**: Search the tracker for open issues:
   - If a **spec** was provided: find all open issues referencing that spec.
   - If **is