claude-code-consult

Files (4)

• SKILL.md
• openai.yaml · agents/
• claude-code-consult.sh · scripts/
• test_consult.py · scripts/

SKILL.md (first lines)

# Claude Code Consult

Use local `claude` as an external reviewer after building context in Codex. Keep the ask narrow and intentional. This wrapper is for consultation, not agentic delegation.

## Workflow

1. Gather context locally first. Read the code, reproduce the issue, or draft the plan before consulting Claude.
2. Choose the mode that matches the ask:
   - `plan`: validate a proposed sequence of work
   - `solution`: critique an implementation approach or compare options
   - `stuck`: help debug or unblock a problem after failed attempts
   - `raw`: send an untemplated question when the built-in framing is a poor fit
3. Build a compact prompt packet with:
   - the goal
   - the relevant constraints
   - what you already tried or decided
   - the exact question you want answered
4. Attach only the files that matter. Prefer one to three focused files or excerpts over broad repository dumps.
5. Run the wrapper script and use Claude's output as input to your own judgment. It uses safe mode with tools disabled, reads the packet from stdin, and does not persist a local Claude session. Requires a Claude CLI supporting `--safe-mode`, `--tools`, and `--no-session-persistence`.

Attached file contents and prompt text are sent to the authenticated Claude provider. Keep the packet focused on the requested review and omit secrets. An approval-review rejection happens before CLI execution; it is not an authentication or wrapper failure. If a rejection requires specific payload approval, explain the selected files and destination, obtain that approval, and retry only after it arrives. Do not broaden or reroute the payload to bypass the rejection.

## Delegation Guidance

These rules are still useful when you choose to run Claude in a truly agentic workflow outside this wrapper:

- good candidates: tests for code you already wrote, an isolated component, or a code review pass
- do not delegate when the task depends on code you are currently building, when file ownership overlaps, or when the task requires the current conversation context
- run Claude in the background and review its output before marking the work item complete

This wrapper does not implement agentic delegation. `claude --print` can critique or advise, but it cannot safely own and execute bounded code changes.

## Commands

Use the wrapper:

```bash
scripts/claude-code-consult.sh <plan|solution|stuck|raw> [options] [prompt]
```

Options:

- `--file <path>`: attach a relevant file with line numbers; repeat as needed
- `--file <path:N-M>`: attach only a focused line range from a file
- `--model <model>`: pass a specific Claude model
- `--effort <low|medium|high|max>`: request more or less reasoning effort

If prompt text is omitted, the script reads from stdin.

Examples:

```bash
scripts/claude-code-consult.sh plan \
  --file App/Feature/CheckoutCoordinator.swift \
  "Goal: add retry support without changing the public API. Review this plan for missing steps and risk."

scripts/claude-code-consult.sh solution <<'EOF'
Goal: remove duplicate analytics events during app startup.
Constraints:
- keep the existing tracker interface
- avoid adding global state
Proposed solution:
- move initialization behind a lazy provider
- gate emission on the first active session
Question:
- what failure modes or simpler alternatives do you see?
EOF

scripts/claude-code-consult.sh stuck \
  --file Sources/Auth/AuthManager.swift \
  --file Tests/AuthTests/AuthManagerTests.swift:1-200 <<'EOF'
Symptoms:
- tests pass individually but fail in suite order
Attempts:
- reset singletons in tearDown
- removed shared clock override
Question:
- what are the most likely root causes and next debugging steps?
EOF
```

## Prompt Quality

Do:

- state the decision or blocker clearly
- include constraints and prior attempts
- ask for critique, risks, missing assumptions, or next debugging steps
- keep attached context tightly scoped
- prefer excerpts over whole files when the context is large

Do not:

- ask Claude to inspect the whole repository by default
- outsource the primary analysis before doing your own local work
- treat Claude's answer as authoritative when it conflicts with observed code or tests

## Output Handling

Treat Claude as a reviewer.

- Compare its answer against the codebase and the user's goal.
- Pull out the useful parts: missing risks, sharper tradeoffs, alternate debugging steps.
- Ignore speculative advice that is not grounded in the provided context.

## Failure Handling

If the script reports that `claude` is missing, install or expose the CLI first.

Check auth with:

```bash
claude auth status
```

If it reports `"loggedIn": false` in an environment with access to the normal credentials, run:

```bash
claude auth login

From rcedwards/blaude-bode, MIT.

More from rcedwards/blaude-bode