/run

Durable execution for coding agents. Bind a workstream, keep state in Markdown, verify before done, and resume from a bounded Handoff — not from yesterday's chat.

Skills follow the Agent Skills format and install via skills.sh.

What it is

/run is an engineering process assistant — a skill protocol for Cursor, Claude Code, and Codex.

It turns multi-step work into a recoverable loop:

bind workstream → explore / plan / execute → verify → hand off → continue

Durable state lives in a Markdown workspace (Obsidian optional). Each git repo keeps a small .run-state index for session binding. No control plane. No SaaS.

Why it exists

Coding agents are good at writing code. They are weak at:

• Continuity — losing the thread between chats, tools, and weekends
• Accountability — marking work done without evidence
• Scope control — drifting off-plan or skipping task accounting

Frameworks that own the whole process (GSD, BMAD, Spec-Kit, issue-tracker agents) can help — but they also take away control and make process bugs hard to fix.

/run keeps you in charge: plain files, explicit phases, hard stops where it matters.

Key features

• Three-layer model — project → workstream → tasks (tasks.md rows)
• Session sticky — bound repos must stay on /run; no silent ad-hoc coding
• Single writer — only parent /run updates workspace state; subagents may edit code (prefer worktrees)
• Verification gate — doing → done requires evidence in the execution log
• Integration gate — all tasks done ≠ workstream closed; human smoke + worktree disposition required
• Handoff block — resume from ## Handoff in context.md, not chat archaeology
• /run auto — unattended advance with dual-agent design gates and real hard stops
• /run review — protocol retro over workspace artifacts; bundled up skill patches the protocol

Quick start

1. Install

npx skills add kl7sn/run -g

Installs run + up. Common flags:

npx skills add kl7sn/run -g -y              # non-interactive
npx skills add kl7sn/run -g -a cursor       # Cursor only
npx skills add kl7sn/run --list             # preview packaged skills
npx skills update                           # refresh later

Contributors with a clone: ./install.sh all (symlink into agent dirs).

2. Create a workstream

In your project repo:

/run init demo          # project container (once)
/run new hello          # nested workstream under the project

Or point RUN_WORKSPACE / .run-state at an existing workspace folder.

3. Run

/run                    # advance explore → plan → execute
/run auto               # unattended (hard stops still apply)
/run review             # retro current project + maintain skills via up

Status line on every advancing reply:

[/run · lang=en · auto=off · 01-demo/01.01-hello · T01 ready]

Packaged skills

Skill	Role
run	Process protocol — bind, phases, tasks, Handoff, gates
up	Skill maintenance — phase 2 of /run review (default apply)

/run is not a general skill toolkit. Other skills (TDD, grilling, domain tools) stay separate and optional.

Commands

Command	Description
/run init [projectId]	Create project container
/run new [workstreamId]	Create nested workstream
/run bind	Rebind this session interactively
/run lang [en|zh]	Show or set document language
/run	Advance current phase
/run auto	Unattended advance
/run review [scope]	Protocol retro (default: current project) + up
/run review scan-only	Report only; skip skill patches

Workspace

Resolution order: .run-state → RUN_WORKSPACE → ~/run-workspace.

<workspace>/
└── Projects/
    └── 01-demo/                    # project  NN-<slug>
        ├── project.md
        └── 01.01-hello/            # workstream  NN.MM-<slug>
            ├── workstream.md
            ├── tasks.md
            ├── context.md          # Handoff · Gotchas · evidence
            └── spec.md             # optional

Review reports: Projects/<projectId>/_run-review/YYYY-MM-DD-review.md

Sample: examples/01-demo/ · Templates: templates/ (*.zh.md for Chinese)

Repo session index (.run-state at git root):

workspace: ~/run-workspace/Projects/01-demo/01.01-hello
lang: en
project: 01.01-hello
repo: .

Supported agents

Agent	Install target
Cursor	~/.cursor/skills/
Claude Code	~/.claude/skills/
Codex	~/.codex/skills/

Use npx skills add kl7sn/run -g -a <agent> to pick one. The install.sh helper also covers ~/.agents/skills/.

What /run is not

❌ Hosted agent platform	✅ Markdown workspace + skill protocol
❌ Issue tracker you must live in	✅ tasks.md rows you can grep
❌ General skill hub / registry	✅ Process assistant + bundled up only
❌ "Looks good" completion	✅ Verification + human smoke before close

Optional companions

/run orchestrates; phase discipline skills are optional:

• Defaults: superpowers (brainstorming, writing-plans, TDD, verification-before-completion)
• Cherry-picks: mattpocock/skills — e.g. grill-with-docs, to-tickets, code-review
• Do not dual-run their handoff / implement or move durable state out of the workspace

See skills/run/SKILL.md → Relationship to other skills.

Documentation

Document	Purpose
skills/run/SKILL.md	Full agent protocol
skills/up/SKILL.md	Skill maintenance skill
docs/design.md	Design notes and tradeoffs
README_CN.md	中文说明

License

MIT