Collaborating With Claude

Collaborating with Claude Code

Drive Claude Code headlessly as an independent collaborator while the calling agent stays responsible for verification, synthesis, and final user-facing decisions.

The bridge (scripts/claude_bridge.py) wraps claude --print, streams progress to stderr, returns structured JSON with telemetry, and manages multi-turn continuity via SESSION_ID. Always go through the bridge — don't invoke claude directly — so output parsing and session handling stay consistent.

In Claude Code, run non-trivial calls in the background and watch the stderr progress:

Bash tool call:
  command: python3 skills/collaborating-with-claude/scripts/claude_bridge.py --cd "/project" --PROMPT "Analyze auth flow in src/auth/"
  run_in_background: true

run_in_background is a host tool parameter, not a shell argument. Use the task-output view to monitor timestamped stderr progress (session, responses, tools, cost) and the final JSON result.

Safety

Default to read-only delegation: --permission-mode plan (analyze, no edits/commands) or --tools "Read,Glob,Grep". Grant writes only deliberately (acceptEdits/auto), preferably in an isolated worktree. Do not hand secrets, private keys, or production data to Claude. Full permission-mode set and the worktree pattern: cli-reference.md, handoff-patterns.md.

Permissions and network (headless)

Headless claude -p cannot prompt: every gated action is denied on the spot and recorded in permission_denials, which the bridge surfaces (verified on 2.1.176). Authority is therefore decided entirely up front via --permission-mode, --tools, and --allowed-tools — get user consent before granting anything beyond read-only.

Network is governed by tool policy, not an OS sandbox: plan mode denies WebFetch/WebSearch too (verified), while an allowed Bash can reach the network freely. Pick the posture per task:

• No network, read-only: --permission-mode plan, or --tools "Read,Glob,Grep".
• Read-only plus targeted web research (verified): --permission-mode dontAsk --tools "Read,Glob,Grep,WebFetch,WebSearch" --allowed-tools "WebFetch(domain:example.com)" --allowed-tools "WebSearch".
• Reads outside --cd are gated as well — grant extra roots with --add-dir.

When to use / not use

Use for: second opinions on design, edge cases, or test gaps; proposing or reviewing a unified diff; multi-turn analysis while you implement. Skip for: trivial one-shot edits (do them directly); tasks needing authoritative cited facts (Claude may guess); anything touching secrets or prod data.

Quick start

⚠️ Backticks / $VARS in prompts trigger shell expansion — use a single-quoted heredoc, or --prompt-file for large/generated prompts. See shell-quoting.md.

PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --permission-mode plan --PROMPT "$PROMPT" --output-format stream-json

For large or shell-sensitive prompts, write the prompt to a file and pass --prompt-file /tmp/prompt.md (piped via stdin — no argv/quoting limits).

Returns (stdout JSON): { "success": true, "SESSION_ID": "...", "agent_messages": "...", "model": "...", "subtype": "success", "total_cost_usd": 0.03, "usage": {...}, "num_turns": 1 } — plus tools_used / tools_failed / tool_counts / permission_denials / structured_output / is_error when relevant. Check tools_failed and permission_denials before trusting the answer: a denied tool means Claude reasoned without the evidence it asked for. Progress streams to stderr; the bridge exits non-zero on failure.

Multi-turn sessions

Capture SESSION_ID from the first call and pass it back (selectors are mutually exclusive):

# Turn 1
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --PROMPT "Analyze the bug in foo()." --output-format stream-json

# Turn 2 — resume by ID (use the same --cd)
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --SESSION_ID "<id>" --PROMPT "Propose a fix." --output-format stream-json

# Or resume the most recent session in this directory
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --continue --PROMPT "What about edge cases?" --output-format stream-json

Use stream-json or json output to capture SESSION_ID.

Bridge flags

Core: --PROMPT (or --prompt-file) · --cd (required) · --model (alias haiku/sonnet/opus/fable, or full id) · --output-format (text·json·stream-json, default stream-json).

