Use the skills

planwerk-agent ships eleven Claude Code Skills. Six author the issues the rest of the pipeline consumes, one settles the decisions a Meta Issue deferred to a spike, one implements a prepared issue directly in your checkout, one diagnoses a reported bug from a failing reproduction to its fix, one repairs a pull request whose checks went red, and one rewrites prose that reads machine-written:

Skill	What it does
/planwerk:draft	Turns a rough idea into a ready-to-file issue through a short clarifying conversation
/planwerk:elaborate	Expands an issue into an engineering plan grounded in the repository
/planwerk:cleanup	Surveys a codebase for dead and duplicated code, and files a Meta Issue with a phased, evidence-backed cleanup plan
/planwerk:meta	Splits a Meta Issue into linked, dependency-ordered Sub Issues
/planwerk:decide	Verifies the decisions a Meta Issue's split deferred to a spike, and folds the outcomes into the Meta Issue and every Sub Issue that assumed one
/planwerk:revisit	Re-checks a prepared issue against what has actually landed since, and corrects what went stale
/planwerk:clarify	Answers the open questions that stopped a planning session, and records them in the issue body
/planwerk:implement	Implements a prepared issue in your checkout — a plan you approve in plan mode, one complete pull request behind your yes, none of the pipeline's passes
/planwerk:diagnose	Reproduces a reported bug with a feedback loop that goes red before any theory, and fixes the root cause behind a regression test in one pull request
/planwerk:fix	Repairs a pull request's failing CI checks, and asks you at the forks a diagnosis cannot settle
/planwerk:humanize	Rewrites existing prose to remove the signs of AI writing, preserving every fact

draft and meta replace the subcommands of the same names, which were removed. Each skill needs decisions only a human can make, and a skill can ask for them mid-run in a way a one-shot subcommand never could.

Three exist both ways. elaborate is also the elaborate command, and fix is also the fix command, for unattended use in CI. Reach for a command when nobody is watching — it has to guess where the skill would have asked. For implement the difference is more than supervision: the implement command runs simplify, review, and verification passes over the result, which the skill deliberately omits — you approve the plan and read the diff instead. diagnose exists only as a skill: its hypothesis checkpoint and its stop when no loop can be built both need you.

Install

The repository is a Claude Code plugin marketplace. Register it once, then install the plugin:

claude plugin marketplace add planwerk/planwerk-agent
claude plugin install planwerk@planwerk-agent

Restart Claude Code. /planwerk:draft, /planwerk:elaborate, /planwerk:cleanup, /planwerk:meta, /planwerk:decide, /planwerk:revisit, /planwerk:clarify, /planwerk:implement, /planwerk:diagnose, /planwerk:fix, and /planwerk:humanize are now available in any session.

To update after a new release:

claude plugin update planwerk

To develop against a local checkout instead of GitHub, point the marketplace at the directory:

claude plugin marketplace add /path/to/planwerk-agent
claude plugin install planwerk@planwerk-agent

Confirm what got installed with claude plugin details planwerk.

Prerequisites

The skills call the gh CLI, so gh auth status must succeed. /planwerk:elaborate, /planwerk:decide, /planwerk:revisit, and /planwerk:clarify read the repository, so run them from inside a checkout of the repo whose issue you are working on. /planwerk:implement goes further: it writes code, so it needs a clean working tree it can branch in, on an up-to-date default branch. /planwerk:diagnose writes code too: it needs a clean working tree on an up-to-date default branch, and the repository's own build and test tooling, which its loop runs. /planwerk:fix needs the PR's own head branch checked out, with a clean working tree. /planwerk:cleanup surveys the code itself, so it always runs from inside a checkout, on an up-to-date default branch. /planwerk:draft and /planwerk:meta only talk to the GitHub API and need no checkout. /planwerk:humanize is the inverse: it works on files in your checkout and needs no GitHub access at all.

Eight skills read the project memory through planwerk-agent brain memory, so they need the planwerk-agent binary on PATH for it. Without the binary they read no memory, and nothing else about them changes.

