swe-workflow

The idiomatic software-engineering workflow: Idea → PRDs → Issues → ship. A chain of small, observable steps connected by markdown files — not an opaque framework.

It ships as Agent Skills, so it runs on Claude Code, Codex, Gemini CLI, Cursor, and any other skills-compatible agent. Pure markdown — no scripts, no build.

Install

Claude Code

Installs the plugin — the swe-workflow skill plus the /swe-workflow:* slash commands.

/plugin marketplace add OpenSWE/swe-workflow
/plugin install swe-workflow@swe-workflow

(swe-workflow@swe-workflow is plugin@marketplace — both happen to be named swe-workflow.)

Other agents (universal)

Installs the swe-workflow skill.

npx skills add OpenSWE/swe-workflow

Invoking

• Claude Code — the slash commands /swe-workflow:setup (0), :spec (1–4), :to-features (2), :grill-feature (3), :ship (5–7), :ship-all (5–7 ×N), :status (thin shims over the skill), or invoke the swe-workflow skill to drive the whole chain (0–7).
• Codex · Gemini CLI · Cursor · others — invoke the swe-workflow skill and say what you want ("ship issue #42"); it routes to the right stage. Most hosts also surface it as a slash command or trigger it from its description.

Prerequisites

The workflow orchestrates several skills this suite doesn't bundle. The setup stage (/swe-workflow:setup) auto-installs the missing ones (then restart to activate them); or install manually:

• log-decisions — the append-only DECISIONS.md decision journal every stage records into (the suite's own, in its own repo). Cross-agent.
• planning-with-files — the plan / plan-goal / status engine the ship stage runs for each issue. Cross-agent.
• mattpocock/skills — tdd (the red → green → refactor inner loop) plus the upstream spec layer: setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, and triage. Cross-agent.

How it fits together

flowchart TD
    IDEA([IDEA])
    S0["/setup (0)<br/>bootstrap repo — prereq skills · always-on rules"]

    subgraph SPEC["SPEC LAYER · /spec (stages 1–4, AFK-friendly)"]
        direction TB
        S1["grill the domain (1) → CONTEXT.md + ADRs"]
        S2["enumerate features (2) → FEATURES.md"]
        S3["spec one feature (3) → a PRD (one per feature)"]
        S4["slice into issues (4) → ready-for-agent issues"]
        S1 --> S2 --> S3 --> S4
    end

    subgraph EXEC["EXECUTION LAYER · /ship (one issue) · /ship-all (backlog, AFK)"]
        direction TB
        S5["plan (5) → task_plan.md (+ findings.md)"]
        S6["build (6) → progress.md (test-first)"]
        S7["close-out (7) → PR + worktree teardown"]
        S5 --> S6 --> S7
    end

    SHIPPED([SHIPPED])
    TRIAGE["triage runs alongside — sorts externally-filed<br/>issues into the ready-for-agent backlog"]

    IDEA --> S0
    S0 --> S1
    S4 --> S5
    S7 --> SHIPPED
    TRIAGE -.-> S5

Loading

Those right-hand artifacts are the interface between stages — the files, not the agent's memory, carry state from stage to stage. The swe-workflow skill's stage table (skills/swe-workflow/SKILL.md) is the canonical map, with each stage's full procedure in references/; the design rationale lives in docs/DESIGN.md.

A typical run

Spelled out for a fresh project — three commands, and what each leaves behind:

1. /swe-workflow:setup (stage 0) — run once at the repo root; bootstraps the repo and auto-installs the external skills the later stages need.
2. /swe-workflow:spec (stages 1–4) — the spec layer, AFK-friendly: grill the domain → coarse features → a PRD per feature → tracer-bullet issues. Leaves CONTEXT.md + ADRs, FEATURES.md, PRDs, and a backlog of ready-for-agent issues.
3. /swe-workflow:ship-all (stages 5–7) — build and ship the whole backlog, AFK.

Prefer to drive the spec layer stage by stage? Every stage's procedure and command is listed in the skill's stage table (skills/swe-workflow/SKILL.md).

License

MIT