Sessions (mutually exclusive): --SESSION_ID · --session-id <uuid> · --continue; plus --fork-session, --no-session-persistence.

Permissions: --permission-mode (default·plan·acceptEdits·auto·dontAsk·bypassPermissions) · --tools · --allowed-tools · --disallowed-tools. Footgun: the space in Bash(git diff *) is load-bearing.

Reproducibility & cost: --bare / --safe-mode (skip customizations; --bare needs ANTHROPIC_API_KEY) · --effort (low→max) · --max-budget-usd · --max-turns · --timeout <seconds>.

Context & advanced: --prompt-file · --system-prompt[-file] · --append-system-prompt[-file] · --add-dir · --json-schema · --mcp-config · --settings · --agent/--agents · --return-all-messages · --verbose.

Full semantics in cli-reference.md. Set the host's timeout_ms to 600000 (10 min) when invoking via a command runner.

Tune performance

--model haiku for quick checks, sonnet for routine work, opus or fable for hard tasks; --effort low→max trades depth for speed/cost; --max-budget-usd caps spend. Omit --model to use the CLI default.

Prompting

Quick starters in prompt-template.md; composable XML blocks in prompt-blocks.md; end-to-end recipes in prompt-recipes.md; delegation patterns and principles in patterns.md. In short: point (file:line), don't paste; one objective per run; state the output shape; verify Claude's output before acting.

Verification

• Smoke: python3 skills/collaborating-with-claude/scripts/claude_bridge.py --help
• Syntax: python3 -m py_compile skills/collaborating-with-claude/scripts/claude_bridge.py
• Session: run a prompt with --output-format stream-json; confirm JSON has success: true, a SESSION_ID, and telemetry (subtype/total_cost_usd/usage/num_turns); failures exit non-zero.
• Ensure Claude is logged in (claude then /login), or set ANTHROPIC_API_KEY (required for --bare).

Collaboration State Capsule

Keep this updated across turns (referenced by handoff-patterns.md):

[Claude Capsule] Goal: | SID: | Model: | PermMode: | Files: | Last: | Next:

References

• prompt-template.md — quick plain-text starters
• prompt-blocks.md — composable XML blocks
• prompt-recipes.md — end-to-end templates
• prompt-antipatterns.md — common mistakes
• patterns.md — when to delegate + prompt patterns
• handoff-patterns.md — read-only / worktree / synthesis
• parallel.md — parallel runs and worktree isolation
• cli-reference.md — verified Claude CLI flags + event schema
• shell-quoting.md — safe heredoc prompts

Claude Prompt Template (Token-Efficient)

Prefer model aliases (--model sonnet for routine work, --model opus for harder tasks); omit --model to use the CLI default. For complex or high-stakes work, upgrade to the XML blocks in ../references/prompt-blocks.md and recipes in ../references/prompt-recipes.md.

Analysis / Plan (read-only)

Task:
- <what to analyze>

Repo pointers:
- <file paths + approximate line numbers>

Constraints:
- Keep it concise and actionable.
- Reference files/lines instead of pasting code.

Output:
- Bullet list of findings and a proposed plan.

Patch (Unified Diff only)

Task:
- <what to change>

Repo pointers:
- <file paths + approximate line numbers>

Constraints:
- OUTPUT: Unified Diff Patch ONLY.
- Minimal, focused changes. No unrelated refactors.

Output:
- A single unified diff patch.

Review (audit an existing diff)

Task:
- Review the following unified diff for correctness, edge cases, and missing tests.

Constraints:
- Return a checklist of issues + suggested fixes (no code unless requested).

Input diff:
<paste unified diff here>

Implementation (worktree + acceptEdits)

Task:
- <what to implement>

Repo pointers:
- <entry file paths + approximate line numbers>

Done criteria:
- <specific acceptance criteria>

Constraints:
- Stay focused on the stated task. No unrelated refactors.
- Run the narrowest test that proves correctness.

Output:
- List of files changed and a brief summary.

Run implementation with write access only in an isolated worktree (--permission-mode acceptEdits); see ../references/handoff-patterns.md.

