Use the GitHub Wiki

Make your repository's GitHub Wiki a source of project review patterns and project memory for review, audit, propose, elaborate, the implement plan step, fix, and address. ship hands the wiki to every implement and fix run it drives. The elaborate, implement, fix, revisit, clarify, decide, diagnose, and meta skills read the project memory as well (see Read the memory from the skills). The wiki is human-editable through the web UI and git-versioned, so this knowledge evolves independently of code commits and never pollutes a diff.

The wiki is off by default and opted into per repo with --wiki. A GitHub Wiki is a separate permission surface — often editable by any authenticated GitHub user (or any collaborator, including triage-only members), and never gated by branch protection or PR review. Enabling it feeds its content into the agent's prompts, including the implement, fix, and address sessions that write code and push it, so turn it on only for repos whose wiki editors you trust as much as your committers.

What the tool reads

The tool reads two directories from the target repo's wiki:

Wiki page	Purpose
review_patterns/<name>.md	A project review pattern in the standard Pattern Format. It loads through the wiki precedence tier — below the committed .planwerk/review_patterns (so a committed pattern overrides a same-named wiki one) and below an explicit --patterns.
memory/<name>.md	A project memory page: one decision, convention, or piece of context. Every prompt that reads the memory lists the pages in an index (file name, title, and the sentence of an optional **Summary**: line), and the session opens the pages its task needs. A page larger than 64 KB is skipped.

Any other page — Home, _Sidebar, navigation, or prose that does not parse as a pattern — is ignored, so a normal wiki can hold both human navigation and machine-read patterns side by side.

Author the pages

