pitroom 0.6.0

package/docs/backends.md

@@ -0,0 +1,113 @@
+# Worker backends
+
+Pitroom's core does everything that must be true for every worker: closed stdin,
+the git guard on `PATH`, recursion guard, timeouts and signals, snapshots and
+isolated copies, exact change tracking, reference verification, receipts and
+the fallback chain. A **backend** only translates between Pitroom and one worker
+CLI. That keeps adapters small (OpenCode is ~150 lines) and makes it impossible
+for a new adapter to skip a safeguard.
+
+```
+src/
+  backends/
+    types.ts            the Backend contract and shared types
+    index.ts            registry
+    opencode/           the reference adapter
+      index.ts          invocation, failure classification, models, doctor
+      events.ts         `--format json` stream → ParsedRun
+      profiles.ts       read / write permission profiles
+  core/                 lifecycle, process runner, prompt, refs, receipts, report
+  vcs/                  git snapshots, isolated copies, git guard
+```
+
+## The contract
+
+```ts
+interface Backend {
+  id: string;                 // "opencode", used in targets: "opencode:provider/model"
+  name: string;
+  capabilities: {
+    readOnly: 'permission-rules' | 'os-sandbox' | 'tool-allowlist' | 'approval-mode';
+    resume: 'by-id' | 'none';
+    reportsCost: boolean;
+    attachFiles: boolean;
+  };
+  binary(): string;                                     // PITROOM_<ID>_BIN > PATH > known install path
+  invocation(req: WorkerRequest): Invocation;           // pure
+  parse(stdout: string): ParsedRun;                     // pure, tolerant of a torn last line
+  failure(run, stderr, exitCode): Failure | undefined;  // kind drives the fallback chain
+  defaultModel?(): string | undefined;
+  resolveModel?(sessionId: string): string | undefined;
+  listModels?(): string[];
+  doctor(ctx): DoctorCheck[];
+}
+```
+
+`failure().kind` is `model-unavailable`, `rate-limited`, `auth` or `other`. Anything
+but `other`, when the worker did no work, makes the core try the next target.
+
+## Mapping Pitroom's modes
+
+The core decides the mode; the adapter must make the CLI enforce it with the
+CLI's **own** mechanism, and never with flags that switch safety off
+(`--yolo`, `--dangerously-*`, `bypassPermissions`, `danger-full-access`,
+`--auto`): the contract tests reject them.
+
+| | read | write / isolate | resume | cost |
+|---|---|---|---|---|
+| **OpenCode v2** (`run --standalone --format json`) | permission profile: edit denied, shell allowlist, `execute` and web off | profile: edits on, history-changing git, bulk deletes and `execute` denied | `--session <id>` | reported |
+| **Codex** (`exec --json --ignore-user-config`) | `-c sandbox_mode="read-only"` (OS sandbox) | `-c sandbox_mode="workspace-write"` (writes only in the working dir, no network), `approval_policy="never"` | `exec resume <id>` | tokens only |
+| **Claude Code** (`-p --output-format stream-json --verbose`) | `--safe-mode --restricted --strict-mcp-config`, `--permission-mode dontAsk`, tools `Read,Grep,Glob` only | same lockdown, tools `+Edit,Write,Bash`, `--disallowedTools Bash(git commit:*)`… | `--resume <id>` | `total_cost_usd` |
+| **Gemini CLI** (soon; `-p -o stream-json`) | `--approval-mode plan` | `auto_edit` + policy engine rules | index/latest only → `resume: 'none'` | tokens only |
+
+Whatever the CLI, the core still applies the git guard, closes stdin (Codex and
+Gemini otherwise read piped stdin into the prompt), sets `PWD` to the worker's
+directory, snapshots the tree and verifies references. `--isolate` runs in a
+standalone repository that reads the user's objects through `alternates`
+(not a `git worktree`), so no CLI can map it back to the user's checkout.
+
+## OpenCode v2 notes
+
+The OpenCode adapter targets OpenCode v2 (`doctor` fails on v1). What changed from v1, and why the adapter looks the way it does:
+
+- **`--standalone` is a safety requirement.** A plain `opencode run` attaches to OpenCode's shared background service, which was started with its own environment. The per-run permission profile (`OPENCODE_CONFIG_CONTENT`), the git guard on `PATH` and `PITROOM_ACTIVE` would then never reach the worker. With `--standalone` each run gets a private server that inherits them; the contract tests assert the flag for every mode.
+- **No `--dir`, and `$PWD` wins.** v2 takes its workspace from `$PWD`, not the process working directory. The core's process runner sets `PWD` to the worker's directory for every CLI; without it a worker started in an isolated copy edited the directory pitroom was launched from (found in a real crew run; the mock now reproduces it and the isolate tests fail without the fix).
+- **Permissions**: v2 calls the shell tool `shell` (v1: `bash`); profiles set both keys to the same rules. The new `execute` tool reaches namespaced tools (browser automation, the OpenCode API itself) and is denied in both modes. `write`/`edit` take `path`.
+- **Events**: `step_finish.tokens` has no `total` (summed from its parts); errors are `{type, message, status}`; a refused tool reports `Permission denied: <tool>`.
+- **Models and sessions**: `debug config` lists config sources (the model is `{providerID, model}`), sessions are exported with `session export`, and model ids accept a `#variant` suffix.
+- **Free tier**: OpenCode Zen free models can answer `403 FreeTierError` ("free tier can only be used from within OpenCode"). It is classified as `auth`, so the fallback chain moves on.
+- **Auto-update**: workers run with `OPENCODE_DISABLE_AUTOUPDATE=1`, so a run never upgrades OpenCode underneath the user.
+
+Recorded v2 streams live in `test/fixtures/opencode/{events,failures}/v2-*`; the v1 ones stay as parser regression tests.
+
+## Codex notes
+
+- **`--ignore-user-config`.** `~/.codex/config.toml` can define MCP servers, which run outside Codex's sandbox and could have side effects in a read-only run, and profiles that loosen the sandbox. Disabling servers one by one is not reliable (`-c mcp_servers.<name>.enabled=false` breaks on names containing dots or spaces), so workers ignore the file; auth still works. The model is the target's, or Codex's built-in default; `#effort` sets the reasoning effort (`codex:gpt-5.6-sol#low`, `codex:#low`).
+- **Resume takes no `-s`/`-C`**, so the sandbox always goes through `-c sandbox_mode=…`; the tests assert it for new and resumed runs.
+- **Login shells.** Codex runs commands through `zsh -lc`; macOS's `path_helper` and `~/.zprofile` reorder `PATH`, which hides the git-guard shim. The second guard layer (git's own env config: a `reference-transaction` hook and `pushInsteadOf`) holds regardless, for every worker.
+- **Stream**: `item.completed` items of type `error` are warnings (deprecated settings, skills budget), not failures; failures are top-level `error` / `turn.failed`, whose message is a JSON API error. The JSON stream does not name the model, so it is read from the session's rollout file. Cost is not reported.
+- **"Not supported when using Codex with a ChatGPT account"** comes back both for models the account cannot use and for models the installed Codex CLI is too old to know (seen with `gpt-6.1-sol` on 0.146, working on 0.159). It is `model-unavailable`, so the chain moves on, and the message suggests updating Codex.
+- **Node**: `codex` is a Node script (`#!/usr/bin/env node`); Pitroom runs such CLIs on its own Node 18+, since agents' shells often have an older Node first on `PATH`.
+
+## Claude Code notes
+
+- **Lockdown** (see the table): `--safe-mode` keeps the user's CLAUDE.md, skills, plugins, hooks and MCP out; `--restricted` removes command-running tools unless listed, confines file tools to the working directory and refuses `bypassPermissions`; `--permission-mode dontAsk` denies anything outside the allowlist instead of prompting. The init event of a real run lists exactly `Glob, Grep, Read` for a read-only worker, no MCP servers, and only Claude Code's built-in plugins.
+- **Not `--bare`**: it disables OAuth, which would break Claude subscriptions.
+- **Argument order**: `--tools`, `--allowedTools` and `--disallowedTools` take lists; non-list options follow them and the prompt comes after `--`, so no list can swallow it.
+- **Errors**: an API error arrives as an assistant message with `is_api_error_message` (e.g. `authentication_failed`, "OAuth session expired"); it is not counted as work, so the fallback chain can move on.
+- **Model**: the init event names it. The user's default is often an Opus-class model; `doctor` warns and suggests `-W claude:haiku`.
+
+## Adding a worker
+
+1. Create `src/backends/<id>/index.ts` exporting a `Backend`; keep CLI knowledge
+   (flags, event format, error wording, model listing) in that folder.
+2. Register it in `src/backends/index.ts` (and drop the id from `PLANNED`).
+3. Record real fixtures under `test/fixtures/<id>/`:
+   - `events/*.jsonl`: stdout of real runs (one read, one write), home paths replaced;
+   - `failures/<name>.stdout.jsonl` + `.stderr.log`: e.g. an unknown model;
+   - `expected.json`: session id, step count, token total, answer prefix, failure kinds.
+4. `npm test`: `test/backends.test.mjs` runs the contract suite against every
+   registered backend automatically (capabilities, no bypass flags, read ≠ write,
+   prompt in argv, optional model/session/files, parsing, failure classification).
+5. Add an end-to-end mock for the CLI if its behaviour differs materially, and a
+   row to the table above and to the README.

