Use the wsp CLI

wsp is the AWaC CLI. It lives at getGanemo/workspace-cli and is installed via pipx install -e <path> (Python ≥ 3.10). Every Ganemo agent workspace was either created by wsp or is meant to be managed by it. Treat it as the only correct way to mutate workspace shape (stacks, product repos, .agents/, CLAUDE.md / AGENTS.md, lockfile).

When to use this skill

Always prefer the CLI over manually editing:

• .agents/{rules,skills,workflows}/ content (wsp sync regenerates it).
• workspace.yml (re-run wsp init against a fresh template if the scaffold drifted, or edit outside the auto-generated regions).
• workspace.lock.yml (auto-managed by wsp bootstrap / wsp sync).
• The header of CLAUDE.md / AGENTS.md (auto-regenerated; only edit between <!-- @awac:editable-start --> and <!-- @awac:editable-end -->).
• <org>/agent-stack/awac.yml#repos (use wsp scaffold-stack <org> --update).

When to skip this skill

• Pure code edits inside a product repo cloned in the workspace — that's normal git work, not workspace-level.
• Reading workspace files for context — no wsp involved.
• Running tests, linters, deploys, or anything that's not workspace shape mutation.
• One-off questions about how AWaC works conceptually — read the spec instead of running commands.

Decision flow when starting a task

1. Is there a workspace.yml at the cwd? If no → either we're outside a workspace, or the user wants to create one (use wsp init).
2. Is there a workspace.lock.yml? If no but workspace.yml exists → run wsp bootstrap first. Anything that needs the cache or the resolved stacks will fail otherwise.
3. Is the user asking about state? wsp status first, before assuming anything is in sync.
4. Is the user asking to refresh stacks (rules / skills / workflows updated upstream)? wsp sync. It does NOT touch product repos.
5. Is the user asking to refresh the lockfile (e.g., they want the latest commit of every product repo too)? wsp bootstrap (idempotent — safe to re-run).
6. Is the user touching awac.yml#org_scaffold or governance/product-structure.md? Run wsp governance check before pushing — same-PR rule means both must move together.

Idiomatic invocations

# New workspace from a template
wsp init my-acme-feature --template acme-feature
cd my-acme-feature
wsp bootstrap

# Daily refresh (after pulling stack updates upstream)
wsp sync

# Read-only inspection
wsp status
wsp status --json | jq '.summary'

# Seed a product's agent-stack from scratch (creates the repo on GitHub)
wsp scaffold-stack <org>

# Refresh an existing agent-stack via PR (no direct main push)
wsp scaffold-stack <org> --update

# Dry-run scaffold (no push, just print the seed dir)
wsp scaffold-stack <org> --no-push

# Sanity-check: env + governance mirror
wsp doctor
wsp governance check

All commands accept --json. Errors carry a stable code/category/cause/remediation shape — wsp --agent-manifest documents the catalog for agent consumption.

Configuration

• WSP_REGISTRY_REPO — defaults to getGanemo/agent-stack-core.
• WSP_REGISTRY_BRANCH — defaults to main.
• WSP_CACHE_DIR — defaults to ~/.wsp/cache. Stacks and registry get cached here. Read-only from the user's perspective — wsp does git reset --hard origin/<ref> on every refresh, so DO NOT edit cached stacks by hand. Edit the upstream stack repo and run wsp sync.

Anti-patterns

1. Hand-editing .agents/ and committing the change to the workspace. That edit gets blown away by the next wsp sync or wsp bootstrap. If the change should propagate to other workspaces, edit the corresponding stack repo (getGanemo/agent-stack-core for universal, getGanemo/agent-stack-<topic> for transversal-by-topic, <product>/agent-stack for product-specific). If the change should ONLY apply here, write it inside the <!-- @awac:editable-start --> block of CLAUDE.md.
2. Cloning product repos into the workspace by hand. wsp bootstrap does it. The lockfile records the exact commits.
3. Using git pull on product repos in the workspace to "update". Use wsp bootstrap — it pulls FF-only and doesn't pisa local changes.
4. Running wsp scaffold-stack against a product org WITHOUT --update if <org>/agent-stack already has content. It refuses (by design). Use --update to open a PR.
5. Skipping wsp governance check when changing either side of the mirror. The check is now in wsp doctor too — you'll catch it accidentally even if you forget.
6. Believing wsp sync is a substitute for wsp bootstrap. sync does NOT clone product repos. If a workspace has never been bootstrapped (no lockfile), bootstrap first.
7. Editing workspace.lock.yml by hand. It's auto-generated. Edit workspace.yml and re-run wsp bootstrap.
8. Inferring the workspace template from the folder name. The folder name is coincidence; templates have semantic impact (they clone real product repos, embed product flows, gate deploys). A folder called acme-billing/ does NOT imply the user wants the acme-feature template — they may want odoo-module instead. Always ASK the user (see the init_workspace workflow Step 2 and the discover_awac_in_fresh_workspace skill Step 4).
9. Editing .stack/<product>/{deploy,devvault}.yml to silence an error. Those files are read-only mirrors materialized by wsp bootstrap from the canonical in the stack repo. Your edit is gone on the next wsp sync. Edit the canonical, or use workspace.yml#deploy_overrides / workspace.yml#devvault_overrides.

Cross-references

• Source / install: getGanemo/workspace-cli
• Spec: https://gist.github.com/GanemoCorp/fdc1042067615003e8aa4a8406198a61
• Registry of stack shortcuts + templates + org_scaffold: getGanemo/agent-stack-core/awac.yml
• Governance (canonical, atemporal): getGanemo/docs-company/governance/product-structure.md
• Live audit per product: getGanemo/docs-company/governance/product-structure.audit.md

Discoverability for agents

wsp --agent-manifest returns a JSON catalog of every command, its required args, options, and the JSON keys each emits. Agents that don't already know the CLI can self-discover from that.