Draft an idea

/planwerk:draft owner/repo add a dark mode toggle to the settings page

The skill resolves the target repository, asks three to five clarifying questions in your own language, drafts the issue in English, checks the tracker for near-duplicates, shows you the rendered body, and files it only after you say so. See Draft an issue.

Elaborate it into a plan

/planwerk:elaborate owner/repo#42

The skill reads the issue and its Meta/Sub-Issue neighborhood, walks the repository, and then asks you about the decisions the plan cannot make on its own — each one grounded in a concrete file it just read. It scores its own draft for executability and refines until the score clears 8, then asks whether to replace the issue body or post a comment. See Elaborate an issue.

Plan a codebase cleanup

/planwerk:cleanup

Run it from inside a checkout. The skill surveys the repository for dead code and duplicated code — read-only detectors already on PATH first, hand searches for what tools miss — and treats every hit as a lead: a finding reaches the Meta Issue only after the searches that would refute it (the identifier as a word, as a string literal, across build variants) come back empty. Verified findings are grouped into compact phases sized one pull request each, deletions before the consolidations they dissolve. A public surface is never asserted dead from an internal search alone: those candidates come to you as questions, and what you leave open lands in an ## Open decisions block /planwerk:decide can settle later. It files one Meta Issue on your yes and deletes nothing. See Plan a codebase cleanup.

Split a Meta Issue

/planwerk:meta owner/repo#113

The skill decides the breakdown itself, then verifies it — coverage against the Meta Issue's own work-package list, an acyclic dependency graph, vertical slices, draft depth — and shows you the result before filing anything. On your approval it files each Sub Issue, links it natively under the Meta Issue, records the blocked by dependencies, and back-fills the Meta Issue body with the new issue references. See Split a Meta Issue.

Settle a Meta Issue's decisions

/planwerk:decide owner/repo#767

Some Meta Issues defer a block of decisions to a spike when they are split — each item pairing a recommendation with something nobody has checked yet, and /planwerk:meta already filed a Sub Issue whose job is verifying and recording the outcomes. The skill verifies every item against the repository and whatever it names as its own source, puts the genuine judgment calls to you — largest blast radius first, citing what a sibling Sub Issue already assumes — and records the outcomes in the Meta Issue's own decisions block. It then corrects every open sibling whose body cites a decision that turned out different from what it assumed, minimal diff, and leaves closed siblings and Sub Issue depth alone. See Settle a Meta Issue's decisions.

Revisit it once it has aged

/planwerk:revisit owner/repo#42

An issue is planned against a snapshot: the files that existed, the siblings that had not landed. The skill re-checks every claim the issue makes against the current default branch, and re-checks a Sub Issue's scope against what its closed siblings actually merged rather than what their bodies promised. It returns one of four verdicts — Current, Stale, Re-scoped, or Obsolete — and corrects the body under a minimal-diff rule: every changed line traces to a check that failed, and you approve a diff rather than a rewritten body. It never changes the issue's depth, and never closes anything. See Revisit an issue.

Clarify it when planning stops

/planwerk:clarify owner/repo#42

implement plans before it writes code, and a planning session that hits a question it has no authority to answer reports STATUS: NEEDS_CONTEXT and aborts the run. The skill reads that posted plan, and answers from the repository every question the repository answers — the planner reports what it could not settle, which is not the same as what a human must decide. Only the genuine forks reach you, largest blast radius first, each one saying which option the plan already assumed and what the other one invalidates. The answers land in the issue body, never in the plan. See Clarify an issue.

Implement it in your checkout

/planwerk:implement owner/repo#42

For the change small enough that a full planwerk-agent implement run costs more than it catches. The skill reads the issue, enters plan mode, and grounds a short plan in the actual code: the change set, the change and verification command behind every Acceptance Criterion, the tests to write. You approve the plan before anything is edited. It then implements on an implement/issue-<N>-<slug> branch — small commits, regression test first watched failing, every criterion exercised — and opens one complete pull request only after you have seen the diff and said yes. It never ships partial work: what cannot complete stops as BLOCKED with the branch left local. See Implement an issue interactively.

