claudecode-headless

Fsm Lab — Development skill for Claude Code

Development community

The GHA-native agent execution OS — engine-agnostic (Claude Code + Codex adapters): intake/conductor/dispatch/workers/reports/watchdog, epochs, budgets, dual-bucket overflow.

How to install Fsm Lab

This entry records only its repository, not the path inside it, so there is no exact command to give. Open claudecode-headless/fsm-lab and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Fsm Lab does

The GHA-native agent execution OS — engine-agnostic (Claude Code + Codex adapters): intake/conductor/dispatch/workers/reports/watchdog, epochs, budgets, dual-bucket overflow. Mock-first at every layer; public repo = free runner minutes.

Alternatives in Development

Knowledge Work Plugins — Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork 9734 125 18 10.5k ★
Puppetmaster — Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory 340 ★
Conductor Implement 334 ★

README

fsm-lab — The GHA-Native Agent Execution OS (engine-agnostic: CC + Codex)

**Charter (reframed 2026-09-24):** this repo is the **GHA-based agent harness / execution engine / OS** — not a CC-GHA adapter. The agent harnesses (Claude Code, OpenAI Codex CLI) are **replaceable executors** beneath the OS: the intake door, conductor, dispatch budgets, dual-bucket workers, union verification, watchdogs, epochs, and the alert lane are engine-agnostic machinery; each engine is one adapter (`worker/cc-adapter.mjs`, `worker/codex-adapter.mjs`) behind the shared `engineTurn` contract. The application layer grows on top (first: the agent review kit).

**Origin (Track-1 Task 43 lab, kept for history):** The de-risking question was: can a single, local, continuously-running agent harness (like Claude Code) be converted into a **distributed system of short-lived GHA jobs that is collectively continuous** — stateful, parallel, watched, and bounded — using only GitHub-native constructs? (Answer: yes — see EVIDENCE.md; the system now runs production-grade with two engines.)

stateless today                          stateful here
─────────────────                        ───────────────────────────────
trigger ─▶ one agent turn ─▶ reply       conductor ─▶ FSM(state) ─▶ dispatch workers ─┐
(HTTP request/response)                  ▲   ▲            │ lease + event report      │
                                         │   │            ▼                           │
                              chain ─────┘   └── watchdog (re-prime, breaker)        │
                              (GITHUB_TOKEN self-dispatch: finite jobs, infinite loop) ◀──────┘

The architecture in one page

Concern	Mechanism	Where
State anchor	versioned `state.json` + rotating `journal-*.jsonl` on the `fsm-state` git branch; CAS = FF-only push; corruption recovery = git-history walk; event-sourced rebuild = journal replay	`lib/store.mjs`
The process (FSM)	pure transit