Spec Kit Workflow Cockpit

Let agents execute. Keep the decisions.

A terminal cockpit for Spec Kit workflows. Follow execution, review feature documents, and decide what happens next without leaving the terminal.

Quickstart | Configuration | Architecture | Contributing

Why Cockpit?

An automated workflow still needs a place for human judgment. Workflow Cockpit puts execution context and review in the same interface:

• Know where you are. See the branch, current node, engine status, and workflow Runway.
• Review before deciding. Browse Feature Files and read formatted Markdown at a gate.
• Choose explicitly. Submit only the workflow's declared options, with confirmation.
• Follow execution. Watch bounded live Engine Output without treating it as workflow state.
• Keep ownership clear. Each Cockpit session owns exactly one run in one project/worktree.

Cockpit is a standalone Python + Textual application. It invokes the installed specify CLI for workflow actions and reads persisted run files for authoritative state. It never modifies the engine or imports its internals. Feature Files show the current feature directory, not a Git diff.

Relationship to AgentMux

If you're familiar with AgentMux, you might wonder why there’s another tool.

AgentMux was my initial attempt at building a deterministic multi-agent pipeline via tmux. Even back then, I wanted to combine AgentMux with Spec Kit. But while I was working on it, Spec Kit introduced its own native workflows — which solved the underlying pipeline problem much more cleanly and even introduces the flexibility I actually was looking for.

Instead of forcing Spec Kit into AgentMux, it made far more sense to just build a dedicated TUI directly on top of the workflow engine.

So for Spec Kit projects, Cockpit essentially replaces AgentMux. AgentMux remains available as a standalone experiment for custom multi-agent setups outside of Spec Kit.

Prerequisites

• Python 3.10 or newer and Git.
• Linux, macOS, and WSL are supported. Native Windows is explicitly unsupported; use WSL.
• A terminal at least 88 columns by 36 rows. Smaller windows show a resize prompt.
• A workflow-capable specify CLI, installed separately. Cockpit accepts >=1.0,<2.0 and probes for the required workflow commands and flags; a version number alone is not sufficient. Interactive gates use the engine's builtin input() prompt, so they are supported for any CLI that passes the probe, not only the release the contract was recorded against. Embedded workflows (type: workflow steps) need specify 1.1.3 or newer; older engines never emit them and keep working unchanged.
• An initialized Spec Kit project containing .specify/, in a Git worktree with at least one commit.
• An enabled, installed workflow and the coding-agent integration it needs, configured and authenticated before starting a run.

Use your Spec Kit distribution's installation and initialization instructions. Cockpit does not install the engine, initialize projects, or configure agent credentials. The supported CLI contract is described in Context and Scope.

Installation

From the root of a source checkout of spec-kit-workflow-cockpit:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
workflow-cockpit --help

Keep this environment active when using the commands below. The repository is named spec-kit-workflow-cockpit; the Python distribution and terminal command are workflow-cockpit.

To install without cloning, pull the package straight from the repository:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install "git+https://github.com/markuswondrak/spec-kit-workflow-cockpit.git"
workflow-cockpit --help

Pin a revision for reproducibility by appending @<ref> to the URL, for example ...workflow-cockpit.git@main or a commit hash.

To build and install a wheel instead, start from the checkout in an activated environment:

python -m pip install build
python -m build
python -m pip install dist/workflow_cockpit-*.whl

Use a fresh dist/ directory so the wildcard selects one wheel. This installation path does not assume a PyPI release is available. See Contributing for the clean-environment artifact smoke check and editable development setup.

Quickstart

In your initialized Spec Kit project, with a compatible specify on PATH and a workflow already installed:

workflow-cockpit --check
workflow-cockpit

The first command checks the platform, Git worktree, project initialization, and engine compatibility without opening the UI. Resolve any reported failures before continuing. It does not check agent authentication or whether all workflow commands are installed.

1. Select a workflow with the arrow keys or j/k, then press Enter to configure it.
2. Fill in its required inputs and activate START RUN. A dirty worktree requires confirmation.
3. Follow progress in the Runway and Engine Output.
4. At a gate, review the Feature Files, choose a declared option, and confirm your decision.
5. Follow the run to its outcome, or use Cockpit's Abort action to stop it.

