jcode-workers

Files (2)

• SKILL.md
• reference.md

SKILL.md (first lines)

# /jcode-workers — OpenAI workers via jcode

Usually used from the `orchestrate` skill, which covers when to delegate, briefs, the
ledger, and verification. This skill covers **how** to run jcode well. The full
command, flag, and config facts are in `reference.md` next to this file. Read it when
you need something not covered here.

## Pick the model

| Model | Use for |
|---|---|
| `gpt-6.1-sol` | Default strong worker: implementation, tests, refactors, reviews. |
| `gpt-6-astra` | **Premium, very expensive (like Fable). Strictly when necessary**: only the most complex tasks where sol has demonstrably failed or clearly isn't enough. Never a routine default, second opinion, or reviewer. |
| `gpt-6-sol`, `gpt-6-luna`, `gpt-5.6-*`, `gpt-5.5` | Previous-generation or cheaper alternatives for a different take or when sol struggles on a routine task; see `reference.md`. |

**Astra rule:** before any `--model gpt-6-astra`, write a one-line justification in the ledger
(or tell the user, outside orchestration): why sol and Claude opus are insufficient for this specific
task. If you can't articulate it, use sol. Never use astra for exploration, reviews, or batches.

Reasoning effort can't be set per `jcode run`: every worker uses the config default
(`openai_reasoning_effort = "medium"`). To get more reasoning, switch model or escalate
instead. Changing the global default is the user's call.

## Everyday use (no orchestration setup needed)

These need no `jw init`. They log under `~/.claude/orchestration/adhoc/` and print the full
reply (capped at 100 lines). Always ask for a bounded answer so the reply stays small.
jcode's `auto_poke` can make the worker append a second full draft to its reply (seen in
testing), so also say "give a single final answer".

| Situation | Command |
|---|---|
| Exploring an unfamiliar codebase, "how does X work", "where is Y handled" | `~/.claude/bin/jw ask --cwd <repo> "<question>. Answer in ≤300 words with file:line references."` |
| Validating code you just wrote (before reporting it done) | `~/.claude/bin/jw review --repo <repo> [--base <ref>] ["focus area"]` |
| Web research (docs, release notes, current facts) | `jw ask "<question>. Cite source URLs."` (jcode uses OpenAI's native web search; see `reference.md`) |
| Second opinion on a bug or design choice | `jw ask --cwd <repo> "<question + evidence so far>"` (for a different take, try a cheaper model such as `--model gpt-6-luna`, not astra; a different take) |
| Small self-contained edit you'd rather offload | `jw ask --cwd <worktree> --write "<task + acceptance check>"`. Use a worktree, never your working copy. |

- `ask` is read-only unless `--write` is given; the read-only constraint is added to the prompt.
- `review` covers uncommitted changes vs `--base` (default `HEAD`) plus untracked files. It asks
  for findings with file:line, severity, and a failure scenario, plus an EVIDENCE block. Verified:
  it caught a planted off-by-one bug and reproduced it.
- Exploration answers are **leads**: verify the claims you'll act on with targeted reads.
- Run long asks and reviews in the background (`run_in_background: true`) and keep working.

## Mode 1: `jw run` (orchestrated subtasks)

```bash
~/.claude/bin/jw usage                               # before batches of more than 3 runs
cat > ~/.claude/orchestration/<slug>/briefs/<task>.md <<'EOF'
<brief from orchestrate/templates/task-card.md (one small card; includes the HANDOFF
 rule); MUST end by asking for an "EVIDENCE:" block>
EOF
~/.claude/bin/jw run --slug <slug> --task <task> --repo <repo> \
   --model gpt-6.1-sol [--base <ref>] [--timeout 1800] ~/.claude/orchestration/<slug>/briefs/<task>.md
```

What it does:
- Creates or reuses worktree `<repo>/.claude/worktrees/jw-<slug>-<task>` on branch
  `jw/<slug>/<task>`, and runs jcode there.
- Saves the full JSON to `~/.claude/orchestration/<slug>/runs/<task>.json`.
- Appends a ledger row, and prints only session / cwd / status / EVIDENCE.

Exit codes: `0` ok, `2` bad args, `3` jcode error or timeout (prints the stderr tail),
`4` empty reply, `75` quota exhausted (`usage_limit_reached` after jcode's own account failover;
prints `jw: quota exhausted on all accounts; fall back to a Claude worker`).

- **Parallel:** launch several `jw run` calls as separate background Bash commands
  (`run_in_background: true`). Each gets its own worktree, so they don't collide. Don't
  poll; wait for the completion notifications.
- **Read-only work** (reviews, audits, investigation): add `--no-worktree` to run in the
  repo itself, and say "do not modify any files" in the brief.
- **Cross-family review of Claude-written code:** `jw run --no-worktree --model gpt-6.1-sol`
  with a brief that names the branch/diff (`git diff <base>...<branch>`) and asks for
  findings with file:line, severity, and a concrete failure scenario. Verify each finding
  before acting on it.
- **Output hygiene:** never cat `runs/*.json` whole. If the EVIDENCE block isn't enough, use
  `jq -r .text runs/<task>.json | head -80`.

## Mode 2: multi-turn follow-up

```bash
~/.claude/bin/jw resume --slug <slug> --task <task> --cwd <worktree> [--model M] <session_id> "<follow-up>"
```
Use this for short corrections ("the check fails with X; fix it"). The session keeps its context
(verified). After ~3 resumes, or when the worker seems confused, start a fresh `jw run`
instead. Seed it with the notes file and a summary of what went wrong. That way jcode's
compaction rarely has to kick in.

**Checkpoint (HANDOFF):** when a run grew large or went off-track, resume it with "write a
HANDOFF: section to your notes file (done so far, files touched, what's left, next command,
open questions) and finish", then start a fresh, smaller `jw run` seeded from that HANDOFF.

## Coordinating workers: the message board (instead of jcode swarm)

Claude is the hub. Workers coordinate through an append-only board file, not through each other:
`~/.claude/orchestration/<slug>/board.md`, one line per message:
`[time] [worker] TYPE: text`, where TYPE is `DECISION | QUESTION | ANSWER | BLOCKER | HANDOFF | INFO`.

```bash
~/.claude/bin/jw post  <slug> orchestrator DECISION "API: parse(s: str) -> Ast; errors raise ParseError"
~/.claude/bin/jw board <slug> --since <last-line-seen> --type QUESTION,BLOCKER
```

- **Before fan-out**, post the shared contracts (interfaces, types, file ownership) as DECISIONs.
  Good contracts mean workers rarely need to talk.
- **Put this in every brief:** "Read ~/.claude/orchestration/<slug>/board.md first. Post
  interface decisions, questions, and blockers with
  `~/.claude/bin/jw post <slug> <your-task-id> <TYPE> \"...\"`. If a QUESTION blocks you,
  post it and finish your turn, reporting what's blocked. Re-read the board before finishing."
- **You moderate:** after each worker finishes, read only new QUESTION/BLOCKER lines
  (`--since`), answer with `jw post … ANSWER`, and wake whoever needs it with `jw resume`.
  Track the last line number you've read in the ledger's Next step.
- **Limit:** a `jcode run` worker can't receive messages mid-turn. Coordination happens at
  turn boundaries. Claude subagents use the same board (give them the same instruction).
- Posts are flock-protected, so concurrent writers are safe (verified with 3 parallel posts).

## Large batches: fan out with parallel `jw run`, not jcode swarm

From ritamgh/claude-skills, MIT.

More from ritamgh/claude-skills