werkflow

Durable agent workflow runtime: workflows are TypeScript functions built on a small SDK; one daemon per repo's .werkflow directory (enforced at werkflow start) executes them across restarts without redoing agent work; trackers, sandboxes, and harnesses are pluggable providers; runs start from ticket state, a cron schedule (on.cron), or the CLI. Human-in-the- loop first: every run is watchable and steerable in herdr, and the evidence a run produces (artifacts, collected agent outputs, bundles) outlives its workspace for every human decision, and gate() pauses a run on the ticket until a person decides - by CLI, by moving the ticket, or by commenting - and an interactive step hands a pane to a person who works with the agent and ends the step with werkflow finish. Agents are named and run-scoped (agent("implementer").prompt(...)): one pane, one session, prompts in order, so a fix round continues where the implementation left off instead of re-reading the branch - a cache, never a channel; results travel through artifacts and step results, and every prompt must be correct fresh. Every run leaves a trace (trace.jsonl: durations, attempts, errors, agent tokens and cost) next to its journal, summarized by werkflow trace <run-id>. Scheduling is dependency-aware: a ticket waits for its prerequisites, and once a prerequisite has an open PR the dependent starts stacked on it - branch and PR alike - via GitHub's native stacked PRs.

Install

npm install werkflow   # or pnpm add / bun add
npx werkflow doctor    # check git, wt, srt, herdr, Linear creds; warn on unsandboxed workflows

Node >= 20, macOS or Linux. Type declarations are included.

Documentation

Start with the user guide: install/configure, define and run workflows, primitives, providers, runtime behavior, instrumentation, CLI, and testing.

Command overview: werkflow start (daemon), run, runs [show], trace, artifact, bundle, gate, attach, finish, resume, cancel, clean, doctor, version - see the guide's CLI section.

Direction and design:

• docs/vision.md - why workflows-as-code, the three concepts
• docs/sdk-spec.md - SDK surface and runtime semantics
• CONTEXT.md - domain glossary
• docs/adr/ - decision records

Develop

Bun is the dev/test toolchain; pnpm manages packages. src/ must stay Node-compatible (no Bun.*, no bun:* imports); pnpm build produces the Node-targeted bundle that ships.

pnpm install
pnpm test
pnpm typecheck && pnpm lint && pnpm fmt:check
pnpm build && pnpm test:dist

The repo's own workflow

.werkflow/workflows/develop.ts drives this repository's tickets: plan -> human gate on the plan -> implement -> verify + review (bounded fix loop) -> PR -> human merge gate. Four named agents (planner, implementer, reviewer, writer); fix rounds continue the implementer's session and review rounds the reviewer's. The review and the PR text run on codex, not on the implementer's model, so no agent grades its own work. Beyond werkflow doctor, it expects on PATH:

• codex - reviewer (gpt-5.6-sol) and PR writer (gpt-5.6-luna), see .werkflow/harnesses.ts
• gh with the gh-image extension - opens the PR and uploads screenshots/recordings from .werkflow/out/ as attachments (upload failure only drops the evidence section) - and the gh-stack extension for stacked runs (GitHub stacked PRs, public preview; if the repo has them disabled the PR falls back to a plain one against the default branch)

Branch, title, and body carry no tracker ids. The remote branch is <original-ticket>/<slug> when the ticket description says Original Ticket: XA-1234, else <type>/<slug>; the local worktree keeps werkflow/<ticket>.

Releasing

Manual version bump; CI publishes on tags. Bump version in package.json, commit, tag v<version>, git push --tags. The release workflow runs checks, builds, smoke-tests the built artifact, and publishes to npm via trusted publishing - dist-tag next for prereleases, latest otherwise.

Trusted publishing can only be configured for a package that already exists on npm, so the very first version is published manually (npm publish); after that, configure the GitHub Actions publisher on npmjs and tags take over. Provenance additionally requires this repository to be public.

License

MIT