pitroom-crew
Use when facing two or more independent tasks - questions about different areas, unrelated bugs or failing test files, the same mechanical change in separate modules - to run Pitroom workers in parallel, watch them live and merge their results.
ATASTECH · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ATASTECH/pitroom --skill pitroom-crewAbout this skill
name: pitroom-crew description: Use when facing two or more independent tasks - questions about different areas, unrelated bugs or failing test files, the same mechanical change in separate modules - to run Pitroom workers in parallel, watch them live and merge their results.
Running a Pitroom crew
Several workers at once, each with its own session (and, for changes, its own isolated copy of the project): one worker per independent problem domain. You split the work, watch, and merge.
When to use
- Several questions about different areas of the code.
- Three or more test files failing with different root causes; subsystems broken independently.
- The same mechanical change in separate modules.
Don't use it when the failures are related (fixing one might fix the others: investigate them together first), when understanding needs the whole system, when you don't yet know what is broken (exploratory debugging: pitroom-debugging), or when workers would edit the same files. The tasks of a written plan run through pitroom-driven-development, which has its own rules for parallel tasks.
1. Split
Parts must be independent: no part needs another's result, and no two parts edit the same file. Start as many workers as there are independent parts: up to 20 run at a time by default (maxParallel, 30 at most), the rest queue. Keep dependent or judgment-heavy parts for yourself.
2. Write focused briefs
Each worker sees only its brief, so each brief is:
- Focused: one problem domain ("fix agent-tool-abort.test.ts", not "fix all the tests").
- Self-contained: the error messages, test names and file paths it needs.
- Constrained: what not to change ("do not change production code", "tests only").
- Specific about the answer: "the root cause and what you changed", "file:line for each".
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0
These look like timing issues. Find the real cause: replace arbitrary timeouts with
event-based waiting, or fix the abort implementation. Do NOT just increase timeouts.
Answer with the root cause and what you changed.
pitroom-research and pitroom-implement have more brief templates.
3. Start
pitroom crew -g auth-audit \
"Map how sessions are created in src/auth; file:line for each step." \
"List every place that reads the session cookie outside src/auth; file:line." \
"Which tests cover session expiry? List files and what each asserts."
Read-only by default. For changes add -i (each worker edits its own isolated copy): pitroom crew -i -g lint-fix "Fix the lint errors in src/a" "Fix the lint errors in src/b". Never parallel --write; Pitroom refuses it.
4. Watch
Follow the group live without polling:
pitroom watch -g NAME --brief: one card line when a worker starts and one when it ends, then a total; the user can read it, so prefer it in a host that shows monitor output (Claude Code's Monitor tool).pitroom watch -g NAME --json: one JSON line per change (queued,started,progress,fallback,done/failed, thenall-done). Run it through your host's background or monitor facility so each line reaches you as it happens; it exits by itself when the group is done.- No such facility:
pitroom wait -g NAME --timeout 540, and call it again while it exits with 75. pitroom status -g NAME: one table snapshot.- Tell the user how to see it live:
pitroom dash --detachprints the address of a read-only page on 127.0.0.1 with every run. Open it in the app's own built-in browser or preview pane when you have one (not with--open, which launches the system browser), and otherwise give the user the address; orpitroom watch -g NAMEin a terminal.
While workers run, do the parts you kept for yourself.
5. Collect, verify and merge
pitroom wait -g NAME --brief # one line per worker: state + SUMMARY
pitroom show <run> # the full report of the ones you need
- Read each summary and understand what changed.
- Check for conflicts: did two workers touch the same code or contradict each other?
- Verify what you will rely on (
refs:lines help), then combine the findings in your own words. - For
-icrews: review each patch (pitroom review <run>orpitroom show <run> --patch), thenpitroom apply -g NAME. It applies in order, stops at the first conflict and refuses a patch that deletes files (decide whether the deletion is wanted, then--allow-delete); fix that one withpitroom run --continue <run> "…"or by hand, then apply the rest. - Run the full test suite yourself afterwards, and spot-check: workers make systematic errors.
When things go wrong
- A worker failed or timed out: retry that part once with a sharper brief, or do it yourself.
- Rate limits: the fallback chain handles single failures; if many fail at once, lower
maxParallel(config orPITROOM_MAX_PARALLEL) or spread the parts over more than one worker. - Stop everything:
pitroom stop -g NAME(running and queued).