User scenarios
Workflow guides for the current HarnessTap CLI, grouped by usage frequency.
This document reflects the current shipped CLI. Each scenario links to a detail page with typical commands.
Orientation
- Machine-wide setup:
init,profile use,harness set(Scenarios 1, 2, 36) - Repo adoption:
scan,apply,mirror(Scenarios 4, 7, 27) - Plugin curation:
plugin create,plugin edit,plugin doctor,add(Scenarios 5, 23, 35) - Plugin pins:
resource sync,plugin show,apply --strict-plugin-versions(Scenarios 8, 16) - Repo profiles:
config show,ht use(Scenario 40) - Sharing:
migrate export/import,plugin pull/plugin publish(Scenarios 10, 28)
See the VHS demo pack for rendered walkthroughs of the covered workflows.
Usage frequency
Frequency describes how often a typical active user reaches for a scenario after HarnessTap is set up — not how important it is the first time.
| Frequency | Meaning |
|---|---|
| Common | Regular per-repo work: onboarding, adoption, repo-specific prefs, applying plugins |
| Occasional | Setup, customization, sharing, maintenance, automation, CI integration |
| Rare | Edge cases, team-only constraints, debugging, or recovery after a mistake |
| Scenario | Title | Frequency | Status |
|---|---|---|---|
| 7 | Preview and apply a plugin | Common | Shipped |
| 11 | Start from a catalog baseline | Common | Shipped |
| 4 | Scan and import an existing repo | Common | Shipped |
| 35 | Add a remote skill package | Common | Shipped |
| 38 | Create a plugin from a skill package | Common | Shipped |
| 31 | Import dual-mode plugin repo | Common | Shipped |
| 3 | Override harness preferences for one repository | Common | Shipped |
| 15 | Apply to a subset of target platforms | Common | Shipped |
| 25 | Stack multiple plugins | Common | Shipped |
| 26 | Turn a project's current state into a plugin | Common | Shipped |
| 27 | True cross-harness mirror | Common | Shipped |
| 36 | Switch global profile presets | Common | Shipped |
| 40 | Switch repo profiles from apm.yml | Common | Shipped |
| 1 | Bootstrap HarnessTap on a machine | Occasional | Shipped |
| 2 | Choose a default main harness and aliases | Occasional | Shipped |
| 5 | Build a reusable plugin from imported resources | Occasional | Shipped |
| 8 | Audit plugin resources and plugin pins | Occasional | Shipped |
| 10 | Export or import a plugin bundle | Occasional | Shipped |
| 12 | Drive HarnessTap from scripts or agents | Occasional | Shipped |
| 13 | Choose a materialization strategy (symlink vs copy) | Occasional | Shipped |
| 16 | Enforce plugin and plugin state in CI | Occasional | Shipped |
| 19 | Sync plugin resources from install trees | Occasional | Shipped |
| 20 | Inspect supported platforms before targeting | Occasional | Shipped |
| 21 | Detect drift between project and last applied plugin | Occasional | Shipped |
| 22 | Diff two plugins | Occasional | Shipped |
| 23 | Doctor-check a plugin without writing | Occasional | Shipped |
| 24 | Apply a plugin directly from a URL | Occasional | Shipped |
| 37 | Publish a profile plugin to the catalog | Occasional | Shipped |
| 32 | Apply to instruction-tier harnesses | Occasional | Shipped |
| 33 | Mirror with plugin-source fallback | Occasional | Shipped |
| 34 | Understand portability limits | Occasional | Shipped |
| 39 | Switch MCP tokens via environments; OAuth limits | Occasional | Documented |
| 6 | Add plugin constraints to a plugin | Rare | Shipped |
| 9 | Review history and recover from a bad apply | Rare | Shipped |
| 14 | Curate and clean up the local resource DB | Rare | Shipped |
| 17 | Migrate HarnessTap state to a new machine | Rare | Shipped (manual) |
| 18 | Debug committed vs effective Claude plugin settings | Rare | Shipped |
| 28 | Share workspace offline with migrate export/import | Occasional | Shipped |
Status legend
- Shipped — the commands shown in the scenario exist in the current CLI.
- Documented — workflow is documented with known product limits (see the scenario detail page).
- Shipped (manual) — achievable today with current commands but as a multi-step workflow (see Scenario 17 vs 28).
Common
Use these when starting or adopting a repository, applying a plugin, or when one repo needs different harness defaults than your machine-wide setup.
| Scenario | Summary |
|---|---|
| 7 | Preview and apply a plugin to one or more target harnesses |
| 11 | Start from a catalog baseline instead of building from scratch |
| 4 | Scan an existing repository and import its current harness setup |
| 35 | Add a remote skill package |
| 38 | Create a plugin from a skill package |
| 31 | Import a repo with both harness files and plugin-source layout |
| 3 | Override harness preferences for one repository |
| 15 | Apply a plugin to a subset of target platforms |
| 25 | Stack multiple plugins in one apply |
| 26 | Turn a project's current state into a plugin |
| 27 | True cross-harness mirror |
| 36 | Switch global profile presets on the machine |
| 40 | Switch repo profiles from apm.yml |
Occasional
Reach for these during initial setup, when curating plugins, when sharing baselines, or when integrating HarnessTap into tooling.
| Scenario | Summary |
|---|---|
| 1 | Bootstrap HarnessTap on a machine and discover existing defaults |
| 2 | Choose a default main harness and alias harnesses |
| 5 | Build a reusable plugin from imported resources |
| 8 | Audit plugin resources and plugin pins |
| 10 | Export or import a plugin as a portable bundle |
| 12 | Drive HarnessTap from scripts or other agents |
| 13 | Choose a materialization strategy (symlink vs copy) |
| 16 | Enforce plugin and plugin state in CI |
| 19 | Sync plugin resources from install trees |
| 20 | Inspect supported platforms before targeting |
| 21 | Detect drift between project files and the last applied plugin |
| 22 | Diff two plugins (or a plugin vs an imported bundle) |
| 23 | Doctor-check a plugin without writing to disk |
| 24 | Apply a plugin directly from a URL |
| 28 | Share a full workspace offline with migrate export/import |
| 37 | Publish and install profile-tagged catalog plugins |
| 32 | Apply plugins to instruction-tier harnesses (windsurf, cline, copilot, …) |
| 33 | Mirror alias harnesses when main harness tree is empty |
| 34 | Review what transfers across harnesses and what does not |
| 39 | Switch MCP tokens via environments; OAuth host limits (Documented) |
Rare
These matter when requirements are strict, when something went wrong, or when maintaining the local DB after a lot of activity.