package/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/pitroom.mjs\" hook-card",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// SessionStart hook: puts the `using-pitroom` skill into the primary agent's
+// context, so it considers delegating before it starts reading and editing, and
+// tells it the exact command to run even if `pitroom` is not on PATH.
+// Dependency-free and fast: it only reads one file.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Inside a Pitroom worker there is nothing to delegate to.
+if (process.env.PITROOM_ACTIVE === '1') process.exit(0);
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+let skill = '';
+try {
+  skill = fs.readFileSync(path.join(root, 'skills', 'using-pitroom', 'SKILL.md'), 'utf8');
+} catch {
+  process.exit(0); // broken install: stay silent rather than break the session
+}
+const body = skill.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
+// Fallback when `pitroom` is not on PATH: the installed launcher (it picks a Node 18+),
+// else this Node if it is new enough, else plain `node`.
+const cli = path.join(root, 'dist', 'pitroom.mjs');
+const launcher = path.join(os.homedir(), '.local', 'bin', 'pitroom');
+const nodeOk = Number(process.versions.node.split('.')[0]) >= 18;
+const fallback = fs.existsSync(launcher) ? `"${launcher}"` : `"${nodeOk ? process.execPath : 'node'}" "${cli}"`;
+const command = fs.existsSync(cli) || fs.existsSync(launcher) ? `\`pitroom\`, or if that is not on PATH: \`${fallback}\`` : '`pitroom`';
+
+const context = `<pitroom>
+You have Pitroom: a development workflow as skills, and cheap worker agents that read, search, implement and review for you. Run it as ${command}.
+It is optional: use it when it helps or when the user asks for it, otherwise work as you normally would. Below is the 'using-pitroom' skill, a menu of what it offers; load a pitroom-* skill with your Skill tool when you choose to use it.
+
+${body}
+</pitroom>`;
+
+// Cursor reads additional_context; Claude Code reads hookSpecificOutput. Emit only one,
+// because Claude Code would otherwise inject the text twice.
+const out = process.env.CURSOR_PLUGIN_ROOT
+  ? { additional_context: context }
+  : { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context } };
+process.stdout.write(`${JSON.stringify(out)}\n`);

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "pitroom",
+  "version": "0.6.0",
+  "description": "A free pit crew for your expensive coding agent: the superpowers development workflow, run by cheap workers. Delegate research, fixes, tests, reviews and whole plans from Claude Code, Codex or any agent to OpenCode, Codex or Claude Code workers, with receipts that prove the savings.",
+  "type": "module",
+  "author": "TahaAtas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ATASTECH/pitroom.git"
+  },
+  "homepage": "https://github.com/ATASTECH/pitroom#readme",
+  "bugs": {
+    "url": "https://github.com/ATASTECH/pitroom/issues"
+  },
+  "bin": {
+    "pitroom": "dist/pitroom.mjs"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "hooks",
+    ".claude-plugin",
+    ".codex-plugin",
+    "docs/backends.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "agent",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cost",
+    "delegation",
+    "llm",
+    "opencode",
+    "subagent",
+    "tokens",
+    "workflow",
+    "code-review",
+    "tdd",
+    "planning"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/pitroom-brainstorming/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: pitroom-brainstorming
+description: Use when you or the user want a feature, component or behaviour change designed before it is built - explores intent, requirements and design with the user and gets approval before implementation.
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by classifying how much process the request needs, then work
+through your path: understand the context, refine the idea, present a
+design, and get your human partner's approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any
+project, or take any implementation action until you have told your
+human partner what you intend and they have approved it. This applies
+to EVERY task on EVERY path below — the ceremony scales with the task;
+the approval gate never does.
+</HARD-GATE>
+
+## Three Paths
+
+Before your first question, classify the request and say the
+classification out loud — "this looks bounded, so I'll present a short
+design here rather than write a spec" — so your human partner can
+override it:
+
+- **Spike** — a feasibility question ("can we...", "is it possible...",
+  "quick and dirty is fine") whose output is an answer, not code you
+  keep. Present the question and what you'll try in 2-3 sentences, get
+  a nod, then find out as cheaply as correctness allows. No design
+  doc, no spec file. Report findings as a recommendation; anything you
+  built stays labeled throwaway.
+- **Bounded** — a well-scoped change to code that already exists in
+  this repo: a new flag, a small endpoint, a one-file fix.
+  Understanding the kind of app is not enough — bounded means the flow
+  you are changing is already here to read. If there is no existing
+  flow to change, the task is not bounded. Ask the clarifying
+  questions that matter, present a short design IN CHAT (a few
+  sentences to a few short paragraphs), and STOP. Implementation
+  starts only after your human partner says yes to that design — a
+  bounded task's approval is as hard a gate as an architectural
+  one. No spec file, no implementation plan document.
+- **Architectural** — new projects, new subsystems, changes that
+  restructure how components fit together or alter interfaces others
+  depend on. Follow the full process: questions, approaches, sectioned
+  design, written spec, then the `pitroom-writing-plans` skill.
+
+When in doubt between two paths, take the heavier one. The ratchet is
+one-way: hidden complexity discovered mid-task upgrades the path —
+stop, say so, and step up. Nothing downgrades mid-task.
+
+## Anti-Pattern: "Too Simple To Need Approval"
+
+Every path ends with your human partner approving your intent before
+implementation. A todo list, a single-function utility, a config
+change — the design may be two sentences in chat, but you MUST present
+it and get approval. "Simple" tasks are where unexamined assumptions
+cause the most wasted work. What scales with simplicity is the
+artifact, never the approval.
+
+This gate is for creative work: a feature, a component, a behaviour
+change. A typo, a one-line fix the user spelled out, or a value the
+user named is not creative work; `using-pitroom` leaves those to you
+without this skill.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
+| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
+| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
+| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
+| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
+| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
+| "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. |
+
+## Checklist
+
+Classify first, announce the path, then create a task for each item on
+your path and complete them in order.
+
+**Spike:**
+1. **Explore project context** — enough to frame the probe — let workers do the reading (`pitroom-research` for one area, `pitroom-crew` for several) and read their answers, not the files
+2. **Present question + probe plan** — 2-3 sentences
+3. **Get approval** — a nod is enough
+4. **Investigate** — as cheaply as correctness allows
+5. **Report findings** — a recommendation; label anything built as throwaway
+
+**Bounded:**
+1. **Explore project context** — check files, docs, recent commits — let workers do the reading (`pitroom-research` for one area, `pitroom-crew` for several) and read their answers, not the files
+2. **Ask clarifying questions** — one at a time, the ones that matter
+3. **Present short design in chat** — approach, files touched, testing
+4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate
+5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document
+
+**Architectural:**
+1. **Explore project context** — check files, docs, recent commits — let workers do the reading (`pitroom-research` for one area, `pitroom-crew` for several) and read their answers, not the files
+2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Present design** — in sections scaled to their complexity, get user approval after each section
+5. **Write design doc** — save to `docs/pitroom/specs/YYYY-MM-DD-<topic>-design.md` and commit
+6. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+7. **User reviews written spec** — ask user to review the spec file before proceeding
+8. **Transition to implementation** — invoke `pitroom-writing-plans` to create implementation plan
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Classify: spike / bounded / architectural" [shape=diamond];
+    "Present question + probe (2-3 sentences)" [shape=box];
+    "Ask clarifying questions (bounded)" [shape=box];
+    "Present short design in chat" [shape=box];
+    "Human approves?" [shape=diamond];
+    "Investigate; report recommendation" [shape=doublecircle];
+    "Implement via normal workflow (no plan doc)" [shape=doublecircle];
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke pitroom-writing-plans" [shape=doublecircle];
+    "Hidden complexity? Upgrade path" [shape=box];
+
+    "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
+    "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
+    "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
+    "Present question + probe (2-3 sentences)" -> "Human approves?";
+    "Ask clarifying questions (bounded)" -> "Present short design in chat";
+    "Present short design in chat" -> "Human approves?";
+    "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
+    "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
+    "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke pitroom-writing-plans" [label="approved"];
+}
+```
+
+**Terminal states are path-bound.** Architectural: the ONLY skill you
+invoke after brainstorming is `pitroom-writing-plans` — never frontend-design,
+mcp-builder, or any other implementation skill. Bounded: after
+approval, implementation proceeds directly through the normal
+development workflow; no plan document. Spike: the terminal state is a
+reported recommendation.
+
+## The Process
+
+The subsections below serve the bounded and architectural paths (a
+spike stops at "present the probe, get a nod"). Sections from
+**Exploring approaches** onward are architectural-path depth — for
+bounded work, context plus a few questions plus a short in-chat design
+is the whole process.
+
+**Understanding the idea:**
+
+- Check out the current project state first (docs, recent commits); for code, ask a worker for a map (`pitroom-research`) instead of reading it yourself
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+- YAGNI ruthlessly - remove unnecessary features from every approach and design
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design (architectural path)
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/pitroom/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Commit the design document to git
+
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+**Second read (optional, for a long spec):** a read-only worker applies [spec-document-reviewer-prompt.md](spec-document-reviewer-prompt.md):
+
+```bash
+sed "s#{{SPEC_FILE}}#docs/pitroom/specs/<file>.md#" "<this skill's folder>/spec-document-reviewer-prompt.md" > "$TMPDIR/spec-review.md"
+pitroom run --task-file "$TMPDIR/spec-review.md"
+```
+
+Weigh its findings like any review (`pitroom-receiving-review`).
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec self-review (and the optional second read), ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec self-review. Only proceed once the user approves.
+
+**Implementation:**
+
+- Invoke `pitroom-writing-plans` to create a detailed implementation plan
+- Do NOT invoke any other skill. `pitroom-writing-plans` is the next step.

package/skills/pitroom-brainstorming/spec-document-reviewer-prompt.md

@@ -0,0 +1,22 @@
+You are a spec document reviewer. Verify that this spec is complete and ready for implementation planning.
+
+Spec to review: {{SPEC_FILE}}
+
+## What to check
+
+| Category | What to look for |
+|---|---|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Requirements ambiguous enough to make someone build the wrong thing |
+| Scope | Focused enough for a single plan, not several independent subsystems |
+| YAGNI | Unrequested features, over-engineering |
+
+## Calibration
+
+Only flag issues that would cause real problems during implementation planning: a missing section, a contradiction, a requirement that could be read two ways. Wording, style and "some sections are less detailed than others" are not issues. Approve unless there are serious gaps that would lead to a flawed plan.
+
+## Answer
+
+SUMMARY: STATUS: APPROVED, or SUMMARY: STATUS: ISSUES FOUND (N)
+In DETAILS: each issue as "[Section]: issue - why it matters for planning", then RECOMMENDATIONS (advisory; they do not block approval).

package/skills/pitroom-crew/SKILL.md

@@ -0,0 +1,80 @@
+---
+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. Two to five parts is the sweet spot; at most `maxParallel` workers (default 4) run at a time, 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:
+1. **Focused:** one problem domain ("fix agent-tool-abort.test.ts", not "fix all the tests").
+2. **Self-contained:** the error messages, test names and file paths it needs.
+3. **Constrained:** what not to change ("do not change production code", "tests only").
+4. **Specific about the answer:** "the root cause and what you changed", "file:line for each".
+
+```text
+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
+
+```bash
+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 --json`: one JSON line per change (`queued`, `started`, `progress`, `fallback`, `done`/`failed`, then `all-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 they can see the same table live with `pitroom watch -g NAME` in a terminal.
+
+While workers run, do the parts you kept for yourself.
+
+## 5. Collect, verify and merge
+
+```bash
+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 `-i` crews: review each patch (`pitroom review <run>` or `pitroom show <run> --patch`), then `pitroom apply -g NAME`. It applies in order and stops at the first conflict; fix that one with `pitroom 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, lower `maxParallel` (config or `PITROOM_MAX_PARALLEL`).
+- Stop everything: `pitroom stop -g NAME` (running and queued).