sync-upstream

# Sync Upstream This skill keeps the plugin marketplace in lockstep with its upstream sources while preserving plugin-specific customizations. The upstream repos and what we track from each: - **superpowers** — `~/workspace/random/superpowers` (clone of `github.com/obra/superpowers`) — core workflow skills (currently: `systematic-debugging`, which is mirrored into the **lesserpowers** plugin, not superpowers) - **haft** — `~/workspace/random/quint-code` (clone of `github.com/m0n0x41d/quint-code`; the local path still uses the old `quint-code` name, the project itself is now `haft`) — FPF reasoning methodology: the v8 skill catalog (`internal/cli/skill/h-*/SKILL.md`) and CLAUDE.md → PRINCIPLES.md context - **agentic-evolve** — `~/workspace/random/agentic-evolve` (clone of `github.com/ericksoa/agentic-evolve`) — evolve commands (master dispatcher + perf/size/ml subskills) - **agent-browser** — `~/workspace/random/agent-browser` (clone of `github.com/vercel-labs/agent-browser`) — browser automation CLI skill (slim discovery stub) - **dmmulroy-skills** — `~/workspace/random/dmmulroy-skills` (clone of `github.com/dmmulroy/skills`) — the `bro` and `herdr` skills, mirrored into **superpowers** - **cursor-plugins** — `~/workspace/random/cursor-plugins` (clone of `github.com/cursor/plugins`) — the `unslop` skill from the `pstack` plugin, mirrored into **superpowers** ## High-level flow 1. Pull latest from each upstream repo. 2. Identify which tracked files actually changed. 3. Summarize the changes for the user (high-level, not line-by-line). 4. Confirm before applying anything. 5. Apply updates with intelligent merging that preserves plugin customizations. 6. Report what landed. The reason confirmation matters before applying is that some files in this plugin have hand-edited customizations (namespace prefixes, removed cross-skill references) that a blind copy would clobber. We let the user approve so they can intervene on the manual-merge cases. ## Step 1 — Pull latest changes from upstream Pull each upstream repo independently. If any pull fails, surface the error and ask the user to resolve manually rather than guessing. ```bash cd ~/workspace/random/superpowers && git pull origin main cd ~/workspace/random/quint-code && git pull origin main cd ~/workspace/random/agentic-evolve && git pull origin main cd ~/workspace/random/agent-browser && git pull origin main cd ~/workspace/random/dmmulroy-skills && git pull origin main cd ~/workspace/random/cursor-plugins && git pull origin main ``` The pull output reveals the old → new commit range and the touched files, which is what later steps key off. ## Step 2 — Identify the tracked surface area These are the only paths to consider when comparing upstream against this plugin. Anything else upstream changed is irrelevant. **From `~/workspace/random/superpowers/`:** - `skills/systematic-debugging/` (entire directory — includes supporting `.md` files) → mirrored into `lesserpowers/skills/` **From `~/workspace/random/quint-code/`:** - `internal/cli/skill/h-*/SKILL.md` → mirrored into `haft/skills/h-*/SKILL.md` (the full v8 skill catalog — one directory per skill). As of v8 there are no `internal/cli/commands/` files; the surface is skills only. - `CLAUDE.md` → mirrored into `haft/context/PRINCIPLES.md` - And: delete the cached MCP binary at `haft/bin/haft` so the SessionStart hook rebuilds it on next launch. **From `~/workspace/random/agentic-evolve/.claude/commands/`:** - `evolve.md`, `evolve-perf.md`, `evolve-size.md`, `evolve-ml.md` → mirrored into `lesserpowers/commands/` **From `~/workspace/random/agent-browser/skills/agent-browser/`:** - `SKILL.md` only. Upstream restructured this into a slim discovery stub that delegates to `agent-browser skills get core` at runtime, so any old `references/` or `templates/` directories under the plugin copy should be removed. **From `~/workspace/random/dmmulroy-skills/`:** - `bro/SKILL.md` → `superpowers/skills/bro/SKILL.md` - `herdr/SKILL.md` → `superpowers/skills/herdr/SKILL.md` That repo holds more skills than these two. Ignore the rest — the collection is opinionated toward Effect and Cloudflare TypeScript work, and it vendors its own copies of Matt Pocock's skills. Only add another one when the user asks for it by name. **From `~/workspace/random/cursor-plugins/pstack/skills/`:** - `unslop/SKILL.md` → `superpowers/skills/unslop/SKILL.md` (manual merge — the plugin copy carries four locally added patterns and a local method) `cursor/plugins` is a monorepo of Cursor plugins, and `pstack` alone ships around forty skills (the `principle-*` family, `tdd`, `architect`, `why`, `swarm`, and more), plus other plugins at the repo root. Only `unslop` is tracked. Ignore everything else unless the user asks for a specific skill by name. **Plugin-specific skills with no upstream — never touch these during sync:** - `using-live-documentation`, `self-maintaining-claude-md`, `using-antigravity`, `agent-communication`, `financial-summary`, `using-code-directives`, `mermaid-validation`, `show-markdown` ## Step 3 — Identify what actually changed For each repo, use the git pull output to find the old and new commits, then diff against the tracked surface area: ```bash cd ~/workspace/random/superpowers git diff <old>..<new> -- skills/systematic-debugging/ ``` Only analyze files that are **both** in the pull output **and** in our tracked list. If nothing tracked changed for a repo, say so and skip it. ## Step 4 — Present a high-level summary Show the user a summary, not line-by-line diffs. For each affected tracked file, mention: - The skill/command name and its source repo - The general nature of upstream changes (e.g. "content updates", "new section added", "rename") - Whether this plugin has customizations on top that need manual merging Plugin-side customizations to be aware of: - **All skills**: use the `superpowers:` namespace prefix for any cross-skill reference - **systematic-debugging**: removed references to skills not bundled here (`defense-in-depth`, `condition-based-waiting`, `verification-before-completion`) - **agent-browser**: local-only `## Visible browser inside herdr` section plus two extra `allowed-tools` entries — always a manual merge, never a copy - **unslop**: six locally added patterns at the end of `### Plain speech` (34 to 39), local sentences added to upstream's 16 (slogan lead-ins) and 32 (artifacts that talk), a locally rewritten `## Process` and `## How to scan` (a two-round pass: the first round finds, the second verifies the first's fixes survived), a local `### Prompts` with a scan template and a verification template, plus a local frontmatter: no `disable-model-invocation` and a description scoped to document writing — always a manual merge, never a copy Suggested format: ``` === Skills with updates === systematic-debugging (from superpowers) Status: Has plugin customizations (removed skill references) Changes: Content updates in upstream version Action: Manual merge required to preserve simplified workflow ``` ## Step 5 — Confirm before applying Ask the user to approve. Surface which entries need manual merging vs straight copies so they know what they're approving: ``` Found differences in N items: - systematic-debugging (requires manual merge) - evolve-perf (direct copy) - ... Proceed with these updates? (yes/no) ``` ## Step 6 — Apply updates by item type Each item type has its own rule. Apply the right one and preserve the plugin's intent. ### Type 1 — Skills with minor customizations (currently: `systematic-debugging`) Copy the whole directory from upstream, then strip references to skills not bundled in this plugin (such as `verification-before-completion`). ```bash cp -r ~/workspace/random/superpowers/skills/systematic-debugging \ ~/workspace/asermax/claude-plugins/lesserpowers/skills/ ``` Re-apply the plugin-side edits afterwards. Read the file end-to-end and remove any lingering cross-skill references to things this plugin doesn't ship. ### Type 2 — Plugin-specific skills Skip entirely. They have no upstream. ### Type 3 — Haft skill catalog and context Direct copy, no plugin customization needed. v8 surfaces haft as a catalog of skills (one directory per skill), not slash commands. Mirror the whole catalog so newly-added skills land and removed ones are dropped, then refresh the context and clear the cached binary. ```bash SRC=~/workspace/random/quint-code DST=~/workspace/asermax/claude-plugins/haft # Mirror the full skill catalog (adds new skills, drops removed ones) rm -rf "$DST/skills" for d in "$SRC"/internal/cli/skill/*/; do name=$(basename "$d") mkdir -p "$DST/skills/$name" cp "$d/SKILL.md" "$DST/skills/$name/SKILL.md" done # If a haft/commands/ directory still exists from a pre-v8 layout, remove it rm -rf "$DST/commands" cp "$SRC/CLAUDE.md" "$DST/context/PRINCIPLES.md" rm -f "$DST/bin/haft" ``` The skill SKILL.md files reference MCP tools via `allowed-tools: mcp__haft__haft_*`; the `.mcp.json` server key `haft` matches that namespace, so no rewriting is needed. Manual-only skills carry `disable-model-invocation: true` — preserve it verbatim. Deleting `haft/bin/haft` is intentional — the SessionStart hook (`haft/hooks/session-init.sh`) rebuilds it on next launch from cached source in `~/.cache/claude-plugins/haft/`. ### Type 4 — Agentic-evolve commands Direct copy of all four files. ```bash cp ~/workspace/random/agentic-evolve/.claude/commands/evolve.md \ ~/workspace/asermax/claude-plugins/lesserpowers/commands/evolve.md cp ~/workspace/random/agentic-evolve/.claude/commands/evolve-perf.md \ ~/workspace/asermax/claude-plugins/lesserpowers/commands/evolve-perf.md cp ~/workspace/random/agentic-evolve/.claude/commands/evolve-size.md \ ~/workspace/asermax/claude-plugins/lesserpowers/commands/evolve-size.md cp ~/workspace/random/agentic-evolve/.claude/commands/evolve-ml.md \ ~/workspace/asermax/claude-plugins/lesserpowers/commands/evolve-ml.md ``` `evolve.md` is a master dispatcher; the other three are mode-specific subskills it routes to. ### Type 5 — Agent-browser skill (slim stub) Upstream is now a discovery stub that calls `agent-browser skills get core` at runtime for the full workflow content. Sync only `SKILL.md` and remove any leftover supporting directories from earlier sync runs. ```bash rm -rf ~/workspace/asermax/claude-plugins/superpowers/skills/agent-browser/references \ ~/workspace/asermax/claude-plugins/superpowers/skills/agent-browser/templates ``` **This one is a manual merge, not a copy.** The plugin file carries a local-only `## Visible browser inside herdr` section that does not exist upstream, so a straight `cp` deletes it. Diff upstream against the plugin copy, port whatever upstream changed, and leave that section standing. Also keep `Bash(herdr plugin:*)` and `Bash(bun run:*)` in `allowed-tools` — the section needs both and upstream declares neither. ```bash diff ~/workspace/random/agent-browser/skills/agent-browser/SKILL.md \ ~/workspace/asermax/claude-plugins/superpowers/skills/agent-browser/SKILL.md ``` ### Type 6 — `bro` and `herdr` (dmmulroy) Direct copy, verbatim. Neither skill references another skill, so the `superpowers:` prefix rule has nothing to apply to, and neither ships supporting files. ```bash SRC=~/workspace/random/dmmulroy-skills DST=~/workspace/asermax/claude-plugins/superpowers/skills cp "$SRC/bro/SKILL.md" "$DST/bro/SKILL.md" cp "$SRC/herdr/SKILL.md" "$DST/herdr/SKILL.md" ``` Two things to leave alone: - **Upstream typos in the `herdr` description** ("terminl", "requies", "another skills"). Copy them as-is. Fixing them locally turns every future sync into a manual merge, and the description still routes correctly. - **`disable-model-invocation: true` on `bro`.** It is a restate-my-last-message command, so it must only ever fire when the user types `/superpowers:bro`. `herdr` overlaps with the "Visible browser inside herdr" section in `agent-browser`, but they do different jobs: `agent-browser` drives the `official.browser` plugin pane, `herdr` drives panes, tabs and sibling agents. Do not merge them or add cross-references between them. ### Type 7 — `unslop` (cursor-plugins) **This one is a manual merge, not a copy.** The plugin file carries six patterns, two extended upstream rules, a method and a frontmatter that do not exist upstream, so a straight `cp` deletes all of them. Diff first, port whatever upstream changed, and leave the local blocks standing. ```bash diff ~/workspace/random/cursor-plugins/pstack/skills/unslop/SKILL.md \ ~/workspace/asermax/claude-plugins/superpowers/skills/unslop/SKILL.md ``` The six local patterns sit at the end of the `### Plain speech` section, after upstream's own 32 (Mannered prose) and 33 (Over-compression): - **34. Describing the message instead of writing it** — spans that refer to the text (its parts, their count, their order, that something is arriving) rather than to the subject, at any position in a sentence, plus headings that count items rather than naming them. Upstream has no equivalent. - **35. Restating what you just said** — a second pass over an idea at the same level of detail, adding nothing. Upstream's 16 covers one narrow instance of it (a bold lead restating its own line), so check whether upstream has widened 16 before assuming 35 is still needed. - **36. Pronoun referent overload** — the same pronoun standing for two different things in one sentence, or a dropped relative pronoun whose wrong attachment is the easier parse; fixed by naming the referent or restoring the "that". Upstream's 28 has the backtrack test that finds these sentences but its split-the-sentence fix cannot repair them, so check whether upstream has widened 28 before assuming 36 is still needed. - **37. Negation where a positive fits** — double negatives and "not about" framing; state the fact instead. - **38. Actions turned into nouns** — an event written as a noun phrase hung on a weak verb; write the clause with its actor and its verb. - **39. "What" clauses that withhold the content** — a clause such as "what a thing is" or "what flows" that points at information without giving it; replace it with the content or an example. Upstream has no equivalent. Two upstream rules carry a local sentence. 16 adds that a slogan lead-in ("**Shapes say what a thing is.**") falls outside its exemption for bold lead-ins, and 32 adds artifacts that talk (a shape, label or test that "says" or "shows" something to state a rule) next to personified code. When upstream rewrites either rule, take upstream's wording and add the local sentence back; when upstream's wording already covers it, drop the local sentence and tell the user. 34, 35, 36 and 38 mirror the `# Writing style` section of the user's global `~/.claude/CLAUDE.md`, so they should move together. If upstream ever grows its own version of one, drop the local copy and keep upstream's, then tell the user so they can align that section. This already happened once: a local "Mannered prose" pattern was retired in 2026-09 when upstream added its own 32 with the same intent. Two more local blocks sit above the patterns. `## Process` is rewritten: upstream's three steps are scan, rewrite and self-audit, while the local one runs rounds, each one a fresh opus agent over every document in the pass, verified and applied before the next starts. `## How to scan` follows it and has no upstream counterpart at all; it carries the round loop, the agent prompt and the between-rounds verification. An earlier local version of that section split the rules into an inline set and four subagent sweeps; it was replaced in 2026-09 because the sweeps asked about surface features and missed the sentences that restate or justify. If upstream ever adds a method section of its own, keep the local one and tell the user. The three local patterns, with that marketplace's own numbering, live in the Filadd marketplace's `plugins/docs/skills/unslop/SKILL.md` (its 30, 31 and 32 mirror the local 34, 35 and 36); a rule change here is a change there too. The two method blocks live in `plugins/docs/skills/doc-writing/SKILL.md` under `## Unslop Pass`; that copy repeats full-scan rounds until one finds nothing, where the local one runs two rounds and makes the second a verification of the first, so the methods differ and a change to one is a decision about the other. Numbering is the thing most likely to collide. Upstream treats rule numbers as stable ids (removed rules leave gaps, they are never renumbered), so if upstream appends items the local patterns must be renumbered to stay last. Cross-references ride on that numbering and have to be repointed when a target moves: 35 refers to 16, 36 refers to 28, and `## How to scan` names the passive rule in its exclusions. Read the merged file end-to-end and check all of it. The frontmatter is local too. Upstream sets `disable-model-invocation: true` and describes the skill as `Must always apply.`; the plugin copy drops the flag and scopes the description to document writing (documentation, READMEs, design notes, specs, PR descriptions, and "when another skill asks for a writing pass"). The reason is mahou's `write-documentation`, which invokes `superpowers:unslop` by name as its writing pass: with the flag set the model cannot call it, so the pass silently stops happening. The scoped description keeps it off code, chat replies and short answers, which is what upstream's flag was protecting against. On sync, port any description wording upstream changes but keep the flag out and the scope in. Everything else in the file is upstream's. ### Manual-merge procedure (used by Types 1, 5 and 7 when upstream changed) 1. Read upstream version end-to-end. 2. Read plugin version end-to-end. 3. Identify what changed conceptually in upstream (not just textually). 4. Edit the plugin version to incorporate those concepts while keeping the plugin-specific approach. 5. Verify the merged file preserves both the upstream improvement and the local customization. ## Step 7 — Confirm what landed Print a clear summary of what was updated and which customizations were preserved: ``` ✅ Plugins synced successfully: Lesserpowers: - systematic-debugging (adapted from superpowers, skill references removed) Haft: - skill catalog synced (12 skills: 11 auto-triggering + h-commission manual-only) - PRINCIPLES.md context updated from upstream CLAUDE.md - Cached MCP binary deleted (rebuilds on next session start) Agentic-Evolve: - evolve commands synced into lesserpowers (4 files: dispatcher + perf/size/ml) Agent-Browser: - agent-browser SKILL.md synced Dmmulroy-Skills: - bro, herdr synced into superpowers (verbatim) Cursor-Plugins: - unslop merged into superpowers (local patterns preserved) ⚠️ Plugin customizations preserved: - All skills: superpowers: namespace prefix applied