Repository navigation
docs: rewrite the plugin docs for users, and cut CLAUDE.md to the traps - #144
Merged
Merged
Conversation
Output of setup-matt-pocock-skills: GitHub Issues as the tracker, the five default triage labels, and a multi-context domain-doc layout with one context per plugin or app. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Move picking a flavour into a Usage section, and state the Paseo requirement once. Drop the palette-mapping note, which is for whoever changes the themes, not for users. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Put installation and the settings location first, since that is what a user of the plugins needs, and shorten local development and releasing. Drop the note on settings from before Paseo 0.9, which no installation is still on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Split usage into tasks, add a settings table, and correct the troubleshooting rows against the code: the real "Discord is not running" label, where the Application ID field sits, and how the plugin finds the daemon and its password. Drop the note on settings from before Paseo 0.9 and the implementation notes that only matter to whoever changes the code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keep the reason the adapter exists, requirements, usage, an environment variable table, short limitations and troubleshooting. Move what passes as a design decision out of "How it works" into ADRs: the PTY-driven interactive CLI, reading output from the transcript, hooks for everything interactive, and holding the turn open for background work. Give the package a CLAUDE.md with the traps that break the adapter when unknown, and cut the rest of the internals. Correct the README against the code: document CLAUDE_TTY_ACP_STATE_SCOPE, inline embedded text up to 32 KB instead of writing it to a file, and say that declining the Bypass Permissions disclaimer fails the session start. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace the wall of paragraphs under Installation with a Usage section per task: starting a review, picking from review requests, reading the guide, a change that moves on, commenting, and finishing. Cut troubleshooting to the problems whose message does not give the fix, and name the settings as the settings screen does. Drop what the code no longer does: GitHub comments on a concept are no longer folded into the pending review's body, and the review body is kept by the plugin on both forges. Record that drafts live on the forge as an ADR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Turn the intro's essays into a Usage section per task, put the four settings in a table, and keep troubleshooting to what Diagnostics does not tell you. Drop the upgrade notes for the old traecli provider, which no installation is still on, and record the move to a provider of the plugin's own as an ADR instead. Record as ADRs that the adapter is built from the plugin's checkout and that the settings are host-wide in Paseo's store. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keep basic orientation and the things that break when unknown; cut rationale, history, walkthroughs of what the code does, and rules the root CLAUDE.md or Paseo's plugin reference already state. Move the decisions with a real trade-off into ADRs: the plugin workspace layout and the linked claude-tty versions at the root; the adapter subprocess, the tool-call vendor method and Paseo's own question cards for claude-tty; the daemon connection for discord-rich-presence; reading the change with git for guided-review. Give the README template a Usage section, make Screenshots and Settings optional, and state the README rules so a feature updates its section instead of appending a paragraph. Correct stale claims on the way: discord's settings schema drops unknown keys rather than rejecting them, and Paseo's install paths are relative to the installed packages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Order it for a user first and a contributor after: overview, installation, development, releasing. Turn development into the steps from a clone to a reloaded plugin, saying that Paseo compiles the bundles itself and only the claude-tty adapter needs a build. Drop the settings location and the pnpm remark from installation, which Paseo and each plugin's README already document, and the plugin-enable step that Paseo no longer has. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add a From source section for running every change on main as it lands, with updating through git pull or the update-plugins skill, and build the development steps on it. Open the release section by saying releases are automatic, so a contributor knows there is nothing to bump by hand. Drop installing a skill into another checkout, since the skills only serve work on this repository. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Name where the build commands live instead of listing which plugins have one today. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Releasing mentioned Paseo Cafe without saying what it is, so introduce it and the official registry under Installation and link there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each plugin's installation now lists its requirements, installs with the github: command, names the registries it is listed in on one line, and links to the root README for installing from source. The README template in CLAUDE.md carries the same shape, and claude-tty-acp folds its requirements into it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The shared typecheck, test, reload and logs commands now live only in the root README, so each package's Development section links there and keeps just what is specific to it. READMEs no longer point at CLAUDE.md, which agents load on their own, and every package with ADRs links to them instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README said every saved draft goes on the forge right away, which is false for GitHub comments on a concept or on highlighted text: they stay local until submit and are then posted as separate PR comments. It also no longer said that only github.com is supported, that GitHub ties a review to the explained commit, where review clones come from, or what to do about GitLab's "Reviewer not found", whose message does not give the fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rewrite dropped the only note that recorded fixtures are trimmed to public fields with emails and private repositories taken out, which nothing in the code says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… PTY write trap A comment in claude-runtime.ts pointed at a README explanation the rewrite removed, so the reason now sits in the comment itself. CLAUDE.md said one write to the PTY is one read for Claude, while prompt-content.ts batches pastes because a large write can be split across reads. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The loader does not need exactly index.client.tsx and index.server.ts: catppuccin-theme ships index.client.ts and no server entry. The note that each skill is a symlink from .claude/skills/ and .agents/skills/ into skills/ was cut with the README's skills section, which leaves an agent adding a skill to only one harness. GLOSSARY-MAP.md and the per-context glossaries were described as existing, while none does yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README said a GitHub or registry install only updates when a plugin releases, but paseo plugin update moves a Git install to the remote's default HEAD, as the old README said. Installing from source is for running your own changes, and installing by registry ID needs Paseo 0.11, which the rewrite no longer said anywhere. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The plugin itself runs on 0.9, so the requirements list alone invited a 0.9 or 0.10 user to a registry install that fails. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tually does runtimeDir takes the first of XDG_RUNTIME_DIR, TMPDIR, TMP and TEMP that is set and never falls back to the next, so a daemon whose XDG_RUNTIME_DIR differs from Discord's misses the socket even as the same user. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The list read as complete but left out the other vendor methods, the dialog input marker, the settings snapshot, the diagnose output, the session and lock files, and Claude's config directory. It now points at the "Mirrors the adapter's own" marks so a contract it misses is still found. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The triage label table and the PR triage flag still carried the setup skill's notes on how to fill them in. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
READMEs are for people using the plugins,
CLAUDE.mdholds only the traps an agent cannot find out from the code orgit log, and decisions with a real trade-off become ADRs.Dropped: upgrade notes for
traecliand pre-0.9 settings (thetraeclihistory is ADR 0001 inclaude-tty), internals in user docs, edge cases the UI already shows, and troubleshooting rows whose message already gives the fix.Claims that no longer matched the code were fixed or removed on the way, e.g. GitHub comments on a concept are no longer folded into the review body, Discord's real "Discord is not running" label, and the undocumented
CLAUDE_TTY_ACP_STATE_SCOPE.Evidence
Words per document, before → after:
Every relative link and anchor in the Markdown resolves.
The only non-Markdown change is one comment in
plugins/claude-tty/scripts/set-identity.mjs.Merge Danger
Door: two-way
Docs only; every commit is
docsorchore, so release-please releases nothing.Blast Radius: documentation
Agents working in the repo now see far less context in
CLAUDE.md; anything cut that turns out to matter is still ingit logand the old files.