workflow-skills

A Claude Code plugin bundling Daniel's general engineering workflow skills: collaborative PR review, durable multi-step planning, auditable quantitative analysis pipelines with independent fact-checking, and a repo-native task loop for capturing and processing follow-up work.

Install

/plugin marketplace add bestdan/workflow-skills
/plugin install workflow-skills@workflow-skills

What's in the box

17 skills, 21 commands, and 2 subagents, organized into eight workflows. Each entry links to its own doc — that's where the flags, edge cases, and handler support live.

PR review

Skill	Trigger	What it does
co-review	/co-review [PR# | --local | --remote | --post] [--base <branch>]	Review a PR yourself, pull in other local agents (codex, agy, devin, copilot, crush, grok) as extra reviewers, reconcile everything against existing GitHub comments, auto-fix the high-confidence items, and surface the judgment calls.
local-review	"let me look over these changes", "open the diff so I can comment"	Open a GitHub-style split-diff UI on localhost so you read an agent's changes and leave inline line comments; the feedback is written to a file the agent acts on. Local-only — nothing touches GitHub unless you flag a comment for it.

Run local-review by hand (no agent needed): the server is a plain script — alias it once and review any patch:

# ~/.zshrc — a function, not an alias: the cache keeps one directory per
# installed plugin version, so pick the newest deterministically instead of
# letting a glob expand to several paths.
local-review() {
  python3 "$(ls -d "$HOME"/.claude/plugins/cache/workflow-skills/workflow-skills/*/scripts/local-review/server.py | sort -V | tail -1)" "$@"
}

cd my-worktree
local-review --git main       # committed diff of my-branch vs main
local-review --git uncommitted  # live diff of uncommitted worktree edits

Open the printed Review UI: URL. --git uncommitted re-reads the worktree live, so further edits show up via the Refresh button; --git <ref> and --git <A>...<B> diff commit-to-commit, so Refresh only picks up new content when the refs themselves move (a new commit, a rebase), not a worktree edit. For a patch file instead, pass --diff-file PATCH --title "<label>" (a static snapshot; --title names the change in the header, otherwise the patch path is shown).

Approve the reviewer commands once. co-review hands each local reviewer a fixed input file on stdin (or via --prompt-file for devin), so the command string never changes and you can approve each reviewer with an exact-match, read-only rule instead of a broad wildcard. The skill's Permissions section has the exact JSON — merge it into permissions.allow in ~/.claude/settings.json or the repo's .claude/settings.json.

Planning

Skill	Trigger	What it does
plan-with-docs	/plan-with-docs, or after approving a plan in plan mode	Write a multi-step plan as one markdown file per PR-sized task under dev_docs/tasks/<name>_plan/, then refine it through clarifying questions.
research-spike	filing/answering a question, registering an obligation, promoting a decision, checking convergence	Run a research spike through an obligation ledger, so a converging question count can't hide a climbing count of deferred work.

Task loop

Capture follow-up work with full context during development, then process it automatically. The task skill auto-triggers on deferred-work language and carries the file format, capture workflow, and handler abstraction; the commands below do the work.

Where tasks land is configured per repo — repo-pr (markdown PR, default), gh-issue, jira, or linear. Handler support is jagged, and commands/task-config.md holds the authoritative capability matrix.

Command	Trigger	What it does
/add-task	/add-task [description]	Capture follow-up work and deliver it via the configured handler.
/do-tasks	/do-tasks [slug | --all | -n N] [--remote|--local]	The single execute verb — turn dependency-ready tasks into PRs, one in-session or N dispatched, bounded by wip_limit.
/list-tasks	/list-tasks [status]	Table of all tasks with status, priority, size, blockers, tags, and expiry.
/promote-tasks	/promote-tasks [dry-run | apply]	Score new tasks against the confidence check and promote them to ready or needs_refinement.
/push-plan	/push-plan <name> [--ready-only]	Push a vetted local plan to the tracker in dependency order, recording ids back so re-runs don't duplicate.
/reoptimize-tasks	/reoptimize-tasks [project | initiative | team] [name]	The inverse of /push-plan — reconcile prose dependencies against native relations and fix cycles, stale links, and overlap.
/task-config	/task-config [handler]	Choose the handler and verify its prerequisites (writes dev_docs/tasks/.task-config.yml).
/complete-task	/complete-task <identifier> [--dry-run]	Transition one identified work item to its tracker's completed state. All four handlers.
/archive-tasks	/archive-tasks [--older-than <N>d] [--issues <refs>] [--all] [dry-run]	Retire terminal-state work past an age threshold. A sweep refuses to mutate without a threshold.
/sweep-for-complete	/sweep-for-complete [--apply] [--all] [--project <id|name>]	Find started-state issues whose linked PR merged and complete exactly those. linear-only (v1).
/reconcile-tasks	/reconcile-tasks [--apply] [--all] [--project <id|name>]	Fix issues sitting in the wrong state, against a fixed rule table. linear and gh-issue, each with its own table.
/find-false-closures	/find-false-closures [--apply] [--project <uuid>] [--repo <owner/name>]	Detect completed issues no merged PR owns (the bare-id over-close bug) and restore them. linear-only.
/sweep-for-archive	/sweep-for-archive [--since 24h] [--apply] [...]	Close-out sweep: verify the window's closures, complete what merged, archive exactly what was proved delivered. linear-only.
/doctor	/doctor [--fix]	Diagnose the setup — config, prerequisites, legacy dirs, schema drift, co-review allow-rules — as PASS/WARN/FAIL.
break-down-task	a task is too big for one PR, or "split / slice / break down this task"	Find the natural shear points in an over-sized task and replace it with PR-sized components chained by is_blocked_by.

/sweep-for-complete, /reconcile-tasks, /find-false-closures, and /sweep-for-archive are dry-run-by-default and safe to schedule via /loop or /schedule.

Coder orchestration

Skill	Trigger	What it does
orchestrate-coders	/orchestrate-coders <task> [--coder <backend>[:<model>]]... [-n N]	Turn the session into an orchestrator that writes no feature code: decompose into PR-sized packets, dispatch each to a coder backend in an isolated worktree, verify every diff, integrate.
select-coder	/select-coder <task> [--refresh] [-n N], or "which model should implement this"	Probe which backends are actually available, profile the task, and return N ranked <backend>:<model> specs with rationale.
assess-task	/assess-task <task>, or "how hard / mechanical is this task"	Profile what a task demands — complexity, creativity, scope, autonomy, cost sensitivity, verification criticality. Never picks a model.
/refresh-coder-comparison	/refresh-coder-comparison [backend | model], or a stale matrix cache date	Re-research the capability matrix — benchmarks, pricing, model rosters, vendor terms — and write it back into select-coder/matrix.md.

Autonomous execution

Skill	Trigger	What it does
deliver-task	/deliver-task <slug | id> [--base <branch>] [--questions <path>]	One task, all the way: claim → implement via a routed worker in an isolated worktree → verify → PR → non-interactive co-review → hand off at needs_review, never done.
auto-pilot	/auto-pilot <linear-project | plan-dir> (in progress)	Advance a whole task graph unattended — a thin orchestrator walking the graph via /deliver-task, with crash-resumable state. See the design notes.

Auditable analysis

Skill	Trigger	What it does
analysis-pipeline	/analysis-pipeline, or auto when building report-producing analyses	Structure quantitative work as model → template → fill pipelines, with input provenance and reproducible output. Ships a working example/.
review-facts	/review-facts	Spawn the fact-reviewer subagent to verify links, cited values, reproducibility, number-trace, descriptors, units, formulas, and the recommendation.
analysis-conventions	auto when writing notebooks or analysis scripts	Conventions for analysis code: marimo vs plain scripts, uv run, scratchpad patterns, notebook structure. Not user-invocable.

Understanding the work

Skill	Trigger	What it does
tutor	/tutor [--pr <N> | --diff [<ref>] | <path>], or "quiz me on this"	Teach you the work until you can defend it: elicit first, close the gap, verify with a counterfactual quiz. An item is checked off only once you've demonstrated it.
research-spike-tutorial	"walk me through how the research-spike obligation ledger works"	A hands-on tutorial against a disposable tree under a temp dir — hit the "destination must already exist" wall for real, then watch the divergence.

Worktree lifecycle

The plugin registers four hooks. Three of them create and tear down an isolated worktree without anything being typed: WorktreeCreate puts it where scripts/worktree-config.sh says worktrees live (not inside the repo, which aborts in a repo that versions its own agent config), WorktreeRemove tears down only what the exiting session itself created, and a PostToolUse reminder on ExitWorktree says teardown ends there. Teardown covers the paths the harness dispatches: an explicit ExitWorktree and the interactive exit dialog. An unattended (claude -p) exit fires SessionEnd and nothing else, and subagent worktrees are never handed to the hook, so both still need a manual run of the same scripts — they are plain scripts you can run by hand either way: scripts/worktree-remove.sh <path> and scripts/branch-remove.sh <branch>.

The fourth, a PreToolUse guard (scripts/guard-foreign-worktree.py), refuses a write into a worktree of the same repo that the session never entered — git -C <path> commit, cd <path> && …, a redirect, or a heredoc naming the path — and points at EnterWorktree instead. Reads are allowed. It also warns once when write-work starts in a main checkout on its default branch. Bypass one Bash call with env WORKFLOW_SKILLS_ALLOW_FOREIGN_WRITE=1 <command>.

Skill	Trigger	What it does
worktree-teardown	auto, when a removal fails, refuses, or half-completes	The mechanics behind the teardown scripts: the submodule force gates, the PR-evidence branch delete, and the half-deleted and locked recovery cases. Not user-invocable.

Bundled subagents

• fact-reviewer — read-only auditor used by /review-facts. Fresh context, Read/Glob/Grep/Bash/WebFetch. Reports findings; never edits the analysis.
• co-review-reconciler — judges review findings for /co-review. Read/Glob/Grep/Bash, no Edit/Write: it returns a verdict, never the fix it just graded.

Also included

• Overnight auto-resume (car) — an external launcher you run instead of claude that survives the 5-hour usage cap: it detects a cap-kill, sleeps until reset, and resumes the same conversation.

Why auditable analysis matters

When you ask Claude to analyze something — compare vendors, project costs, evaluate options — the default behavior is to do the math in its head and write the answer directly into prose:

Based on the pricing, Vendor A costs $2,510/year, Vendor B costs $2,627/year, and Vendor C costs $2,197/year. I recommend Vendor C, saving $430/year.

This looks helpful but is fragile: you can't tell where the numbers came from, you can't update them when inputs change, and you can't verify the math. The analysis-pipeline and review-facts skills push Claude to structure analyses as reproducible pipelines instead — every number traces back to a named, sourced input, and a separate agent audits the result before it ships.

Example

skills/analysis-pipeline/example/ contains a complete working pipeline (vendor cost comparison) you can run:

cd skills/analysis-pipeline/example
uv run model.py              # compute all values -> model_output.json
uv run fill_templates.py     # fill template placeholders -> memo.filled.md

Then audit it:

/review-facts .

Staying up to date

Third-party marketplaces have auto-update disabled by default. Enable auto-update in the /plugin UI (Marketplaces tab), or update manually:

/plugin marketplace update bestdan/workflow-skills
/reload-plugins

Development

Run the full quality gate locally with just check. Start at AGENTS.md for the map of the repo and the conventions that are load-bearing, then CONTRIBUTING.md for the dev loop and the "adding a skill" checklist.

License

MIT