When to upgrade to XML blocks

Use the XML blocks in ../references/prompt-blocks.md when:

• The task is multi-step and you need a <completeness_contract>.
• Correctness matters and you want a <verification_loop>.
• You're doing review/research and need <grounding_rules>.
• Claude keeps stopping early — add <default_follow_through_policy>.

See ../references/prompt-recipes.md for ready-to-use end-to-end templates.

Claude Code CLI Reference

Verified against claude (Claude Code) CLI v2.1.176. The bridge wraps claude --print (headless mode).

Invocation shape

Claude runs headlessly from the workspace directory (it uses the process cwd; there is no --cd flag — the bridge sets cwd for you):

cd /path/to/repo && claude --print "<prompt>" --output-format stream-json --verbose

The prompt is the positional argument, or piped via stdin when the bridge's --prompt-file is used.

Core flags (headless)

Permission & tools (single source of truth)

Headless gating extends to reads: paths outside --cd / --add-dir are permission-gated and denied under -p (verified). Denials also surface as tool_result errors, so the bridge's tools_failed counts them.

Tool scoping:

• --tools "Read,Glob,Grep" — restrict which built-ins exist at all ("" = none, "default" = all).
• --allowedTools / --disallowedTools — approve/deny by name or rule. Footgun: the space in Bash(git diff *) is load-bearing — Bash(git diff*) would also match git diff-index.

Safe read-only review: --permission-mode plan, or --tools "Read,Glob,Grep" --permission-mode dontAsk.

Network is tool policy, not an OS sandbox: an allowed Bash reaches the network freely, and plan blocks WebFetch/WebSearch. For read-only work that needs targeted web access (verified recipe):

--permission-mode dontAsk --tools "Read,Glob,Grep,WebFetch,WebSearch" \
  --allowedTools "WebFetch(domain:example.com)" --allowedTools "WebSearch"

Reproducibility & context

Sessions

Transcripts live under ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl; resume needs a matching cwd.

There is no local review / apply / fork subcommand (unlike Codex). Use --fork-session to branch, pass diffs in the prompt for review, and git apply to apply patches. claude ultrareview exists but is a cloud-hosted multi-agent review of the current branch/PR, not a local headless run. Native claude --worktree <name> creates a session worktree (verify it composes with --print before scripting).

stream-json event schema

With --output-format stream-json --verbose, each stdout line is one JSON event:

// session metadata — carries session_id, model, tools, mcp_servers
{"type":"system","subtype":"init","session_id":"…","model":"claude-sonnet-4-6"}
// assistant turn — text + tool_use blocks in message.content[]
{"type":"assistant","message":{"content":[{"type":"text","text":"…"},
  {"type":"tool_use","name":"Read"}]},"session_id":"…"}
// tool results fed back — is_error:true marks failures and permission denials
{"type":"user","message":{"content":[{"type":"tool_result","is_error":true,"content":"…"}]}}
// rate-limit signal
{"type":"rate_limit_event","rate_limit_info":{"status":"allowed"}}
// final, authoritative termination event
{"type":"result","subtype":"success","is_error":false,"result":"…final text…",
  "session_id":"…","total_cost_usd":0.04,"num_turns":2,
  "usage":{"input_tokens":3,"output_tokens":293,"cache_read_input_tokens":40868},
  "modelUsage":{"claude-sonnet-4-6":{"costUSD":0.04}},"permission_denials":[]}

result.subtype ∈ success | error_max_turns | error_max_budget_usd | error_during_execution | error_max_structured_output_retries. The final text (result.result) is present only on success; a model/auth failure can emit subtype:"success" with `is_error:true` — always check is_error. --output-format json emits just this final result object.

From these events the bridge derives tools_used, per-tool tool_counts, and tools_failed (count of tool_result blocks with is_error:true — includes permission denials and ordinary tool errors).

Other system sub-events: hook_started / hook_response (non---bare only), api_retry, compact_boundary.

Caveats

