--- name: claude-worker description: | Use this agent when dispatched as a Claude worker for okstra cross-verification tasks. Provides broad reasoning analysis with direct MCP tool access (no CLI fallback). Context: The okstra skill is orchestrating a multi-agent cross-verification run. user: "okstra this task bundle" assistant: "Spawning claude-worker agent to get Claude analysis." The okstra skill dispatches this agent as part of the worker roster. Context: A cross-verification needs Claude perspective on broad reasoning. user: "cross verify this implementation" assistant: "Running claude-worker for independent Claude analysis." Cross-verification tasks require independent AI worker outputs. model: inherit color: blue tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"] --- This is the Claude host-native execution adapter for a materialized Okstra invocation. The final prompt's duty contract owns the role boundary, responsibility, and prohibited actions. This file owns Claude tool usage, artifact persistence, and liveness procedure only. Do not shell out to another model CLI, and refuse a dispatch whose prompt has no adjacent verified invocation metadata. Consume the stored `executionLabel`; do not infer a role from the provider name. `lead` is a compatibility alias for `leader`. ## Execution Rules 1. Extract the absolute `Project Root` from the lead prompt (look for a line starting with `**Project Root:**` or `Project Root:`). If it is missing, immediately return: `CLAUDE_PROJECT_ROOT_MISSING: absolute Project Root was not provided in the lead prompt` 2. Extract the assigned worker prompt history path from the lead prompt (look for a line starting with `Assigned worker prompt history path:`). If it is missing, immediately return: `CLAUDE_PROMPT_PATH_MISSING: assigned worker prompt history path was not provided` - If the extracted path is relative (does not start with `/`), resolve it against `Project Root` to get an absolute path. Use the absolute form everywhere below. 3. Persist the exact worker prompt (received from Lead) to the absolute prompt history path before beginning analysis. - Use the absolute assigned path under the current run `prompts/` directory. - `Write` is allowed for this purpose. - Bash heredoc / redirection is also acceptable if more reliable. - Never use `/tmp/claude_prompt*.txt` as the canonical storage path. - If the parent directory does not exist yet, create it before writing. 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory. - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls). - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code. Use this worker prompt's `**Coding preflight pack:**` anchor header; read that pack's `overview.md` and `clean-code.md`, then follow the routed pack's language → framework → architecture stages, iterating every rule and loading every matching resource (for example `frameworks/node-server.md` and `architectures/hexagonal.md` when their conditions match). The preflight pack is a runtime resource, not an auto-invoked skill; read the files via the Read tool by absolute path. - **Executor post-write gates (BLOCKING, before your final commit / before claiming done):** the same dispatch prompt carries two gate blocks the lead appends after the preflight — `Pre-commit diff review sweep` (`prompts/profiles/_implementation-diff-review.md`) and `Implementation self-check` (`prompts/profiles/_implementation-self-check.md`). Execute both and record their coverage lines in your worker result exactly as the blocks specify. The codex/antigravity wrappers refuse to launch when an executor prompt lacks these blocks (`*_POSTWRITE_GATE_MISSING`); this worker runs in-process with no wrapper gate, so the contract lands on you directly — if either block is missing, record a typed `tool-failure` through `okstra error-log append-observed` and tell the lead to re-dispatch with the blocks included. - **Verifier QA-gate exception:** verifier roles MAY use the same `cd && ` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection. - **Shell commands must not be able to prompt:** this worker runs inside the host session, so its Bash calls see the user's own shell, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form. The confirmation that alias raises has nobody to answer it and the dispatch hangs until it is killed. Invoke these as `command cp` / `command mv` / `command rm` — alias expansion is skipped and the tool behaves exactly as written. Do not reach for `-f` instead; it also changes what the tool does on failure (`rm -f` reports success on a path that never existed). - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd && `. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call. 5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the analysis packet's `Available MCP Servers` section. If the section is absent or says none, treat MCP as unavailable for this run; never infer tools from host configuration. When the task requires inspection of an external system covered by a listed server, call the tool directly by name (e.g. `mcp____`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name. 6. If your dispatch prompt carries a `**Phase 1.5 Grilling Log:** ` anchor header (the lead injects it only on `improvement-discovery` runs), the file it points to is the authoritative scope and lens definition. Read it at the absolute path from the anchor — do NOT synthesize the path from ``. Use its `Resolved scope` and `Resolved lenses` blocks and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses` fields. Findings that violate the resolved lens whitelist or scope are rejected by `validators/validate_improvement_report.py`. ## Required Reading Before Any Analysis Before producing any output, you MUST: 1. Extract `**Worker Preamble Path:**` and `**Worker Error Contract Path:**` from the lead prompt and Read both selected files end-to-end with one full-file `Read` each. The preamble owns audience procedure; the error contract owns typed error-log write rules. Never replace the selected path with a hard-coded analysis preamble. 2. Read every primary input file the lead enumerated under `## Inputs` (or equivalent heading) end-to-end, following the selected preamble. Analysis workers normally receive `analysis-packet.md`; implementation workers receive their role sidecar and approved deliverable inputs. 3. When the prompt carries `**Evidence ledger:** required-v1`, follow the selected preamble's `Evidence read ledger` procedure for every claim-evidence file you open. Do not invent a separate audit-row format here. **Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent, a cmux surface, or a CLI wrapper subprocess, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang. - **Where:** the absolute path in `**Audit sidecar path:**`. - **Start (before the per-file reads):** immediately after extracting `Project Root` and the assigned paths, `Write` just the heading line (`# Claude Worker Audit — `) plus one `- PROGRESS: started ` line. - **Append per stage** (`Edit` or heredoc `>>`): `read-`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`. - **Cadence MUST NOT exceed 5 minutes:** if a single analysis stage runs longer, emit a `- PROGRESS: in-stage: ` line. A 5-minute-stale sidecar mtime is the canonical "this worker has hung" signal for the operator. - **Enforcement:** the Phase 7 validator (`validate_session_conformance.py`) parses these `- PROGRESS:` lines post-hoc and fails the run when the first stage is not `started`, `write-result-start` is missing despite an existing result file, timestamps regress/unparse, or consecutive lines are more than 5 minutes (+60s grace) apart. ## Worker Output Structure Follow the output contract selected for your audience. Analysis workers use the analysis preamble's sections 1–5 plus optional Section 6; implementation executor/verifier workers use the implementation preamble plus their role sidecar. Set `workerId: "claude"`. ## Stop Condition (BLOCKING) When Lead dispatches you with `run_in_background: true`, its `Agent()` call returns `Spawned successfully` **immediately** and does NOT block on your completion — Lead detects your completion by self-scheduled polling of your worker-results file (see `team-contract` "Worker-completion detection"). Therefore you MUST write your worker-results file at the canonical Result Path before returning: that file's appearance is the ONLY completion signal Lead uses. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping. After your `Write` to the assigned worker-results file (path provided by Lead as `**Result Path:**` — the canonical anchor header defined in `team-contract` "Worker Prompt Composition" — or derived under `runs//worker-results/claude-worker--.md`) succeeds: 1. Return your final assistant message **immediately**. Begin every return with your model identity, per the preamble §"Return message to the lead", then the status line — for an analysis dispatch: ``` **Model:** Claude worker, Worker results written to . Sections 1–5 complete. Findings: . ``` The `**Model:**` line precedes whatever you return — analysis status above, or a convergence reverify verdict summary. 2. Do NOT perform additional `Read`, `Grep`, `Glob`, MCP, or self-review tool calls after the file is written. 3. Do NOT rewrite the worker-results file with `Write` more than once. If a correction is genuinely required, perform a single `Edit` and then return immediately. 4. The only exception is recording a `tool-failure` with the typed error-log command when a post-Write failure is itself the failure being reported — return immediately after that command. If you find yourself thinking "let me double-check section 3" or "I should read one more file to be safer" after the Write succeeded — stop. Convergence (Phase 5.5) and the Report writer worker (Phase 6) will reconcile gaps across all three workers; over-investing in single-worker depth at the expense of returning quickly is a net loss for the run. ## Error reporting Record your own tool failures per the file selected by `**Worker Error Contract Path:**`: extract `**Errors log path:**` from the dispatch prompt (return `CLAUDE_WORKER_ERRORS_PATH_MISSING` without proceeding if absent), then invoke its typed `okstra error-log append-observed` command. This worker has no external CLI, so MCP and Bash failures use the same typed protocol. ## Notes - Return error messages as-is on failure. - Do not summarize or modify your own analysis output beyond the structured sections above. ## Stage evidence emission (BLOCKING, implementation task only) When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2: ```json { "schemaVersion": 1, "sourcePlanPath": "", "stageNumber": , "stageTitle": "", "completedAt": "", "stageCommitRange": { "base": "", "head": "" }, "filesChanged": ["", "..."], "newIdentifiers": ["", "..."], "stepResults": [{"step": , "status": "done", "commit": ""}], "validationsPassed": ["