Workcells

Workcells is a tmux-native, file-gated multi-worker AI development system. It turns one bounded task into a reviewed, QA-verified, merged pull request by running a role-separated worker team against explicit signal files.

The current public shape is a productized extraction of a proven private workcell pattern. It is intentionally shell-first: operators can inspect tmux panes, signal JSON, supervisor logs, worker verdicts, and final status files without trusting hidden daemon state.

Worker Model

Worker	Role	Responsibility
worker-1	implementer	RED/GREEN/REFACTOR implementation loop
worker-2	reviewer	Code quality, constitution, diff, and task-contract review
worker-3	QA verifier	Human-like packaged-app E2E walkthroughs with A/B/C/D grade
worker-4	handler	GitHub comment/merge/escalation and canonical ship status

worker-3 is deliberately separate from worker-2. A code review pass is not a user-story pass. Tasks declare e2e_qa_scope as full, smoke, or none.

Install

This repository is a v0.1 skeleton. Clone it and put bin/workcell on PATH:

git clone https://github.com/psingley/workcells.git
cd workcells
ln -sf "$PWD/bin/workcell" "$HOME/.local/bin/workcell"

Required local tools:

bash 4+, jq, git, gh, tmux, omc, codex, node 22+, npm or pnpm

Quick Start

In a target repo:

workcell init
workcell doctor --run-ready
workcell run T123

workcell run opens the default tmux layout:

• leader pane on the left
• worker-1 through worker-4 stacked top-to-bottom on the right
• supervisor visibility through the run metadata and signal-supervisor.log

During a run, inspect:

{{APP_ROOT}}/.omc/work-units/<run-id>/signals/
{{APP_ROOT}}/.omc/work-units/<run-id>/reports/signal-supervisor.log
{{PLAN_ROOT}}/.workcell-status.json

Public Contract

Read spec.md first. The important decisions are:

• B1-B10 remain hard invariants.
• The old informal B11 polling/nudge rule is retired as an invariant and replaced by an async coordination plan with supervisor visibility retained.
• worker-3 QA emits qa-result.<cycle>.json.
• harness drift emits harness-drift.json and aborts gracefully before workers start.
• worker-4 writes {{PLAN_ROOT}}/.workcell-status.json as the single canonical shipped marker after merge.

Status

This repo skeleton was authored under a sandbox that could not create ~/workcells directly. The contents are ready to move or push once filesystem and GitHub publication access are available.