To target a project from elsewhere, pass --project /path/to/project. To use a particular engine installation, pass --specify /path/to/specify. Both options also work with --check.

Run Context for Your Agent

At start, Cockpit installs its bundled cockpit-run-context skill into your project's agent so it can read the current run. Ask your agent about the run and it reports the workflow, status, active gate, and Feature Files from the authoritative run files:

The destination follows .specify/integration.json:

Integration	Installed to
claude	.claude/skills/cockpit-run-context/SKILL.md
github-copilot	.github/skills/cockpit-run-context/SKILL.md
opencode	.opencode/skills/cockpit-run-context/SKILL.md
other / undeclared	.agents/skills/cockpit-run-context/SKILL.md

An existing skill directory is left untouched, so local edits are never overwritten. --check does not install anything. The installed file is an ordinary worktree change; commit or ignore it as you prefer. The skill reads the stable index at .specify/workflows/runs/current_run, which Cockpit rewrites after each Start. Cockpit also writes current_run.json next to it, a pointer-only JSON twin for programs; both always name the same run, and a reader that finds them disagreeing reports the disagreement instead of guessing.

Scripting and Other Frontends

Three subcommands expose the same lifecycle core the TUI uses, so a script or another frontend can read and drive a run without the UI. All three accept the global --project and --specify options.

workflow-cockpit --project /path/to/project context --json
workflow-cockpit --project /path/to/project context --json --file specs/007-x/spec.md
workflow-cockpit --project /path/to/project install
workflow-cockpit --project /path/to/project serve

