---
name: clean-workflow
description: Strip a federated module's deployed artifacts from the bonded fiddle — removes ext directory, drops META-INF/federation entries from jars, and removes typings from <fiddle>/admin/.federation/. Wraps the `ws-clean` bin.
when_to_use: Activates when undeploying a module, switching a module from one deploy target to another (jar↔ext), preparing to re-ship clean, debugging stale artifacts, or when the user types `npx ws-clean` / says "clean module <name>", "strip the deployed jar entries", "remove ext deploy".
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
---

Language: English only.

This skill is used to remove deployed federation artifacts for one or more modules via `ws-clean`. Inverse of [ship-workflow](../ship-workflow/SKILL.md). Three modes: clean by name (resolves the project's deploy target), clean by mode-filter (`--kind jar` or `--kind ext`), or clean a specific jar by path (`ws-clean jar <pathtojar>`).

## When this skill applies

- "undeploy this module"
- "strip the deployed jar entries for `<name>`"
- "remove the ext deploy of `<name>`"
- "clean this module before re-shipping"
- Switching deploy target (jar → ext or vice versa): clean the old artifact first
- User runs `npx ws-clean` or `npx ws-clean jar <path>`

## How it works

Entry point: `/Users/ph/projects/ws-admin-aux/admin-kit/bin/ws-clean.js`. Implementation: `/Users/ph/projects/ws-admin-aux/admin-kit/lib/clean-remotes.js`, `/Users/ph/projects/ws-admin-aux/admin-kit/lib/clean-jar.js`.

Per project (when called without `jar <path>`):

1. Resolves the project's target via `resolveTarget()` (`<workspace>/wsconfig.json` → `wpmRoot` + project's `wsmodules.target` setting).
2. **ext target** → `rm -rf <fiddle>/scripts/ext-admin-remotes/<id>/`.
3. **jar target** → opens the jar with `adm-zip`, drops every entry matching `^META-INF/federation/<id>/`, re-packs the jar without those entries.
4. Removes typings dir: `rm -rf <fiddle>/admin/.federation/<id>/`.

Specific-jar mode (`jar <path>`) drops EVERY `META-INF/federation/<*>/` entry from the given jar regardless of which workspace owns it.

Usage:

```
npx ws-clean                              # clean all projects in workspace (rare)
npx ws-clean <name>                       # clean one project by name (preferred)
npx ws-clean --kind jar                   # filter: only jar-targeted projects
npx ws-clean --kind ext                   # filter: only ext-targeted projects
npx ws-clean jar /path/to/some.jar        # escape hatch: strip a specific jar by path
```

A deprecated `ws-purge` alias exists and delegates to `ws-clean` with a warning.

## Behavior contract (the agent MUST follow this when this skill is active)

- **Announce on load (MUST).** The first time this skill informs a response in a session, begin that response with the line `🧩 skill: clean-workflow` (combine as `🧩 skills: a, b` when several load together). Once per skill per session — it's a load marker, not a summary; do not repeat it on later turns.
- MUST resolve scope before invoking — prefer targeted (`<name>` argument) over a global clean.
- MUST verify the workspace is bonded (`wsconfig.json` exists) before invoking.
- MUST warn the user when cleaning a project that consumer modules currently depend on at runtime — the consumers will fail to load until re-shipped.
- MUST recommend running `ws-clean` before switching a project's deploy target (jar → ext or vice versa) to prevent the stale-shadow issue.
- MUST NOT mass-clean (no `<name>` arg) without confirming — it strips every project in the workspace.

## Common pitfalls

- **Cleaning AFTER dropping a module locally.** [drop-module](../drop-module/SKILL.md) removes the source but not the deployed artifact. Run `ws-clean <name>` BEFORE drop OR right after, otherwise the host still tries to load a phantom remote.
- **Cleaning the wrong target.** `ws-clean <name>` resolves the project's CURRENT target setting. If the previous deploy was a different target (e.g. project was `ext`, was redeployed as `jar`), only the current target gets cleaned; the old artifact lingers. Solution: explicitly clean both — `ws-clean --kind jar <name>` then `ws-clean --kind ext <name>`, or use the escape hatch.
- **Cleaning a jar that lives elsewhere.** `<fiddle>/modules/*.jar` is the default scope; if a federation-contribution-carrying jar is referenced from a different path, use `ws-clean jar <pathtojar>`.
- **No effect.** If the project never deployed (or was just generated and never shipped), clean is a no-op. The bin reports "(nothing cleaned)".

## Out of scope

- This skill does NOT remove the project source — see [drop-module](../drop-module/SKILL.md).
- Does NOT touch `<fiddle>/modules.json.adminModules` — the fiddle operator manages that.
- Does NOT clean the host SPA or controller artifacts — those are `wpm admin --clean` concerns.

## Cross-links

- [ship-workflow/SKILL.md](../ship-workflow/SKILL.md) — re-deploy after clean
- [drop-module/SKILL.md](../drop-module/SKILL.md) — remove source after clean
- [wire-setup-modules/SKILL.md](../wire-setup-modules/SKILL.md) — `--force` mode does clean-then-deploy per project
- the `federation-error-catalogue` skill — entry #3 (jar shadowed by ext)