• `--json-schema` validates output after generation (not constrained decoding) — malformed output is possible; validate independently.
• stdin (used by --prompt-file) is capped at ~10 MB.
• Background Bash tasks Claude spawns under -p are terminated ~5 s after the final result.
• claude --help does not list every flag; absence from --help does not mean unavailable (--max-turns, --system-prompt-file are real and verified).

Handoff Patterns

How much authority to give Claude, and how to bring its work back.

Read-only analysis

For diagnosis, architecture opinions, reviews, and research.

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/path/to/repo" \
  --permission-mode plan \
  --PROMPT "$PROMPT"

Ask for evidence, file paths, line numbers, and a compact recommendation. Verify the cited files before acting.

plan also denies WebFetch/WebSearch. If the analysis needs the web, use the scoped recipe in cli-reference.md (dontAsk + --tools + pre-approved --allowed-tools) instead of widening the permission mode. Check tools_failed / permission_denials in the result: a denied tool means Claude answered without the evidence it asked for.

File-backed handoff

When the prompt is large, generated, or shell-sensitive (backticks, $VARS), pass it via a file instead of argv:

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/path/to/repo" \
  --permission-mode plan \
  --prompt-file /tmp/claude-handoff.md

--prompt-file pipes the file to Claude's stdin, bypassing argv and shell-quoting limits (keep it under ~10 MB). For large system context, use --system-prompt-file / --append-system-prompt-file.

Read-only patch proposal

When you want implementation help without letting Claude edit:

• Ask for OUTPUT: Unified Diff Patch ONLY.
• Include expected behavior and the tests to satisfy.
• Run in --permission-mode plan so no writes happen.

Inspect the patch, then apply it yourself with git apply.

Isolated write handoff

Give write access only in an isolated worktree, preferably under /tmp. This is the canonical worktree pattern — other references point here.

git worktree add -b claude/<task-name> /tmp/claude-<task-name> HEAD

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/tmp/claude-<task-name>" \
  --permission-mode acceptEdits \
  --PROMPT "$PROMPT"

(acceptEdits auto-approves file edits; auto adds classifier-gated command approval — see cli-reference.md.) After completion:

git -C /tmp/claude-<task-name> diff
git -C /tmp/claude-<task-name> status --short

Review and port the changes deliberately. Do not merge blind. Claude also offers native claude --worktree for interactive sessions — see parallel.md.

Parallel read-only runs

Split independent questions into separate sessions: one prompt per concern, separate SESSION_IDs, plan mode, explicit output contracts. Synthesize by comparing contradictions, shared evidence, and gaps. Details in parallel.md.

State capsule

Keep the [Claude Capsule] from SKILL.md updated after each turn, so compaction or handoff does not lose the thread.

Parallel Execution and Worktree Isolation

Use when a task splits into independent runs, or when write access must be isolated.

Parallel read-only analysis

For independent analyses that don't modify files, run multiple bridge calls concurrently. In Claude Code, set run_in_background: true on each Bash tool call and monitor each via the task-output view (the bridge streams timestamped progress to stderr).

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/project" --permission-mode plan \
  --PROMPT "Analyze the auth module for correctness risks."

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/project" --permission-mode plan \
  --PROMPT "Analyze the payment module for correctness risks."

After all complete, synthesize: contradictions, shared dependencies, gaps no run covered, and the concrete next action.

Claude-managed subagents

Claude can spawn its own subagents for independent lanes via --agents (inline JSON) or --agent <name>:

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/project" --permission-mode plan \
  --PROMPT "Use parallel subagents: one for security risks, one for test gaps, one for maintainability. Wait for all, then summarize only final findings with file references."

Keep subagent work read-only unless each write lane has its own worktree. Ask for distilled summaries, not raw logs.

Worktree isolation

When multiple write-capable runs are needed, use one git worktree per task (canonical setup in handoff-patterns.md):

git worktree add -b claude/auth-fix /tmp/wt-auth HEAD
git worktree add -b claude/perf-fix /tmp/wt-perf HEAD

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "/tmp/wt-auth" --permission-mode acceptEdits \
  --PROMPT "Fix the auth bug in src/auth/login.py. Run the narrow verification."

