---
name: workspace-init
description: Initializes a fresh admin-modules workspace in the current directory by overlaying admin-kit's template (package.json + angular.json + tsconfig + scripts), running npm install, and optionally bonding to a fiddle via --wpm-root. Wraps the `ws-init-workspace` bin.
when_to_use: Activates when bootstrapping a brand-new admin-modules workspace, when the user runs `npx ws-init-workspace`, or asks "scaffold a workspace", "start a new admin-modules project", "set up workspace for federated remotes".
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
---

Language: English only.

This skill is used to scaffold a new admin-modules workspace using `ws-init-workspace`. The bin overlays admin-kit's template onto an empty (or near-empty) directory, merges package.json fields, runs `npm install`, and optionally wires `wsconfig.json` + `tsconfig.federation.json` if a fiddle root was provided.

## When this skill applies

- "scaffold a new admin-modules workspace"
- "start a new federated admin project"
- Running `npx ws-init-workspace` (with or without `--wpm-root`)
- Empty directory + the user wants to add federated remotes

## How it works

Entry point: `/Users/ph/projects/ws-admin-aux/admin-kit/bin/ws-init-workspace.js`. Implementation: `/Users/ph/projects/ws-admin-aux/admin-kit/lib/init-workspace.js` (and the template tree under `admin-kit/template/`).

Steps the bin performs (per the file's header comment):

1. **Refuse if `angular.json` already exists** in PWD — never clobber an existing workspace.
2. **If no `package.json`**, run `npm init -y` to create a minimal one.
3. **Merge `template/package.json` fields** into PWD's package.json. Field conflicts (existing scripts/deps with different values than the template's) cause an abort with a report — the user resolves manually and re-runs.
4. **Copy the rest of `template/`** (angular.json, tsconfig.json, prettier ref, etc.) — skips files that already exist.
5. **Run `npm install`** to materialize the merged deps.
6. **If `--wpm-root <path>` was passed**, also writes `wsconfig.json` ({wpmRoot, hostId}) + regenerates `tsconfig.federation.json` + creates cross-workspace symlinks. Equivalent to running `ws-wire-host <fiddle>` after the scaffold.

Usage:

```
npx ws-init-workspace                              # scaffold only; bond later via ws-wire-host
npx ws-init-workspace --wpm-root /path/to/fiddle   # scaffold + bond in one go
npx ws-init-workspace --wpm-root /path/to/fiddle --host-id admin
```

## 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: workspace-init` (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 run `npx --yes -p @wiresphere/admin-kit ws-init-workspace ...` from the empty target directory (not from a parent).
- MUST inspect the target directory beforehand — if `angular.json` exists, do NOT proceed; report the existing workspace and ask the user how to handle it (start fresh elsewhere, or use [wire-host](../wire-host/SKILL.md) on the existing one).
- MUST surface any merge conflict report from the bin verbatim and pause for user resolution; the bin aborts in this case by design.
- MUST NOT pre-create `package.json` before running the bin — the bin handles the `npm init` step itself when needed.
- MUST NOT auto-bond to a fiddle without `--wpm-root` from the user — bonding is an explicit choice (see [wire-host](../wire-host/SKILL.md) for the post-hoc path).

## Common pitfalls

- **Existing `angular.json` blocks init.** This is intentional — the bin refuses to overwrite. If the user wants to convert an existing project, that's a different workflow (currently manual).
- **Merge conflict abort.** Means the target's existing package.json has scripts/deps that differ from the template. Common when a project's been hand-edited. Resolution is manual: align the field or remove it, then re-run.
- **`npm install` failure after merge.** Usually a transitive resolution issue (incompatible version pin) — read the npm error, fix the offending dep, re-run from scratch on a fresh dir.
- **Forgetting `--wpm-root`.** Workspace scaffolds fine but `npm run ship` won't have anywhere to deploy to. Run [wire-host](../wire-host/SKILL.md) after the fact.

## Out of scope

- This skill does NOT generate the FIRST module — that's [generate-module](../generate-module/SKILL.md), invoked separately after the workspace is initialized.
- Does NOT migrate legacy moodia-schematics workspaces into the federation format. Manual migration only.
- Does NOT clone module repos. That's `wpm install`'s concern, run from inside a fiddle, not the workspace.

## Cross-links

- [generate-module/SKILL.md](../generate-module/SKILL.md) — scaffold first module after init
- [wire-host/SKILL.md](../wire-host/SKILL.md) — bond to a fiddle post-init
- [ship-workflow/SKILL.md](../ship-workflow/SKILL.md) — what `npm run ship` does once a module exists