context --json prints one versioned JSON object (the file view) describing the current run: run identity, workflow, branch, engine status, current step (including a composed run's inner scope), the open gate with exactly its declared options, the projection the UI renders, a bounded Feature Files index, and per-source conditions. --file RELATIVE_PATH adds one bounded file read and must name a file inside the declared Feature Files index. The command is read-only: it never writes, never takes the ownership claim, and never signals a process. Exit code 0 whenever an envelope is produced — including when there is no run or a source is missing — and 2 only for no discoverable project or invalid arguments.

install is the single install/update path for frontend artifacts. It prints one line per artifact (<outcome> <relative-path> [reason]) and exits 0 even when an individual artifact fails; 2 means no project was found. An artifact is either user-editable (installed once, then never overwritten) or managed (replaced atomically when its packaged version differs).

serve starts a detached host that owns the run over a Unix socket at .workflow-cockpit.sock (gitignored) and speaks line-delimited JSON: list, validate, start, status, gate, decide, abort, adopt, and resume. It holds the same ownership claim the TUI holds, outlives frontend disconnects, and exits when the run is terminal or paused with no client connected, releasing the claim. A second host in the same worktree is refused with host_already_running. serve is POSIX-only (Unix domain sockets and process groups); native Windows is out of scope for it, while context and install stay portable.

A frontend that needs to detect an incompatible shape records the envelope's schema_version and the host's protocol_version, and on a mismatch runs workflow-cockpit install once, re-reads its managed artifact, and reports any residual incompatibility to the user. The contract is described in ADR-0017.

Try the Extended Flow

The repository is dogfooded against the published spec-kit-extended-flow bundle. The feature flow uses the standard Spec-Kit lifecycle with specification and plan review gates:

Specify -> Spec Review -> Plan -> Plan Review -> Tasks -> Analyze -> Implement -> Converge ->
Documentation -> Finish

From an initialized Spec Kit project at this checkout's root, with your chosen agent integration already configured, install the released Extended Flow from GitHub:

scripts/setup-speckit.sh --source github

Then start the Cockpit, choose Spec-Kit Extended Flow — Feature Flow, and describe your change in the spec input. The integration input defaults to auto, using the project's initialized integration. Both review gates offer approve or reject; rejection aborts the feature workflow. Select Quick Flow for trivial changes.

The Extended Flow preset supplies the unattended runtime context, while its extension supplies documentation reconciliation, finish, and Quick Flow commands. The bundle also installs the standard Spec-Kit bug extension. For local development against an unreleased checkout, use:

scripts/setup-speckit.sh --source local --path ../spec-kit-extended-flow

See Contributing for the preferred dogfooding path and the local development variant.

Configuration

Workflow selection and input values are configured in the UI. There is no general Cockpit configuration file.

Setting	Purpose and default
--project PATH	Project root; otherwise discover the nearest .specify/ in the current directory or its parents.
--specify PATH	Engine executable; takes precedence over WORKFLOW_COCKPIT_SPECIFY, then specify on PATH.
--check	Print preflight results and exit without opening the UI.
--style NAME	Override appearance; otherwise use the project's default integration, with neutral fallback.
EDITOR	Optional external editor for Feature Files while paused at a gate.

Built-in styles are cockpit, claude, github-copilot, and opencode. Styles change colors, not the agent integration or workflow behavior. Project defaults come from .specify/integration.json; custom styling templates live in .specify/cockpit/templates/. Use the neutral template as a schema example. Custom templates should use their own names; they do not override built-ins.

Use specify to manage installed workflows and their definitions under .specify/workflows/. Persisted files in .specify/workflows/runs/<run-id>/ remain the authoritative run state, while .specify/feature.json identifies the feature directory used for review. See Crosscutting Concepts for styling and read-model conventions.

Safety and Limits

Cockpit owns one engine process group, not a fleet of agents or multiple concurrent runs. It is not a sandbox: workflow steps and agents operate with the permissions of the environment in which you launch them. Review your workflow and agent configuration before starting.

Catchable SIGINT, SIGHUP, and SIGTERM delivered to the Cockpit process trigger a bounded best-effort abort and cleanup of its recorded engine process group without a confirmation prompt. The headless host applies the same rule on a catchable death and when it releases a terminal or unattended run, so it never abandons a live engine process. There is no cleanup guarantee for SIGKILL, host loss, power loss, or interpreter failure: Cockpit cannot run cleanup it never receives, and the engine process group may be left running.

context --json is strictly read-only, and serve owns the same single claim the TUI owns: a second host in one worktree is refused rather than silently taking over. The host adds one file to your worktree, the gitignored .workflow-cockpit.sock; serve appends it to .gitignore when it is absent.

Documentation and Requirements

Documentation follows arc42, with twelve sections indexed in docs/architecture/README.md, numbered decisions alongside it, and a shared glossary. The layout is designed for focused reading by both people and coding agents, not for loading the entire documentation set into every conversation.

Start here	What it contains
Architecture index	Goals, constraints, boundaries, components, runtime, deployment, and quality context.
Functional requirements	Product promise, goals, and functional requirements.
Quality requirements	Quality scenarios and acceptance targets.
Backlog	Open story slices and deferred work, including the E01 OpenCode adapter.
Decision log	Numbered architecture decision records.
Glossary	Pinned terms such as Run, Gate, Feature File, and Runway.
Agent instructions	Always-on repository constraints and commands.

AGENTS.md is the only always-on context. Load the matching architecture section on demand; strategy, quality scenarios, and the AI Debt Register are reference-only. Code establishes behavior; documentation establishes intent and constraints. Conflicts should be surfaced rather than silently reconciled.

For the rationale behind this documentation approach, read the documentation context article.

Contributing

See CONTRIBUTING.md for local setup, exact lint and test commands, artifact verification, and the preferred dogfooding workflow, and RELEASING.md to cut a release. Develop repository changes through the Extended Flow and review its gates in Cockpit whenever practical.

CI runs Ruff and the unit, Textual, contract, PTY, and documentation suites on Linux and macOS with Python 3.10, 3.11, and 3.12. A dependent job builds the sdist and wheel, then checks installation in a fresh environment. A tag on main that matches the package version runs the Release workflow, which re-verifies the tagged commit, builds the artifacts, and publishes a GitHub Release with generated notes. WSL verification is run locally using the same quality commands in the contributor guide.

License

MIT.