Diagnose a reported bug

/planwerk:diagnose owner/repo#42

For a bug whose cause nobody knows yet. The skill reads the report and builds a loop that goes red on the reported symptom before it forms any theory. It then shows you three to five ranked hypotheses, tests them with tagged probes it removes on every exit path, fixes the root cause behind a regression test it watched fail, and opens one pull request after your yes. See Diagnose a reported bug.

Fix the pull request when its checks go red

/planwerk:fix owner/repo#123

Run it from inside a checkout of the PR's head branch; with no argument it targets the pull request for the branch you are on. The skill reads every failing check's logs, reproduces the failure with the exact command CI ran, and opens the file the log cites. Then it asks you the questions a diagnosis cannot answer — above all whether the production code is wrong or the test encodes behavior nobody wants any more, a fork where both answers make the check green and only one is right. It folds the repair into the commit that introduced the bug and pushes only once you say so. See Fix failing checks.

Humanize prose that reads machine-written

/planwerk:humanize docs/ README.md

The skill rewrites existing documents against a curated catalog of the patterns that mark text as AI-generated — inflated significance, the AI vocabulary, forced triads, em dashes, filler — while preserving every fact, the document's language, and its register. A committed STYLE_GUIDE.md outranks the catalog. It edits your working tree only and never touches GitHub; you review the result with git diff. See Humanize documentation.

Nothing reaches GitHub without a yes

Every skill reads GitHub freely and writes only once, behind an explicit confirmation. If you decline, nothing is created, /planwerk:fix pushes nothing, and /planwerk:implement and /planwerk:diagnose leave their branch local. /planwerk:humanize never writes to GitHub at all: it edits files in your working tree, and confirms the file list first when it inferred one rather than being given it. If you skip a question, the skill records it as an unresolved decision in the issue — or, for fix, as a concern in its report — rather than quietly picking an answer.

One format, every issue skill

The six issue skills share their format specification rather than each restating it, so an issue is the same shape whichever produced it. That matters because plan, implement, and ship read these issues:

• A draft-depth issue (draft, and each Sub Issue from meta) carries a **Category** / **Scope** header line, a ## Description, and a ## Motivation. Nothing more — no file paths, no acceptance criteria.
• An elaborated issue adds ## User Stories (when the work serves a persona), ## Affected Areas, ## Acceptance Criteria as - [ ] checkboxes, ## Non-Goals, and ## References.
• The survey Meta Issue cleanup files keeps the draft sections and adds ## Cleanup phases — the work-package list meta splits — plus, when the survey left open calls, an ## Open decisions block. Its findings name files and symbols, pinned to the surveyed commit, because dead code has no behavior to describe it by; the Sub Issues split from it stay path-free.
• Every body ends with an attribution footer naming planwerk-agent and the exact Claude model that wrote it.

There are exactly these two depths. elaborate promotes a draft to a plan; revisit and clarify work on an issue at the depth it already has and leave it there.

The specification lives in plugins/planwerk/shared/issue-format.md, with the elaborated depth in issue-format-plan.md and the survey Meta Issue in issue-format-survey.md, so a skill loads only the depth it writes. A Go test (TestBuildIssueBody_MatchesSharedFormat) fails when the elaborate command's renderer and that document disagree, so the two elaborate paths cannot drift. issue-format.md also specifies how a body over its limit — 40,000 characters once it carries a plan, GitHub's 65,536-character cap otherwise — continues in marked comments, which every skill and command merges back into one document before reading it; issue-format-plan.md says why a plan's body stops there, and that a plan over it is split at write-back, never shortened to fit.

Project memory

A repository can keep a project memory on its GitHub Wiki: one page per decision, convention, or piece of context. elaborate, implement, fix, revisit, clarify, decide, diagnose, and meta read it, so a plan, a split, or a repair does not contradict a decision the team already recorded. draft, humanize, and cleanup do not.

