salvage

Start over, simpler — without losing what you learned.

A Claude Code plugin for the moment a project has gone down a bad path: the wrong tech stack, over-engineered for what it actually needs, or built on requirements that turned out to be incomplete. Instead of fighting the existing code, salvage recovers the real requirements — now that you know more — and writes a portable spec to rebuild on the simplest stack you can actually maintain. A fresh agent then implements that spec in a clean project.

It is the inverse of the handoff plugin. handoff says "continue this work." salvage says "this approach failed — keep the intent, drop the decisions."

salvage produces documents only. It does not scaffold or generate code in the broken project. The recovered spec is the product; building from it happens later, in a fresh repo.

The three-act lifecycle

salvage runs across two repositories, with you moving a bundle between them.

1. Act 1 — in the broken project (/salvage). A four-stage interview:

   • Intake — what the app is supposed to do, what fought you, and your maintenance ceiling (the tools you can actually own — a hard cap on the stack).
   • Code archaeology — read the existing code to separate genuine behavior to keep from incidental tech decisions to drop.
   • Architecture interview — choose the stack one fork at a time, starting at the simplest rung and climbing only when a stated requirement forces it.
   • Emit the bundle — write a self-contained salvage/ bundle to the project root.

   Stages 1–3 only read and ask. Nothing is written until the final stage, and nothing is written into a new project yet.

2. Act 2 — the move. You create a clean, empty git repo and drop the salvage/ bundle into it.

3. Act 3 — in the new project (accept). The salvage-project skill auto-detects the bundle on session start (the way handoff detects HANDOFF.md), confirms before touching anything, writes the canonical project docs to the repo root, and transitions straight into the build.

The salvage interview is the brainstorming phase. By the time Act 1 finishes, the design is validated — so Act 3 does not re-brainstorm. It drops straight into planning and building.

Install

salvage is distributed as a Claude Code plugin through its own marketplace (this repo). Installation is two commands, run from inside Claude Code.

1. Add this repo as a marketplace:

/plugin marketplace add maludb/salvage-project

/plugin marketplace add also accepts a full git URL if you prefer:

/plugin marketplace add https://github.com/maludb/salvage-project.git

You may be reminded that plugins can run code on your machine — only install from sources you trust.

2. Install the plugin:

/plugin install salvage@salvage

The format is <plugin-name>@<marketplace-name> — both are salvage here (the plugin and its marketplace share the name).

Prefer a menu? Run /plugin to open the interactive interface — browse the Discover tab, select salvage, and install.

Verify

/plugin list

You should see salvage@salvage listed. Then confirm the command is live:

/salvage

Installed plugins are cached under ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ — here ~/.claude/plugins/cache/salvage/salvage/0.1.0/.

Update / uninstall

/plugin marketplace update salvage     # fetch the latest version
/plugin uninstall salvage@salvage      # remove it
/plugin disable salvage@salvage        # keep it installed but turn it off

Entry points

Once installed, there are two ways in:

• /salvage — the guided command. Run it inside the broken project to start Act 1.
• The salvage-project skill — natural-language triggerable. Saying things like "salvage this project", "start over simpler", or "rebuild this" invokes the same flow. The skill also runs automatically on session start to detect an existing bundle (Act 3).

Local development

To hack on salvage without going through GitHub, load it straight from a clone:

git clone https://github.com/maludb/salvage-project.git
claude --plugin-dir ./salvage-project        # loads the plugin for that session

Or add the local checkout as a marketplace and install from it:

/plugin marketplace add ./salvage-project
/plugin install salvage@salvage

After editing plugin files, run /reload-plugins to pick up the changes.

What's in the bundle

Act 1 writes a salvage/ directory containing six files:

The bundle is portable and agent-agnostic. In Act 3, requirements.md, tech-stack.md, design-notes.md, anti-patterns.md, and CLAUDE.md are copied out to the new repo's root; manifest.yaml stays in salvage/.

Relationship to superpowers

If the superpowers plugin is installed, Act 3 hands the bundle to its plan/execute workflow (writing-plans → executing-plans) for a structured build.

superpowers is an optional accelerator, never a hard dependency. If it isn't installed, the bundled CLAUDE.md carries a built-in fallback — build feature-by-feature from requirements.md, simplest-first, confirming each before moving on. The bundle stands alone with any agent.

How it's built

salvage/
├── .claude-plugin/plugin.json
├── commands/
│   └── salvage.md               # /salvage — runs Act 1
├── skills/
│   ├── salvage-project/         # the spine: salvage mode (Act 1) + accept mode (Act 3)
│   │   └── SKILL.md
│   └── simplicity-guide/        # bundled reference consulted during the architecture interview
│       ├── SKILL.md
│       └── references/          # data-store, frontend, realtime, auth, jobs, deploy
├── templates/
│   └── CLAUDE.md                # curated principles + project-specific slots
└── README.md

The salvage-project skill picks its mode by checking for salvage/manifest.yaml in the working directory: absent → Act 1 (recover and emit); present → Act 3 (accept and set up). The simplicity-guide skill supplies one reference file per architecture fork, each laid out as a ladder of rungs with Use when, Climb when, Cost, and a fill-in Rationale template.

License

MIT © Edward Honour