stagent

stagent

English | 简体中文 | 日本語 | 한국어 | Français | Deutsch | Español

A Claude Code plugin that runs config-driven development workflows as a state machine. You declare stages, transitions, and inputs in a single workflow.json; the plugin's hooks and scripts drive the loop.

Two modes:

• Cloud (default) — state mirrored to a hosted webapp with a live browser viewer, cross-machine resume, and zero project-dir footprint.
• Local — state and artifacts live under <project>/.stagent/, no network.

Quick Start

Installation

Run this command

claude plugin marketplace add jie-worldstatelabs/stagent && claude plugin install stagent@stagent

Already installed? Update with:

claude plugin marketplace update stagent && claude plugin update stagent@stagent

Requires: Claude Code, jq, curl, git (cloud mode also relies on standard POSIX tools like sha256sum / shasum).

Run a workflow

Optional but recommended: sign in first to claim session ownership and better manage your past sessions.

/stagent:login

Start the default development workflow — it builds what you describe:

/stagent:start --flow=cloud://demo "Build a journaling app with MBTI insights inferred from journal entries"

The skill prints a live UI URL. Without sign-in, this is an anonymous, publicly viewable session — anyone with the link can watch the state machine run in real time (stage timeline, rendered artifacts, git diff baseline..HEAD updating via SSE), and there is no owner.

For a fully offline run, switch to local mode:

/stagent:start --mode=local "Build a journaling app with MBTI insights inferred from journal entries"

Create your own workflow template

Define your own workflow from a natural-language prompt — stagent scaffolds the stages:

/stagent:create "plan, implement, critique & score UX"

This defaults to cloud mode: the new template is published to your hub account after the planning + writing stages finish. Sign in first if you haven't already:

/stagent:login

For a fully offline run (template stays on disk under ~/.config/stagent/workflows/<name>/, nothing pushed to the hub), switch to local mode:

/stagent:create --mode=local "plan, implement, critique & score UX"

Need inspiration? Browse the cookbook for twelve battle-tested workflow templates you can fork or remix.

The Default Workflow

With no --flow flag:

• Cloud mode (default) fetches cloud://demo from the hub — a hosted template that may evolve independently of this README
• Local mode uses the plugin-bundled workflow at skills/stagent/workflow/ (offline fallback) — the canonical source for the cycle described below

The bundled workflow runs a plan → execute → review → QA → deploy cycle:

1. Planning (interruptible, inline) — Q&A with you: clarifying questions, proposed approaches, plan file. You confirm before anything gets built.
2. Executing (subagent, opus) — implements the plan: tests-first when specified, minimal focused changes. On re-entry, also reads the previous iteration's reviewer / QA feedback as optional inputs.
3. Reviewing (subagent) — adversarial code review against the baseline git SHA captured at workflow start. PASS → QA; FAIL → loop back to Execute.
4. QA-ing (subagent) — runs real user-journey tests (Playwright, XcodeBuildMCP, etc.). Distinguishes test bugs from app bugs — only confirmed app bugs block progress. PASS → Deploy; FAIL → loop back to Execute.
5. Deploy (interruptible, inline) — Vercel CLI flow: vercel whoami, vercel link on first run, sync production env vars, vercel --prod, smoke-check the URL. Interruptible because first-run setup may need vercel login in another terminal or env-var values from you. Done → terminal complete.

The execute → review → QA loop runs autonomously after you approve the plan. A Stop hook guarantees the loop runs to completion (until QA passes; deploy then runs as the final, interruptible stage). The loop stops on one of: deploy completes (terminal complete), max_epoch is hit (default 20, configured in workflow.json → .max_epoch; breaks runaway iteration by forcing terminal escalated), or you intervene with /stagent:interrupt (pauses) or /stagent:cancel (terminal cancelled). All three — complete, escalated, cancelled — are declared in workflow.json → .terminal_stages.

Custom Workflows