Review each (git -C /tmp/wt-auth diff) before merging, then git worktree remove /tmp/wt-auth.

Claude also offers native claude --worktree <name> to create a session worktree directly (verify it composes with --print for your version before relying on it in scripts).

Worktree tips

• Put worktrees in /tmp or outside the repo.
• node_modules, virtualenvs, caches, and build outputs are not shared automatically.
• The same branch cannot be checked out in multiple worktrees.
• Use absolute paths for result files and review artifacts.

Rate limits

• Start with 2–3 concurrent runs.
• Stagger launches if rate-limit events appear (the bridge surfaces rate_limited in its result).
• Split by independent concern; don't run duplicate agents on the same vague task.

Prompt Patterns

When to delegate to Claude, and how to shape the prompt.

When to delegate

Pattern overview

Prefer --permission-mode plan (analyze, no writes) or --tools "Read,Glob,Grep" for read-only work. Full permission-mode set in cli-reference.md.

Deep analysis

In this codebase, we are seeing:
<symptom, error, or failing command>

Known clues:
- <file or module>
- <recent change>
- <related stack trace>

Analyze:
1. root cause with file:line evidence
2. full code path involved
3. smallest safe fix approach

Do not modify files.

Bug fix proposal

Bug: <what is happening>
Reproduction: <steps or failing test>
Expected: <correct behavior>

Investigate root cause. Check:
- <paths>
- <related components>

Output: root cause analysis with file:line evidence, then a unified diff fix.
Do not modify files directly.

After review, apply with git apply (Claude has no separate apply subcommand).

Code review

Pass the diff in the prompt (Claude has no built-in review subcommand):

Review this diff for correctness, edge cases, and missing tests:
<unified diff>

Output prioritized findings with severity and suggested fixes. Skip formatting-only changes.

Or point Claude at the changed paths in plan mode and let it read them itself.

Prototyping

Implement <feature> in <project>.

Requirements:
- <requirement>

Reference:
- <existing similar code path>

Constraints:
- follow existing patterns
- no unrelated refactors

Output: unified diff patch only.
Do not modify files directly.

For direct writes, use an isolated worktree with --permission-mode acceptEdits (or auto). See handoff-patterns.md.

Architecture comparison

We need to implement <feature>. Compare:

Option A: <description>
Option B: <description>

Based on actual code under <paths>, evaluate:
1. implementation complexity
2. performance implications
3. impact on existing code
4. maintainability

Output a comparison table with a recommendation.

Multi-file refactoring

Refactor <what> across <scope>.

Rules:
- <rule>

Files:
- <glob or directory>

Analyze impact first, list affected files, then produce a unified diff.
Do not modify files directly.

Tips

• Point, don't paste: pin file paths and line numbers; let Claude read via --cd / --add-dir.
• One objective per run; split unrelated work into separate runs.
• State done criteria and output shape (table, JSON, unified diff).
• Verify Claude's output before changing final code or reporting to the user — the bridge plumbing is reliable, but the model's reasoning still needs checking.
• Tune effort/cost with --effort (low→max), --model (sonnet/opus), and --max-budget-usd. See cli-reference.md.

Prompt Anti-Patterns

Common mistakes when prompting Claude. Each shows the problem and a fix.

Vague task framing

Bad:

Take a look at this and let me know what you think.

Fix — state the job:

<task>
Review this change for material correctness and regression risks.
</task>

Missing output contract

Bad:

Investigate and report back.

Fix — define the shape:

<structured_output_contract>
Return:
1. root cause
2. evidence
3. smallest safe next step
</structured_output_contract>

No follow-through default

Bad:

Debug this failure.

Fix — tell Claude when to stop:

<default_follow_through_policy>
Keep going until you have enough evidence to identify the root cause confidently.
</default_follow_through_policy>

Asking for more reasoning instead of a better contract

Bad:

Think harder and be very smart.

Fix — add a verification loop:

