Why AWaC
Anyone using AI coding agents seriously hits two walls: drift (rules that diverge across projects within weeks) and bloat (every workspace ending up as a 200-file .agents/ no one owns). AWaC solves both with versioned stacks + a declarative manifest + deterministic composition.
One file describes the workspace
A workspace.yml lists the stacks. The CLI resolves them, clones the repos they declare, composes .agents/{rules,skills,workflows}/, and writes CLAUDE.md + AGENTS.md. Lockfile makes it reproducible.
Agent-first by design
Every command emits machine-readable output. Errors are code + category + cause + remediation so AI agents can react programmatically. The CLI ships embedded wsp guide <topic> so an agent in a fresh dir can self-orient before acting.
100% local, no SaaS
Stacks live in plain GitHub repos. The CLI is pipx-installable. No backend, no telemetry. MIT licensed — fork it, vendor it, embed it.
The fastest path: open Claude Code, Cursor, Aider, or any agent CLI in an empty folder, and paste these two lines into the chat. Your agent does the rest.
Install AWaC if not present (see https://github.com/getGanemo/workspace-cli-oss/releases/latest), then run `awac guide quickstart` and follow it step by step.That’s it. The CLI ships an embedded quickstart guide that tells the agent how to install/upgrade itself, self-orient, ask you the right questions (workspace name + template), scaffold, and report. No long prompt to copy.
If you’re on v1.2.x and can’t upgrade yet, paste this entire block into your agent’s chat instead:
You are an AI coding agent. Set up an AWaC workspace in this folder.
AWaC ("Agent Workspace as Code") is a Terraform-style tool: a `workspace.yml`manifest declares which versioned "stack" repos compose into this workspace's`.agents/` folder + `CLAUDE.md` + `AGENTS.md`. The CLI binary is named `wsp`(also installed as `awac` from v1.2.0+). Public repo:https://github.com/getGanemo/workspace-cli-oss
Required CLI version: 1.2.0 or later.
Step 1 — Detect CLI state (DO NOT install or upgrade yet, just probe): awac --version 2>/dev/null || python -m wsp --version 2>/dev/null \ || echo "NOT_INSTALLED"
Three branches: a) Output starts with "wsp," or "awac," AND version >= 1.2.0 → already installed and current. SKIP to Step 2. b) Output starts with "wsp," or "awac," AND version < 1.2.0 → installed but outdated. Upgrade with: gh release download --repo getGanemo/workspace-cli-oss \ --pattern '*.whl' --dir /tmp/wsp pipx install --force /tmp/wsp/wsp-*.whl Then continue to Step 2. c) Output is "NOT_INSTALLED" (or command failed) → install with: gh release download --repo getGanemo/workspace-cli-oss \ --pattern '*.whl' --dir /tmp/wsp pipx install /tmp/wsp/wsp-*.whl (If `gh` is not installed, fall back to plain `pip install` from the wheel URL at https://github.com/getGanemo/workspace-cli-oss/releases/latest) Then continue to Step 2.
Step 2 — Self-orient. Run BEFORE doing anything else: awac guide discover awac guide init awac templates --json
Step 3 — Ask me, do not infer: - The workspace name (kebab-case lowercase). - Which template I want. Read out the available templates from `awac templates --json` and show me which are "product templates" (the ones flagged `requires_confirmation: true` — those clone product repos and embed me in a product-specific deploy/secrets flow). - DO NOT infer the template from the folder name. Folder prefixes are coincidence; templates carry semantic blast radius. If unclear, default to `blank`.
Step 4 — Once I confirm name + template: awac init <name> --template <T> # add --yes only if template is # product-specific AND I confirmed # in this turn cd <name> awac bootstrap
Step 5 — If template was product-specific, after bootstrap run: awac secrets check <product> # validates my local vault awac deploy <product> # plan-only
Step 6 — Report what got created (file count, .agents/ tree summary, anymissing secrets) and stop. Do not start writing product code.
Rules:- The CLI emits structured JSON errors. Parse `code` + `remediation` and follow the remediation; do not improvise around errors.- Never edit files under `.stack/<product>/` directly — that's a read-only mirror of the product stack. For per-workspace variation, edit `workspace.yml#deploy_overrides` or `#devvault_overrides`.- Never push or commit anything I haven't asked for.- If your org has its own governance doc, set `WSP_GOVERNANCE_DOC=<url>` before running scaffold-repo / scaffold-stack so seed READMEs reference it instead of the AWaC public default.After paste, the agent will install + self-orient + ask you the two questions (name, template) before scaffolding. If your agent skips a step or infers a template without asking, that’s a bug — send us a GitHub issue with the transcript.
If you prefer to run the commands yourself:
# 1. Install latest release (v1.1.0+)TAG=$(gh release view --repo getGanemo/workspace-cli-oss --json tagName -q .tagName)gh release download "$TAG" --repo getGanemo/workspace-cli-oss --pattern '*.whl' --dir /tmp/wsppipx install /tmp/wsp/wsp-*.whl
# 2. Verifywsp --versionwsp guide init # read the path before acting
# 3. Compose a workspacewsp init my-feature --template blankcd my-featurewsp bootstrapwsp command, every flag.deploy.yml, devvault.yml, workspace overrides.