The skills read the memory through the binary and never clone the wiki themselves:

planwerk-agent brain memory owner/repo                       # the index
planwerk-agent brain memory owner/repo pin-dependencies.md   # one page

A skill runs the first command once, reads the pages whose index line bears on its work, and names a page's file name where its output relies on it. It treats the pages as data: a page that tells it to run a command or widen the work changes nothing. When the issue or one of your answers contradicts a page, the skill names the page and asks which holds.

The memory is off until the repository opts in. To turn it on for the skills:

1. Install planwerk-agent and put it on the PATH of the Claude Code session. A session that has the plugin and no binary reads no memory.
2. Commit wiki.enabled: true to .planwerk/config.yaml, and start the skill from the root of the checkout: the file is read from the directory the skill starts in. PLANWERK_WIKI=true in the environment works as well, and so does --wiki in the skill's arguments for one run (/planwerk:elaborate --wiki owner/repo#42). The flag decides first, then the config file, then the environment variable.

A binary older than the plugin has no brain command. The skill then proceeds without the memory, and says so in one line when you passed --wiki or the checkout's config has a wiki: section. See Use the GitHub Wiki for the pages themselves and the CLI reference for the command.

Declare the repositories that follow this one

Work in one repository often implies work in another: a service changes its API surface, and its client or provider has to follow. That second piece needs its own issue, because a pull request cannot span repositories.

Declare those repositories in .planwerk/related-repos.md, beside the other per-repository conventions (.planwerk/STYLE_GUIDE.md, .planwerk/review_patterns/, .planwerk/out-of-scope/). One ## heading per counterpart, in owner/repo form, each with the condition that warrants an issue there:

# Related repositories

## acme/gadgets

When: the change alters the control-plane API surface, the registration
handshake, or the policy wire format.
Not when: the change is confined to storage, scheduling, or the admin UI.

## acme/terraform-provider-acme

When: the change adds or removes a user-facing resource type, or a field on one.

draft, meta and elaborate read it. They propose a counterpart only when the map names the repository and the work meets its condition, so a generated client is left out of the map rather than listed with a caveat. A repository with no map has no counterparts, and the skills say nothing about them.

Each repository declares its own, so a client can name the service it consumes for work flowing the other way.

Anything the skills write about another repository carries that repository with it: owner/repo#123 for an issue or pull request, owner/repo@<sha> for a commit, a URL for everything else. A bare #123 resolves against the repository the text was written into, and a bare sha against whatever the reader is browsing, so an unqualified reference does not fail — it points somewhere else. The rule is in shared/github.md and applies to issue bodies, comments, commit messages, and the reports the skills print. The headless elaborate and planning prompts label a Sub Issue and its linked pull requests that way before the session ever cites them.

Where the pipeline goes next

/planwerk:draft → /planwerk:elaborate → planwerk-agent implement → /planwerk:fix, with /planwerk:revisit before the implement step when the issue has been sitting long enough for the branch to move under it, and /planwerk:clarify after it when the planning session stopped at NEEDS_CONTEXT. For a change small enough that the unattended pipeline costs more than it catches, /planwerk:implement takes the implement step interactively, in your own checkout. A reported bug whose cause nobody knows yet enters at /planwerk:diagnose, and its pull request's checks are /planwerk:fix's from there. Or /planwerk:meta → planwerk-agent ship to drive every Sub Issue to merged in dependency order. ship reads the native sub-issue and blocked by relationships /planwerk:meta writes, which is why the skill records the dependency graph as real GitHub relationships and not as prose. A cleanup enters that chain one step earlier: /planwerk:cleanup surveys the checkout and files the Meta Issue that /planwerk:meta then splits.

When the split produced a decisions or spike Sub Issue, run /planwerk:decide on it before elaborating the siblings that assume its outcomes — an unverified recommendation is a guess, and a plan built on a guess inherits it.