<verification_loop>
Before finalizing, verify that the answer matches the observed evidence and task requirements.
</verification_loop>

Mixing unrelated jobs into one run

Bad:

Review this diff, fix the bug you find, update the docs, and suggest a roadmap.

Fix — one task per run: 1. Run review first. 2. Run a separate fix prompt if needed. 3. Use a third run for docs or roadmap.

Unsupported certainty

Bad:

Tell me exactly why production failed.

Fix — require grounding:

<grounding_rules>
Ground every claim in the provided context or tool outputs.
If a point is an inference, label it clearly.
</grounding_rules>

Prompt Blocks

Composable XML-tagged blocks for structuring Claude prompts. Use selectively — pick only the blocks your task needs.

Core

<task>

Use in every prompt. State the job, the context, and what done looks like.

<task>
Describe the concrete job, the relevant repository or failure context, and the expected end state.
</task>

Output shape

<structured_output_contract>

Use when the response shape matters (reviews, diagnostics, recommendations).

<structured_output_contract>
Return exactly the requested output shape and nothing else.
Keep the answer compact.
Put the highest-value findings or decisions first.
</structured_output_contract>

<compact_output_contract>

Use when you want concise prose instead of a schema.

<compact_output_contract>
Keep the final answer compact and structured.
Do not include long scene-setting or repeated recap.
</compact_output_contract>

Follow-through

<default_follow_through_policy>

Use when Claude should act without asking routine questions.

<default_follow_through_policy>
Default to the most reasonable low-risk interpretation and keep going.
Only stop to ask questions when a missing detail changes correctness, safety, or an irreversible action.
</default_follow_through_policy>

<completeness_contract>

Use for debugging, implementation, or any multi-step task that should not stop early.

<completeness_contract>
Resolve the task fully before stopping.
Do not stop at the first plausible answer.
Check whether there are follow-on fixes, edge cases, or cleanup needed for a correct result.
</completeness_contract>

<verification_loop>

Use when correctness matters.

<verification_loop>
Before finalizing, verify the result against the task requirements and the changed files or tool outputs.
If a check fails, revise the answer instead of reporting the first draft.
</verification_loop>

Grounding

<missing_context_gating>

Use when Claude might otherwise guess about repository facts.

<missing_context_gating>
Do not guess missing repository facts.
If required context is absent, retrieve it with tools or state exactly what remains unknown.
</missing_context_gating>

<grounding_rules>

Use for review, research, or root-cause analysis.

<grounding_rules>
Ground every claim in the provided context or your tool outputs.
Do not present inferences as facts.
If a point is a hypothesis, label it clearly.
</grounding_rules>

<citation_rules>

Use when external research or source references matter.

<citation_rules>
Back important claims with citations or explicit references to the source material you inspected.
Prefer primary sources.
</citation_rules>

Safety and scope

<action_safety>

Use for write-capable or potentially broad tasks.

<action_safety>
Keep changes tightly scoped to the stated task.
Avoid unrelated refactors, renames, or cleanup unless they are required for correctness.
Call out any risky or irreversible action before taking it.
</action_safety>

<tool_persistence_rules>

Use for long-running tool-heavy tasks.

<tool_persistence_rules>
Keep using tools until you have enough evidence to finish the task confidently.
Do not abandon the workflow after a partial read when another targeted check would change the answer.
</tool_persistence_rules>

Task-specific

<research_mode>

Use for exploration, comparisons, or recommendations.

<research_mode>
Separate observed facts, reasoned inferences, and open questions.
Prefer breadth first, then go deeper only where the evidence changes the recommendation.
</research_mode>

<dig_deeper_nudge>

Use for review and adversarial inspection.

<dig_deeper_nudge>
After you find the first plausible issue, check for second-order failures, empty-state behavior, retries, stale state, and rollback paths before you finalize.
</dig_deeper_nudge>

Prompt Recipes

End-to-end prompt templates for common Claude tasks. Copy the smallest recipe that fits, then trim what you don't need.

Blocks reference: prompt-blocks.md

