⚡ Blitz — Background Work Runner

A Claude Code skill for people on Claude Max plans. Queue tasks, declare long-term goals, and enable per-project audits. Blitz fires on a configurable cadence with a per-project idle gate, runs work through parallel agents, and writes every agent's output to disk so you wake up to actual artifacts, not a closed terminal.

Parallelism is for throughput, not quota multiplication. Five agents finish five tasks in the time of one — that's the win.

Step 0 — Route by Subcommand

Read the first word of arguments after /blitz:

Config path: ~/.claude/blitz.json (Windows: C:\Users\<user>\.claude\blitz.json) Output path: ~/blitz/runs/<timestamp>/ (Windows: C:\Users\<user>\blitz\runs\<timestamp>\)

If ~/.claude/blitz.json doesn't exist on any subcommand other than setup, create a minimal default with empty backlog: [] so reads don't fail. Don't force setup on first run.

M-ADD — Add a Task to the Backlog

Syntax: /blitz add <task description> (optional flag: --project <path>)

1. Parse the task description (everything after add minus any flags).
2. Determine project path:
   • If --project <path> provided, use it.
   • Otherwise, use the current Claude Code working directory.
3. Append to backlog[] in config:

   { "id": <next>, "task": "<description>", "project": "<absolute path>", "added": "YYYY-MM-DD" }
   

4. Confirm:

   ✅ Added #[id] to backlog
      Task:    <description>
      Project: <project path>
      Backlog now has [N] item(s).
   

If the task description is empty, ask the user what they want to add.

M-LIST — Show the Backlog

Display every backlog item with its id, task, project (shortened), and date added. Group by project if there are multiple. Show total count at top.

⚡ Blitz backlog — [N] items

  #1  Refactor auth.js for clarity              [myapp]    added 2026-04-29
  #2  Generate tests for billing module         [myapp]    added 2026-04-30
  #3  Write API docs for /v2 endpoints          [api-svc]  added 2026-05-01

Run /blitz to blitz through them.

If empty: Backlog is empty. Add something with /blitz add <task>.

M-REMOVE — Remove an Item

Syntax: /blitz remove <id> (or rm).

Remove the item with that id from backlog[]. Confirm:

✅ Removed #[id]: <task>. Backlog now has [N] item(s).

If the id doesn't exist, list the current backlog and ask which to remove.

M-CLEAR — Clear Everything

Confirm first: Clear all [N] backlog items? (yes/no). Only proceed on explicit "yes". Then empty backlog: [] and confirm.

M-GOAL — Goal Lifecycle

Long-term goals are user-defined objectives that compound over many fires. Each goal has a durable plan (~/blitz/goals/<id>/plan.md) and a long-lived branch (blitz/goal-<id>). Goal items live in backlog[] with kind: "goal".

M-GOAL-ADD — Add a goal

Syntax: /blitz goal add <description> (optional flag: --project <path>)

1. Parse the description.
2. Determine project path: --project flag, else current cwd.
3. Append to backlog[]:

{
  "id": <next>,
  "kind": "goal",
  "task": "<description>",
  "project": "<absolute path>",
  "added": "YYYY-MM-DD",
  "branch": "blitz/goal-<id>",
  "autoPush": false,
  "lastTouched": null,
  "incrementCount": 0
}

4. Confirm:

✅ Added goal #[id] to backlog
   Goal:    <description>
   Project: <project path>
   Branch:  blitz/goal-<id> (will be created on first increment fire)
   Plan:    ~/blitz/goals/<id>/plan.md (will be written on first fire)

The plan is not written at queue time. The first fire on this goal writes it.

M-GOAL-LIST — Show goals

Display every kind: "goal" item with id, description, project, branch, increment count, and last-touched date. If none, print: No goals. Add one with /blitz goal add <description>.

M-GOAL-REVIEW — Review a goal's branch

Syntax: /blitz goal review <id>

1. Look up the goal item; load branch field.
2. In the goal's project directory, run:

git log <branch> ^main --oneline
git diff main..<branch> --stat

3. Print plan.md status: count of [x], [ ], and [~] items.
4. End with a hint: Merge with: git checkout main && git merge <branch>.

If the branch doesn't exist, print: No commits yet on this goal.

M-GOAL-LOG — Show increment history

Syntax: /blitz goal log <id>

Read every result file in ~/blitz/runs/*/goal-<id>-*.md (sorted by timestamp), print the top-level heading and the first paragraph of each.

M-GOAL-REMOVE — Remove a goal

Syntax: /blitz goal remove <id>

Remove the item from backlog[]. Do not delete the branch or plan.md. Print:

✅ Removed goal #[id]: <description>
   The branch blitz/goal-<id> and plan.md were left in place.
   Clean up manually: git branch -D blitz/goal-<id> && rm -rf ~/blitz/goals/<id>

M-GOAL-AUTOPUSH — Toggle autopush

Syntax: /blitz goal autopush <id> on|off

Set autoPush on the goal item. When true, increment fires also git push origin <branch> after committing. Default is off.

Confirm:

✅ Goal #[id] autopush: <on|off>

Goal Fire Flow

When the auto-fire pulls a kind: "goal" item, route to one of two flows based on plan.md state.

Planning fire (no plan, or empty plan)

This is the first fire for a goal. No code is written. The agent only produces a plan.

1. Spawn one general-purpose agent with this prompt template:

Working directory: <goal.project>

You are the planning agent for a long-term goal. Your sole job is to write
a plan.md file. You will NOT write any code.

Goal: <goal.task>

Read the project state (git log -30, top-level file tree, README.md if it
exists, package.json or equivalent) and produce a numbered Markdown
checklist of small, mergeable, demoable increments toward the goal.

Each increment must:
- Be self-contained (no item depends on incomplete prior items)
- Be mergeable on its own (could ship as a single PR)
- Be small enough that one focused agent could finish it in one fire
- Have a clear "done" criterion

Write the checklist to: ~/blitz/goals/<goal.id>/plan.md

Format:
  # Plan: <goal.task>
  Project: <goal.project>
  Created: <date>

  ## Increments
  - [ ] 1. <one-line summary>: <2-3 sentence detail>
  - [ ] 2. ...

Also write a result file to <output_dir>/goal-<goal.id>-plan.md containing
the plan and a short paragraph explaining your reasoning (why these
increments, in this order).

Do NOT make any commits. Do NOT modify any project files.

2. After the agent finishes, update the goal item: lastTouched = now, incrementCount stays at 0.
3. The goal will hit the increment-fire flow on its next fire.

Increment fire (plan.md exists with at least one unchecked item)

1. Read ~/blitz/goals/<goal.id>/plan.md. If every item is [x], the goal is done — set a marker comment in plan.md (> Goal complete: YYYY-MM-DD), update the goal item with lastTouched = now, and exit. Skip auto-promoting a "review and merge" task since the user knows from /blitz goal list.
2. Pick the lowest-numbered unchecked item.
3. Spawn one general-purpose agent with th