Swe Workflow

---
name: swe-workflow
description: Orchestrates the full five-stage flow from raw idea to shipped PR — grill-with-docs → to-prd → to-issues → triage → worktree+planning-with-files. Each stage answers one question (What do I want? / What does done look like? / What are the units of work? / What's actionable? / Build it). Use when the user has an idea but no spec yet, wants to plan a feature end-to-end, says "let's PRD this," asks "how do I start on this idea?", or grabs a ready-for-agent issue to implement.
---

# SWE Workflow

The idiomatic software-engineer workflow: clarify the idea → spec it → slice it → triage it → ship it. Five stages, each with a dedicated skill and a durable artifact that feeds the next.

## The workflow

```
┌────────────────────── SPEC LAYER (mattpocock) ──────────────────────┐
│                                                                      │
│  0. How is this repo set up?                                         │
│     /setup-matt-pocock-skills ──► AGENTS.md, docs/agents/            │
│              (one-time: tracker, triage labels, doc layout —         │
│               wires this repo's conventions into the chain)          │
│                                                                      │
│  1. What do I want?                                                  │
│     /grill-with-docs ──► CONTEXT.md, ADRs                            │
│              (resolve domain language; capture decisions —           │
│               re-run until no questions remain or you abort)         │
│                                                                      │
│  2. What features does this break into?                              │
│     /to-features ──► FEATURES.md                                     │
│              (read CONTEXT.md + ADRs → user-facing features;         │
│               strike through, don't delete, on ship)                 │
│                                                                      │
│  3. What does done look like?                                        │
│     /to-prd ──► PRD (auto-labeled `ready-for-agent`)                 │
│              (Problem / Solution / User Stories /                    │
│               Implementation Decisions / Testing Decisions / Scope)  │
│                                                                      │
│  4. What are the units of work?                                      │
│     /to-issues ──► N tracer-bullet issues                            │
│              (vertical slices, all auto-labeled `ready-for-agent`    │
│               — /triage NOT in the critical path)                    │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

                                  │
                  (Agent grabs ONE `ready-for-agent` issue)
                                  │
                                  ▼
┌────────── EXECUTION LAYER (worktree + planning-with-files) ──────────┐
│                                                                      │
│  5. How do I plan each issue?                                        │
│     Fetch issue (per tracker) ──► worktree + branch + seed files     │
│              (task_plan.md, findings.md, progress.md from AC)        │
│                                                                      │
│     /planning-with-files:plan ──► interview → make the plan          │
│              (prompt bakes in /karpathy-guidelines + /tdd —          │
│               shapes phases, key questions, decisions to make)       │
│                                                                      │
│                    step 5 writes ▼                                   │
│                        ┌────────────────────┐                        │
│                        │    task_plan.md    │                        │
│                        └────────────────────┘                        │
│                     step 6 reads ▼                                   │
│                                                                      │
│  6. How do I build each issue?                                       │
│     /planning-with-files:plan-goal ──► read task_plan.md,            │
│              work each sub-task in order → commit                    │
│              (sub-tasks already name /tdd + /karpathy-guidelines)    │
│                                                                      │
│  7. How do I close out each issue?                                   │
│     progress.md highlights ──► PR body / closing comment             │
│              (the session log IS the PR narrative — don't rewrite)   │
│                                                                      │
│     Teardown ──► git worktree remove + branch -d if merged           │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘
```

*File-based end to end — each step hands the next a markdown artifact: `CONTEXT.md`/ADRs → `FEATURES.md` → PRD → issues → `task_plan.md` → `progress.md`. The files are the interface between steps; nothing lives only in the agent's head.*

## Parallel concern: `/triage`

`/triage` sits beside the chain, not inside it — a small state machine over the issue tracker (`needs-info` / `ready-for-agent` / `ready-for-human` / `wontfix`). Required for issues filed *outside* the chain (user bug reports, external contributions, ad-hoc feature requests); redundant for chain-created issues, since `/to-prd` and `/to-issues` auto-label `ready-for-agent` at creation.

See [REFERENCE.md](REFERENCE.md#parallel-concern-triage--whats-actionable-for-external-issues) for the full state machine and per-state outputs.

## Design philosophy

This is a **chain of small skills, not a framework.** Three principles guard against drifting into framework opacity:

1. **Own the process.** "Process" here means *deciding what goes into context at each stage*. Every skill in the chain is a markdown file you can read, edit, swap, or skip — there is no opaque orchestrator.
2. **Every artifact is observable.** PRDs, issues, AGENT-BRIEFs, `task_plan.md`, `findings.md`, `progress.md` — all human-readable markdown, all `cat`-able at any point.
3. **Ephemeral state is intentional.** Per-issue worktrees and planning files die when the PR ships. Deliberate defense against spec/plan drift accumulating into a "ball of mud" over time.

Operating maxim (Matt Pocock, after [surveying ~2000 AI coding course participants on framework dissatisfaction](https://x.com/mattpocockuk/status/2044029094942159126)): *"a good framework hands a lot of control over to the user and is easy to observe."* If a proposed addition reduces either, reject it — even if it's borrowed from a framework that looks useful.

**Concrete commitments** derived from these principles:

- **Instructions-only, no scripts.** Deterministic operations are documented as instructions the agent runs, not wrapped in scripts. Every script reintroduced would move the chain toward the opacity Matt's surveyed users rejected.
- **Transparent markdown all the way down.** Seven chain stages plus `/triage` as a parallel concern — every link is a markdown skill or documented procedure you can read, edit, or replace without touching code. None of them opaque. The direct test of the operating maxim above.

**Engineering-side, by design.** The mattpocock toolchain assumes features come from product thinking (user needs, business goals) that lives outside this skill ecosystem. Stage 2 (`/to-features`) is the deliberate seam: features get *enumerated* here (read from `CONTEXT.md` + ADRs), but *discovered* elsewhere — in user interviews, product strategy, sales conversations, whatever your team uses. This toolchain has no opinion on that.

See [REFERENCE.md](REFERENCE.md#how-this-differs-from-spec-kit-class-frameworks) for the comparison with spec-kit / BMAD / GSD.

## Where to enter the chain

Don't always start at stage 1 — jump to where the chain actually breaks.

| Entry signal | Start at |
|--------------|----------|
| Fresh repo, no `## Agent skills` block or `docs/agents/` yet | 0 |
| Vocabulary fights, fuzzy terms, no glossary yet | 1 |
| Domain understood, features not yet enumerated | 2 |
| Feature picked, no PRD yet for this one | 3 |
| PRD exists but is one mega-issue | 4 |
| Picked a `ready-for-agent` issue, ready to plan | 5 |
| `task_plan.md` refined, ready to implement | 6 |
| Implementation committed, ready to open the PR + tear down | 7 |
| External issue filed by a user, needs classification | (parallel: `/triage`) |

## When is it done?

The mirror image of "Where to enter the chain" — four levels of "done", four signals:

| Level | Done when | Recorded in |
|-------|-----------|-------------|
| Phase | TDD cycle green + logged | `task_plan.md` checkbox ticked |
| Issue | All phases ticked, PR merged | tracker status (closed/merged) |
| Feature | All issues from its PRD merged | `FEATURES.md` strike-through w/ shipped refs |
| Project | (no native concept — judgment call) | — |

A feature's completion is mechanical: walk from the PRD to its child issues (via the parent reference `/to-issues` writes), confirm all closed, then strike through the `FEATURES.md` line:

```
- [x] ~~user-can-reset-password~~ — ~~A user can reset...~~ (shipped: #42, #43, #44)
```

Software projects rarely "complete" — features keep getting added. If you need a hard milestone, layer on your tracker's mechanism (`gh milestone`, Linear cycles, release tags) and define "project complete" as that milestone closing. See [REFERENCE.md](REFERENCE.md#completion-signals) for per-tracker completion queries.

## Stages 5-7: worktree + planning-with-files

The skill is **instructions-only** — there are no scripts. The agent performs each step manually, adapting to the team's issue tracker.

### Bootstrap

1. **Pick the tracker.** See [Tracker selection](#tracker-selection) below.
2. **Fetch the issue** per [`trackers/<name>.md`](trackers/) — extract title, body, labels, AGENT-BRIEF.
3. **Derive paths**:
   - slug = title → lowercase → non-alphanumerics replaced with `-` → truncate to 40 chars
   - branch = `issue-<id>-<slug>` (Linear's `TEAM-123` passes through literally)
   - worktree = `../<repo>-issue-<id>/`
4. **Create the worktree**: `git worktree add ../<repo>-issue-<id> -b issue-<id>-<slug>`
5. **`cd` in and seed** three planning files:

   | File | Contents |
   |---|---|
   | `task_plan.md` | Goal = title; Phases = AC checkboxes. **Structured fields only** (hook re-injection risk). |
   | `findings.md` | Raw issue body + AGENT-BRIEF pasted verbatim. Safe sink for external content. |
   | `progress.md` | Initial session log entry with bootstrap timestamp. |

6. **Invoke `/planning-with-files:plan`** (Stage 5) with this prompt:

   > /planning-with-files:plan Interview me about this issue, then write task_plan.md to implement it. The plan must use /tdd (tests first: red → green → refactor) for writing code and tests, and apply /karpathy-guidelines (surgical, simple changes) for code quality — and it must name both skills explicitly in task_plan.md so they're used when the plan is executed.

   The interview refines the seeds — sharpens phases, surfaces key questions, captures decisions to make. `task_plan.md` is the **core artifact** Stage 6 reads; `findings.md` holds the raw issue body. The prompt's last clause is load-bearing: telling the planner to **name `/tdd` and `/karpathy-guidelines` inside `task_plan.md`** is what carries the methodology into Stage 6 — `plan-goal` re-reads the plan, sees the skills called out per phase, and applies them instead of being re-told.
7. **Invoke `/planning-with-files:plan-goal`** to execute (Stage 6) — reads `task_plan.md`, drives each phase as a goal via Claude Code's goal command; outer loop runs phases; `/tdd` is the inner loop for code-producing phases. Since the Stage 5 prompt already named `/tdd` and `/andrej-karpathy-skills:karpathy-guidelines`, the plan calls for them — `plan-goal` carries them out: test-first, surgical changes, simplicity first, no speculative abstractions, surfaced assumptions.
8. **Close out** (Stage 7) — open the PR with the body drawn from `progress.md` highlights (the session log *is* the narrative; don't rewrite it). After it merges, [tear down](#teardown-after-pr-merges) the worktree and branch.

### Tracker selection

Priority order:

1. **`$SWE_WORKFLOW_TRACKER`** env var (explicit override)
2. **`tracker=<name>`** line in `.swe-workflow.conf` at the repo root
3. **Auto-detect** from project signals:
   - `.scratch/` directory → `local-markdown` (mattpocock's `.scratch/<feature>/` convention)
   - github remote + `gh` installed → `github`
   - gitlab remote + `glab` installed → `gitlab`
   - `.linear/` directory → `linear`
   - `$MULTICA_WORKSPACE_ID` set → `multica` (no project-level signal — Multica config is user-level)
4. Still ambiguous → ask the user.

Per-tracker fetch commands and conventions: [`trackers/<name>.md`](trackers/). To add a new tracker, write a new doc following the same shape — nothing else changes.

### Inner loop: `/tdd` for code-producing phases

`/planning-with-files:plan-goal` is the **outer loop** (phases, state, errors); `/tdd` is the **inner loop** (one failing test → one minimal fix). For each phase in `task_plan.md` that produces testable code:

```
Mark phase in_progress  →  /tdd (red → green → refactor)  →  log to progress.md  →  Mark phase complete
```

Not every phase needs `/tdd` — exploration, config tweaks, and infra changes skip it. See [REFERENCE.md](REFERENCE.md#inner-loop-tdd-within-each-code-producing-phase) for the full nuances (multiple cycles per phase, decision/error capture, when `/tdd`'s own planning step duplicates vs. complements the issue-level plan).

### Teardown (after PR merges)

From the **main checkout** (NOT inside the worktree):

```bash
# Verify no uncommitted changes
git -C ../<repo>-issue-<id> status --porcelain

# Remove worktree
git worktree remove ../<repo>-issue-<id>

# Delete branch only if merged into the default branch
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git branch --merged "$default_branch" \
  | grep -qE "^[[:space:]]*\*?[[:space:]]*issue-<id>-<slug>$" \
  && git branch -d "issue-<id>-<slug>"
```

## Critical handoff rules

1. **PRD uses the glossary from stage 1.** If `to-prd` introduces terms that conflict with `CONTEXT.md`, loop back to `/grill-with-docs`.
2. **Issues are tracer bullets, not horizontal layers.** Each is a thin vertical slice (schema → API → UI → tests). "Backend issue" + "frontend issue" is a smell — re-slice.
3. **Only `ready-for-agent` issues enter execution.** `/to-issues` auto-applies the label on chain-created issues; `/triage` applies it to external issues (user reports, etc.). Either way, stage 5 reads from the label, not the source.
4. **One issue = one worktree = one `task_plan.md`.** Filesystem isolation for parallel AFK agents. No exceptions.
5. **Strike through, don't delete.** When a feature ships, strike it through in `FEATURES.md` with a shipped reference — never delete. Preserves institutional memory; prevents quiet scope drift.

## Don't double-track

| Lives in… | Don't also put in… |
|-----------|--------------------|
| PRD (immutable arch decisions) | `task_plan.md` (would rot; the spec is authoritative) |
| AGENT-BRIEF (durable contract) | `task_plan.md` (copy only AC + key interfaces; raw brief goes in `findings.md`) |
| `task_plan.md` (execution-time decisions, errors hit) | The issue (don't litter the spec with build noise) |
| `progress.md` (session log) | A hand-written PR summary (the log IS the summary) |

## Security boundary

`planning-with-files` re-injects `task_plan.md` into context on every tool call. Any text in `task_plan.md` is an amplified prompt-injection target.

- Raw issue bodies, fetched docs, web content → `findings.md` only.
- `task_plan.md` gets only **structured fields** the executor wrote (Goal, Phases from AC, Decisions, Errors).

The bootstrap procedure ([Stages 5-7](#stages-5-7-worktree--planning-with-files)) enforces this split.

## When to skip this skill

- Single-file edits (no spec, no plan needed)
- Bug fixes where the AGENT-BRIEF is one paragraph — just do it, skip stage 5 bootstrap
- Exploration / prototypes — use the `prototype` skill instead

## Further reading

- [REFERENCE.md](REFERENCE.md) — per-stage detail, HITL vs AFK execution, gotchas
- Source skills: `grill-with-docs`, `to-prd`, `to-issues`, `triage` (mattpocock/skills), `planning-with-files` (OthmanAdi/planning-with-files)