Diagnosis

Find the root cause of a failing test, command, or runtime error.

<task>
Diagnose why [failing test / command / error] is breaking in this repository.
Use the available repository context and tools to identify the most likely root cause.
</task>

<compact_output_contract>
Return a compact diagnosis with:
1. most likely root cause
2. evidence
3. smallest safe next step
</compact_output_contract>

<default_follow_through_policy>
Keep going until you have enough evidence to identify the root cause confidently.
Only stop to ask questions when a missing detail changes correctness materially.
</default_follow_through_policy>

<verification_loop>
Before finalizing, verify that the proposed root cause matches the observed evidence.
</verification_loop>

<missing_context_gating>
Do not guess missing repository facts.
If required context is absent, state exactly what remains unknown.
</missing_context_gating>

Narrow fix

Implement the smallest safe fix for an identified issue.

<task>
Implement the smallest safe fix for [issue] in this repository.
Preserve existing behavior outside the failing path.
</task>

<structured_output_contract>
Return:
1. summary of the fix
2. touched files
3. verification performed
4. residual risks or follow-ups
</structured_output_contract>

<default_follow_through_policy>
Default to the most reasonable low-risk interpretation and keep going.
</default_follow_through_policy>

<completeness_contract>
Resolve the task fully before stopping.
Do not stop after identifying the issue without applying the fix.
</completeness_contract>

<verification_loop>
Before finalizing, verify that the fix matches the task requirements and that the changed code is coherent.
</verification_loop>

<action_safety>
Keep changes tightly scoped to the stated task.
Avoid unrelated refactors or cleanup.
</action_safety>

Root-cause review

Analyze a change for correctness and regression risks.

<task>
Analyze this change for material correctness and regression issues.
Focus on the provided repository context only.
</task>

<structured_output_contract>
Return:
1. findings ordered by severity
2. supporting evidence for each finding
3. brief next steps
</structured_output_contract>

<grounding_rules>
Ground every claim in the repository context or tool outputs.
If a point is an inference, label it clearly.
</grounding_rules>

<dig_deeper_nudge>
Check for second-order failures, empty-state handling, retries, stale state, and rollback paths before finalizing.
</dig_deeper_nudge>

<verification_loop>
Before finalizing, verify that each finding is material and actionable.
</verification_loop>

Research / recommendation

Explore options and recommend a path.

<task>
Research the available options and recommend the best path for [topic].
</task>

<structured_output_contract>
Return:
1. observed facts
2. reasoned recommendation
3. tradeoffs
4. open questions
</structured_output_contract>

<research_mode>
Separate observed facts, reasoned inferences, and open questions.
Prefer breadth first, then go deeper only where the evidence changes the recommendation.
</research_mode>

<citation_rules>
Back important claims with explicit references to the sources you inspected.
Prefer primary sources.
</citation_rules>

Shell quoting for --PROMPT

When invoking claude_bridge.py, be careful: your shell parses the command line before Python runs.

The pitfall: Markdown backticks

Markdown inline code uses backticks (` like/this `). In bash/zsh, backticks mean command substitution, even inside double quotes, so this breaks:

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." \
  --PROMPT "Analyze `tmp/eth_dev_news_raw.json` and summarize."

Typical symptoms (from the shell, before Claude runs):

• zsh: permission denied: tmp/eth_dev_news_raw.json
• zsh: command not found: as_of

Recommended: heredoc (no expansion)

Build the prompt via a single-quoted heredoc delimiter (<<'EOF') so backticks (and $VARS, $(...), etc.) are not expanded by the shell:

PROMPT="$(cat <<'EOF'
Analyze `tmp/eth_dev_news_raw.json` and summarize.
Set `as_of` to `YYYY-MM-DD`.
EOF
)"

python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." \
  --PROMPT "$PROMPT" \
  --output-format stream-json

Alternatives

• Escape backticks manually: use \` (easy to miss in long prompts).
• Avoid backticks entirely: write Analyze the file tmp/eth_dev_news_raw.json instead.