README
¶
planwerk-agent
AI-powered code review and codebase analysis tool for GitHub repositories. Uses Claude Code to automatically analyze PR changes and produce structured review results, to analyze entire repositories and generate actionable feature proposals, to audit an entire codebase against all known review patterns, to elaborate high-level issues into detailed engineering plans, or to generate copy-paste-ready prompts that fix or implement an issue.
Features
Commands
- Review a pull request and produce a structured, severity-categorized report
- Propose feature work by analyzing an entire repository
- Audit a codebase against every known review pattern
- Sync the GitHub Wiki against the code, flagging stale and redundant knowledge
- Gap-analysis of completed features against the actual code
- Elaborate a high-level issue into a detailed engineering plan
- Prompt generation that fixes or implements an issue
- Implement an elaborated issue end to end and open a draft PR
- Ship a Meta Issue: drive every Sub Issue to merged, in dependency order
- Fix a PR's failing CI checks in a self-healing loop
- Rebase a PR onto its base, resolve conflicts with Claude, and analyze the rebased commits
- Address a PR's review comments by incorporating selected threads as follow-up commits
Skills
Some of this work needs decisions only a human can make, so it ships as interactive Claude Code Skills rather than subcommands:
/planwerk:draftturns a one-line idea into a ready-to-file GitHub issue/planwerk:elaborateexpands an issue into an engineering plan grounded in the repository/planwerk:cleanupsurveys a codebase for dead and duplicated code, and files a Meta Issue with a phased, evidence-backed cleanup plan/planwerk:metasplits a Meta Issue into linked, dependency-ordered Sub Issues/planwerk:decideverifies 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:revisitre-checks a prepared issue against what has actually landed since, and corrects what went stale/planwerk:clarifyanswers the open questions that stopped a planning session, and records them where the next one reads them/planwerk:implementimplements 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:diagnosereproduces a reported bug with a feedback loop that goes red before any theory, and fixes the root cause behind a regression test/planwerk:fixrepairs a pull request's failing CI checks, asking you whether the code or the test is the wrong one/planwerk:humanizerewrites existing prose to remove the signs of AI writing, preserving every fact
Quick start
Install the latest release:
go install github.com/planwerk/planwerk-agent/cmd/planwerk-agent@latest
# or, with Homebrew:
brew install planwerk/tap/planwerk-agent
Review a pull request:
planwerk-agent owner/repo#123
Install the skills:
claude plugin marketplace add planwerk/planwerk-agent
claude plugin install planwerk@planwerk-agent
You need Claude Code and the
gh CLI installed and authenticated. See
Getting started
for the full walkthrough, and
Use the skills
for the skills.
Documentation
Full documentation lives at https://planwerk.github.io/planwerk-agent/, organized along the Diátaxis framework:
- Tutorials — learning-oriented, guided paths
- How-to guides — task-oriented recipes
- Reference — every command, flag, and field
- Explanation — concept, methodology, and design decisions
License
Licensed under the Apache License 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
planwerk-agent
command
|
|
|
planwerk-eval
command
Command planwerk-eval is a dev-only harness that scores the review pipeline's output quality against a labeled seeded-bug corpus.
|
Command planwerk-eval is a dev-only harness that scores the review pipeline's output quality against a labeled seeded-bug corpus. |
|
internal
|
|
|
address
Package address orchestrates the `address` subcommand: it fetches a PR's human review threads, lets the operator select which unresolved ones to act on, dispatches Claude to incorporate each as a follow-up commit, pushes the commits, and (gated) replies to and resolves each addressed thread.
|
Package address orchestrates the `address` subcommand: it fetches a PR's human review threads, lets the operator select which unresolved ones to act on, dispatches Claude to incorporate each as a follow-up commit, pushes the commits, and (gated) replies to and resolves each addressed thread. |
|
attribution
Package attribution centralizes the self-attribution that planwerk-agent stamps on every artifact it leaves on GitHub — issue bodies, pull request descriptions, review comments, thread replies — and prints in its CLI previews.
|
Package attribution centralizes the self-attribution that planwerk-agent stamps on every artifact it leaves on GitHub — issue bodies, pull request descriptions, review comments, thread replies — and prints in its CLI previews. |
|
brain
Package brain reads and builds a repository's project memory.
|
Package brain reads and builds a repository's project memory. |
|
capture
Package capture is the read-only proposal engine that mines an implement run's review findings, plan, and implementation report for project knowledge worth recording on the target repo's GitHub Wiki — without writing anything.
|
Package capture is the read-only proposal engine that mines an implement run's review findings, plan, and implementation report for project knowledge worth recording on the target repo's GitHub Wiki — without writing anything. |
|
checklist
Package checklist provides the review checklist used in the Claude prompt.
|
Package checklist provides the review checklist used in the Claude prompt. |
|
doccheck
Package doccheck detects documentation files that may need updating based on code changes in a PR.
|
Package doccheck detects documentation files that may need updating based on code changes in a PR. |
|
domains
Package domains provides the domain list the planning prompts sweep before they commit to a change set.
|
Package domains provides the domain list the planning prompts sweep before they commit to a change set. |
|
eval
Package eval is a dev-only output-quality harness for the review pipeline.
|
Package eval is a dev-only output-quality harness for the review pipeline. |
|
extract
Package extract anchors a target repository's GitHub Wiki review patterns into committed, reproducible files.
|
Package extract anchors a target repository's GitHub Wiki review patterns into committed, reproducible files. |
|
gapanalysis
Package gapanalysis compares completed Planwerk feature files against the actual repository state and reports gaps — acceptance criteria, scenarios, test specifications, or tasks marked complete in the spec but not yet implemented in the code.
|
Package gapanalysis compares completed Planwerk feature files against the actual repository state and reports gaps — acceptance criteria, scenarios, test specifications, or tasks marked complete in the spec but not yet implemented in the code. |
|
github/githubtest
Package githubtest is the one test double for github.Client.
|
Package githubtest is the one test double for github.Client. |
|
gitref
Package gitref reads repository content as it stands at a git ref rather than as it stands in the working tree.
|
Package gitref reads repository content as it stands at a git ref rather than as it stands in the working tree. |
|
gitref/gitreftest
Package gitreftest builds throwaway git repositories for tests of code that reads content at a ref.
|
Package gitreftest builds throwaway git repositories for tests of code that reads content at a ref. |
|
glossary
Package glossary reads a target repo's own domain vocabulary so the review, elaborate, and propose commands phrase their output in the repo's terms, and generates a starter glossary artifact for a repo that has none.
|
Package glossary reads a target repo's own domain vocabulary so the review, elaborate, and propose commands phrase their output in the repo's terms, and generates a starter glossary artifact for a repo that has none. |
|
hygiene
Package hygiene holds the finding-hygiene stage that both the review and implement commands run over a set of review findings before they are acted on.
|
Package hygiene holds the finding-hygiene stage that both the review and implement commands run over a set of review findings before they are acted on. |
|
implement
Package implement turns an elaborated GitHub issue into a single Claude Code session that implements the feature end-to-end (code + tests + docs) inside a fresh clone of the target repository.
|
Package implement turns an elaborated GitHub issue into a single Claude Code session that implements the feature end-to-end (code + tests + docs) inside a fresh clone of the target repository. |
|
logging
Package logging configures the process-wide slog default logger and provides a human-friendly console handler plus JSON output for CI logs.
|
Package logging configures the process-wide slog default logger and provides a human-friendly console handler plus JSON output for CI logs. |
|
mdfence
Package mdfence sizes Markdown backtick fences from the text they wrap.
|
Package mdfence sizes Markdown backtick fences from the text they wrap. |
|
mirror
Package mirror keeps a local copy of what a repository knows on GitHub: one markdown file per issue and per pull request with the whole conversation, the commit list of the default branch, and a clone of the wiki.
|
Package mirror keeps a local copy of what a repository knows on GitHub: one markdown file per issue and per pull request with the whole conversation, the commit list of the default branch, and a clone of the wiki. |
|
patterns/patternstest
Package patternstest holds the helpers shared by the tests of the commands that hand a wiki's project memory to a session: the wiki seam and the page it returns, and the checks on the directory patterns.MaterializeMemory writes for a run.
|
Package patternstest holds the helpers shared by the tests of the commands that hand a wiki's project memory to a session: the wiki seam and the page it returns, and the checks on the directory patterns.MaterializeMemory writes for a run. |
|
planwerk
Package planwerk detects and parses Planwerk feature files from a repository.
|
Package planwerk detects and parses Planwerk feature files from a repository. |
|
rebase
Package rebase orchestrates the `rebase` subcommand: it replays a PR's commits onto a freshly fetched base branch, dispatches Claude to resolve each conflict semantically, then analyzes the rebased commits against the upstream range that entered the base since the PR forked.
|
Package rebase orchestrates the `rebase` subcommand: it replays a PR's commits onto a freshly fetched base branch, dispatches Claude to resolve each conflict semantically, then analyzes the rebased commits against the upstream range that entered the base since the PR forked. |
|
redact
Package redact scrubs common secret patterns from untrusted PR content before it is forwarded to Claude.
|
Package redact scrubs common secret patterns from untrusted PR content before it is forwarded to Claude. |
|
report/schema
Package schema holds the JSON Schema documents that describe planwerk-agent's machine-readable (--format json) output.
|
Package schema holds the JSON Schema documents that describe planwerk-agent's machine-readable (--format json) output. |
|
reviewprepared
Package reviewprepared analyzes Planwerk feature files in the "prepared" state, surfaces quality issues in the SPEC ITSELF, and (optionally) opens a pull request that rewrites each feature JSON with the improvements.
|
Package reviewprepared analyzes Planwerk feature files in the "prepared" state, surfaces quality issues in the SPEC ITSELF, and (optionally) opens a pull request that rewrites each feature JSON with the improvements. |
|
search
Package search keeps a full-text index of a mirror directory and answers ranked keyword queries over it.
|
Package search keeps a full-text index of a mirror directory and answers ranked keyword queries over it. |
|
ship
Package ship is the unattended fleet driver for a Meta Issue: it drives every one of the Meta Issue's Sub Issues to merged on the default branch, in dependency order, without a human in the loop.
|
Package ship is the unattended fleet driver for a Meta Issue: it drives every one of the Meta Issue's Sub Issues to merged on the default branch, in dependency order, without a human in the loop. |
|
skills
Package skills discovers the Claude Code Agent Skills a target repository ships under .claude/skills/ so the orchestrated implement/fix/address prompts can list them and oblige the session to use a matching one instead of improvising.
|
Package skills discovers the Claude Code Agent Skills a target repository ships under .claude/skills/ so the orchestrated implement/fix/address prompts can list them and oblige the session to use a matching one instead of improvising. |
|
styleguide
Package styleguide discovers the documentation style guide a target repository commits as STYLE_GUIDE.md so the mutating prompts (implement, fix, address) can bind the documentation prose the session writes — README and docs pages, CHANGELOG entries, doc comments / docstrings, CLI help text — to the repo's own rules.
|
Package styleguide discovers the documentation style guide a target repository commits as STYLE_GUIDE.md so the mutating prompts (implement, fix, address) can bind the documentation prose the session writes — README and docs pages, CHANGELOG entries, doc comments / docstrings, CLI help text — to the repo's own rules. |
|
sync
Package sync reconciles a target repository's GitHub Wiki knowledge — its review patterns and project-memory pages — against the current state of the code.
|
Package sync reconciles a target repository's GitHub Wiki knowledge — its review patterns and project-memory pages — against the current state of the code. |
|
todocheck
Package todocheck reads TODOS.md from a repository and provides its content for cross-referencing with PR changes.
|
Package todocheck reads TODOS.md from a repository and provides its content for cross-referencing with PR changes. |
|
workspace
Package workspace owns the cross-cutting helpers shared by the --local code path: the dirty-working-tree gate, origin detection, the interactive y/n prompter, and a stdin-is-a-TTY check.
|
Package workspace owns the cross-cutting helpers shared by the --local code path: the dirty-working-tree gate, origin detection, the interactive y/n prompter, and a stdin-is-a-TTY check. |
Click to show internal directories.
Click to hide internal directories.