A GitHub Wiki is itself a git repo (https://github.com/owner/repo.wiki.git). Edit it through the web UI, or clone and push:

git clone https://github.com/owner/repo.wiki.git
cd repo.wiki
mkdir -p review_patterns memory
# a review pattern in the standard format
cat > review_patterns/db-query-builder.md <<'MD'
# Review Pattern: DB queries go through QueryBuilder

**Review-Area**: architecture
**Severity**: WARNING

## What to check

All database access must go through the QueryBuilder, never raw SQL strings.

## Why it matters

Raw SQL bypasses the query allow-list and parameterization the QueryBuilder
enforces.
MD
# a project-memory page: a title, a one-sentence summary, then the reasoning
cat > memory/pin-dependencies.md <<'MD'
# Pin every dependency

**Summary**: Dependencies are pinned to exact versions and never float a version range.

A floating range broke the release build twice. Renovate proposes the bumps.
MD
git add -A && git commit -m "Add review patterns and memory" && git push

The wiki must be initialized first: create at least one page through the repository's Wiki tab on github.com before the .wiki.git clone exists. A wiki that was never initialized is treated as "no wiki" — the run proceeds with the other pattern tiers and no project memory.

Write memory pages a session can find

A session does not receive the page bodies. It receives one index line per page and opens the pages its task needs, so the line decides whether a page is read:

- conventions.md: conventions
- pin-dependencies.md: Pin every dependency | Dependencies are pinned to exact versions and never float a version range.

To write a page that is found:

1. Start the page with a # <title> heading that names the decision. A page without a heading is listed under its file name without .md.
2. Add a **Summary**: <one sentence> line that states the decision itself, not its background. A page without the line stays valid and is listed under its title only.
3. Keep one decision per page, and keep the page under 64 KB. A larger page is skipped with a warning in the run's log.

The index has a budget of 64 KB, which holds about 250 pages of typical length. When a wiki exceeds it, the run's log warns with the number of pages that are not listed. The listed pages are the first ones in file-name order, and the session is told to list the directory for the rest. See the reference for the exact limits.

Enable, disable, and pin

The wiki is off by default. You opt in per run:

# Off by default: no wiki is read
planwerk-agent review owner/repo#123

# Turn it on for one run
planwerk-agent review --wiki owner/repo#123

# Pin the wiki to a fixed commit, tag, or branch for a reproducible run
planwerk-agent review --wiki --wiki-ref v1.4.0 owner/repo#123

Or set defaults in .planwerk/config.yaml:

wiki:
  enabled: true              # opt the wiki in (the default is off); false is the same as --no-wiki
  repo: owner/repo           # override the wiki source (default: the target repo)
  ref: main                  # pin to a branch/tag/commit

Precedence is flag → config file → environment variable (PLANWERK_WIKI, PLANWERK_WIKI_REF) → default-off. --no-wiki overrides --wiki.

The same opt-in applies to elaborate, fix, address, ship, and brain memory: each takes --wiki, --no-wiki, and --wiki-ref. A repository that already sets wiki.enabled needs no flag.

planwerk-agent elaborate --wiki owner/repo#123
planwerk-agent fix --wiki owner/repo#456
planwerk-agent address --wiki owner/repo#456
planwerk-agent ship --wiki owner/repo#100

Read the memory from the skills

The elaborate, implement, fix, revisit, clarify, decide, diagnose, and meta skills read the project memory through the binary and never clone the wiki themselves. A skill runs one command for the index and one per page its work touches:

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

To let the skills read the memory:

1. Put planwerk-agent on the PATH of the session that runs the skill. A session with the plugin and no binary reads no memory.
2. Opt the repository in with wiki.enabled: true in .planwerk/config.yaml, and start the skill from the checkout's root, where that file is read. As an alternative, export PLANWERK_WIKI=true, or pass --wiki in the skill's arguments for one run (/planwerk:elaborate --wiki owner/repo#123). The flag decides first, then the config file, then the environment variable.

With the wiki off, or with a wiki that has no memory pages, the command prints nothing and the skill proceeds without a memory. The draft, humanize, and cleanup skills read none. A skill run proposes and pushes no wiki page.

Private wikis

A private wiki is cloned with your GitHub token (taken from gh auth token), so it works transparently whenever you can already access the repo with gh. A public wiki clones anonymously. The token is never written to the cached clone or to git's output.

Reproducibility

The wiki is resolved to a concrete commit at the start of each run. That commit is recorded in the report header (> Wiki: owner/repo.wiki @ <short-sha>) and folded into the cache key, so editing the wiki re-runs the review rather than serving a stale cached result, and two runs against the same wiki commit produce the same review.

Capture knowledge from a findings-producing run (propose-only)

When implement, review, or audit runs with --wiki, a read-only capture pass proposes new wiki pages from the findings — so the wiki grows from every findings-producing run, not only by hand. Generalizable review findings become candidate review_patterns/ pages; under implement, durable rationale from the plan and the implementation report also becomes candidate memory/ pages. (A standalone review or audit has no plan or report, so it proposes patterns only.) Every candidate is deduplicated against the wiki's existing entries and the bundled pattern catalog, so capture does not re-propose what is already recorded.

The pass is propose-only: the suggestions surface in the run report — and as a comment on the source issue (implement) or PR (review --post-review) — and nothing is written to the wiki. Review them and add the ones worth keeping. It is on by default whenever a wiki is resolved; disable it with --no-capture. It runs on a cache miss only, so a cached review/audit proposes nothing. Under ship, every implement run it drives ends with this pass and comments on its Sub Issue. ship --no-capture turns it off.

The proposed memory/ pages follow a small write convention so they stay easy to maintain by hand or by a later automated write-back:

• One page per durable decision. A memory page records a single "why" — a non-obvious choice, a constraint to honor, a trade-off that was weighed — not a catch-all log.
• A stable, descriptive slug. Re-running capture on the same decision reuses the same memory/<slug>.md path, so it updates the page in place rather than appending a near-duplicate.
• A title and a summary line. The page has a # <title> heading that names the decision and, below it, a **Summary**: <one sentence> line that states it. Those two are what a session sees in the memory index. A proposed update to a page that has no summary line adds one.
• A provenance marker. Each proposed page begins with an HTML comment — <!-- planwerk-agent: captured from owner/repo#123 --> — that marks it as tool-authored (rather than hand-authored) and names the issue it came from. The marker is fixed for a given source, so a re-run does not churn the page.

Push accepted pages to the wiki (opt-in)

By default the capture pass writes nothing — it only proposes. Pass --capture-wiki to turn the accepted pages into real wiki growth: a separate, mechanical write phase clones the wiki fresh, writes each page (provenance marker included) under the pinned planwerk-agent identity, and pushes. When the wiki has never been initialized, the first page creates its initial commit.

The write-back is available only from a trusted source — implement (your own branch), ship (the implement runs it drives), and audit (your own repo). review has no --capture-wiki flag and is always propose-only: a review analyzes an untrusted pull request and the proposal pass reads attacker-controlled source, so auto-pushing its free-form pages would let an external contributor poison the shared knowledge base via indirect prompt injection. Capture patterns from a review by reading its proposals and adding the ones worth keeping by hand.

planwerk-agent implement --wiki --capture-wiki owner/repo#123          # confirms, then pushes
planwerk-agent implement --wiki --capture-wiki --yes owner/repo#123    # non-interactive (CI)
planwerk-agent audit --wiki --capture-wiki owner/repo                  # from a standalone audit
planwerk-agent ship --wiki --capture-wiki --yes owner/repo#100         # from every Sub Issue's run

The write is gated to match the rest of the wiki surface. Claude never pushes: it authored the page bytes in the read-only proposal pass, and this phase performs the push, preserving the read-only-author / write-phase separation. The phase confirms interactively first and refuses a non-TTY run without --yes. The gate is also settable per repo via the PLANWERK_CAPTURE_WIKI environment variable or a capture.wiki: true config key (flag → config → env → off). The write-back is non-fatal: a refusal or push failure degrades back to propose-only rather than failing the run. The push authenticates a private wiki exactly as sync does — see its write-phase note for the auth details.

The write phase never replaces a page the run did not read: a new page whose path the wiki already holds is skipped with a Skipped line.

ship runs unattended and never shows the confirmation prompt. It pushes the accepted pages only when the write-back is enabled and --yes is given. Enabled without --yes, ship logs one warning at start and every run stays propose-only.

Start from the repository's history

A repository that turns the wiki on starts with an empty memory, while its earlier decisions sit in closed issues, review threads, and commit messages. brain bootstrap distills that history into memory pages and review patterns, has a second model review each page, and pushes them after you confirm. See Bootstrap the project memory.

Keep the wiki trustworthy

Wiki knowledge drifts as the code changes, so the highest-priority source quietly rots. Run sync to flag entries that reference code that no longer exists (stale) or that duplicate another entry (redundant), and to prune them after confirmation — keeping the wiki worth reading.

See the Review patterns reference for the precedence model and the CLI reference for every flag.