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 ofgithub.com/obra/superpowers) — core workflow skills (currently:systematic-debugging, which is mirrored into the lesserpowers plugin, not superpowers) - haft —
~/workspace/random/quint-code(clone ofgithub.com/m0n0x41d/quint-code; the local path still uses the oldquint-codename, the project itself is nowhaft) — 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 ofgithub.com/ericksoa/agentic-evolve) — evolve commands (master dispatcher + perf/size/ml subskills) - agent-browser —
~/workspace/random/agent-browser(clone ofgithub.com/vercel-labs/agent-browser) — browser automation CLI skill (slim discovery stub) - dmmulroy-skills —
~/workspace/random/dmmulroy-skills(clone ofgithub.com/dmmulroy/skills) — thebroandherdrskills, mirrored into superpowers - cursor-plugins —
~/workspace/random/cursor-plugins(clone ofgithub.com/cursor/plugins) — theunslopskill from thepstackplugin, mirrored into superpowers, and thestatechartskill from the same plugin, adapted into mahou as a spike strategy
High-level flow
- Pull latest from each upstream repo.
- Identify which tracked files actually changed.
- Summarize the changes for the user (high-level, not line-by-line).
- Confirm before applying anything.
- Apply updates with intelligent merging that preserves plugin customizations.
- 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.
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.mdfiles) → mirrored intolesserpowers/skills/
From ~/workspace/random/quint-code/:
internal/cli/skill/h-*/SKILL.md→ mirrored intohaft/skills/h-*/SKILL.md(the full v8 skill catalog — one directory per skill). As of v8 there are nointernal/cli/commands/files; the surface is skills only.CLAUDE.md→ mirrored intohaft/context/PRINCIPLES.md- And: delete the cached MCP binary at
haft/bin/haftso 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 intolesserpowers/commands/
From ~/workspace/random/agent-browser/skills/agent-browser/:
SKILL.mdonly. Upstream restructured this into a slim discovery stub that delegates toagent-browser skills get coreat runtime, so any oldreferences/ortemplates/directories under the plugin copy should be removed.
From ~/workspace/random/dmmulroy-skills/:
bro/SKILL.md→superpowers/skills/bro/SKILL.mdherdr/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)statechart/SKILL.md(andreferences/) →mahou/skills/spike/references/strategies/model-check.md(conceptual merge only — see Type 8)
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 and statechart are 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,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:
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 herdrsection plus two extraallowed-toolsentries — 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## Processand## How to scan(a two-round pass: the first round finds, the second verifies the first's fixes survived), a local### Promptswith a scan template and a verification template, plus a local frontmatter: nodisable-model-invocationand 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).
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.
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.
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.
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.
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.
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
herdrdescription ("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: trueonbro. 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.
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.
Type 8 — statechart → mahou's model-check strategy (cursor-plugins)
Never a copy, and not a line-by-line merge either. Upstream is a standalone skill with a bundled TypeScript command that installs TLC and Java through mise, runs TLC, and renders the chart with its own view module. The mahou file is one spike strategy in mahou's voice that keeps the method and drops all of that: TLC is found on the machine or installed with the user's consent, the chart is drawn by hand with superpowers:mermaid, and the user decides whether a broken rule is a bug or a wrong rule.
git -C ~/workspace/random/cursor-plugins diff <old>..<new> -- pstack/skills/statechart/SKILL.md pstack/skills/statechart/references/
Read upstream's diff for changes to the method: how rules become invariants, how Next is written, deadlock handling, how a broken rule is re-run, chart labelling and marks, the arrow budget, replaying paths against code. Port those into model-check.md in mahou's wording. Ignore changes to scripts/, upstream's mise-based install step, the --view module API and references/render.md (Pele CSS, SVG options); none of it exists on the mahou side. When an upstream change only makes sense with the bundled command, tell the user and skip it.
Manual-merge procedure (used by Types 1, 5 and 7 when upstream changed)
- Read upstream version end-to-end.
- Read plugin version end-to-end.
- Identify what changed conceptually in upstream (not just textually).
- Edit the plugin version to incorporate those concepts while keeping the plugin-specific approach.
- 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
- systematic-debugging: references to non-bundled skills removed
- agent-browser: "Visible browser inside herdr" section kept
- unslop: local patterns 34 to 39 kept, local sentences in 16 and 32 kept, local `## Process` and `## How to scan` kept, model invocation kept on with the document-scoped description
Error handling
- Upstream repo missing: report the expected path and stop.
git pullfails: show the error, suggest manual resolution, stop. Don't try to recover automatically — the user might have local changes upstream you'd lose.- Permission issues: report and suggest fixes.
- Nothing tracked changed: tell the user everything is already in sync.
- Manual merge ambiguous: ask the user how they'd like it resolved rather than guessing.
What never to do
- Don't lose plugin customizations. The simplified workflows and namespace prefixes are deliberate.
- Don't show line-by-line diffs in the summary. It's too noisy and obscures what actually matters.
- Don't skip the confirmation step. Even when changes look harmless, the user is the one who knows whether they want the merge now.
- Don't blindly overwrite a file with plugin customizations without re-applying them.