groundwork-method 0.0.1 → 0.11.0

package/src/generators/workspace-dev-cli/cli-src/src/util/runners.ts

@@ -0,0 +1,70 @@
+import * as fs from 'fs';
+import { CONFIG_PATH } from './paths';
+
+/** A declared native process the CLI manages directly — a surface app (Electron,
+ *  CLI, Flutter) or a native sidecar (a macOS-only Python service that can't be
+ *  containerized). Runners decouple "managed by ./dev" from "is a docker-compose
+ *  service": the lifecycle commands start/stop/tail/report them alongside Docker
+ *  infra and natively-run app services. Declared in `.dev/dev.config.json`. */
+export interface Runner {
+  /** Unique within the workspace; keys the runner's pid and log files. */
+  name: string;
+  /** Display/metadata only. */
+  kind?: 'sidecar' | 'surface';
+  /** Shell command to launch. Run via `bash -c` from `cwd`. */
+  cmd: string;
+  /** Working directory, relative to the repo root. */
+  cwd?: string;
+  /** Extra environment merged over the parent process env. */
+  env?: Record<string, string>;
+  /** Optional readiness probe. Carried but not enforced by `start` yet. */
+  health?: unknown;
+  /** Whether `./dev start` launches it (default true). `false` = registered and
+   *  reportable, but not part of the boot set (e.g. a CLI tool). */
+  autostart?: boolean;
+}
+
+/** Coerce a raw `runners` value (untrusted JSON) into validated Runner records.
+ *  Entries missing a string `name`/`cmd` are dropped rather than throwing, so a
+ *  malformed config degrades to fewer runners instead of breaking every command. */
+export function parseRunners(raw: unknown): Runner[] {
+  if (!Array.isArray(raw)) return [];
+  const out: Runner[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const r = item as Record<string, unknown>;
+    if (typeof r.name !== 'string' || typeof r.cmd !== 'string') continue;
+    out.push({
+      name: r.name,
+      kind: r.kind === 'surface' ? 'surface' : r.kind === 'sidecar' ? 'sidecar' : undefined,
+      cmd: r.cmd,
+      cwd: typeof r.cwd === 'string' ? r.cwd : undefined,
+      env:
+        r.env && typeof r.env === 'object' && !Array.isArray(r.env)
+          ? (r.env as Record<string, string>)
+          : undefined,
+      health: r.health ?? null,
+      autostart: r.autostart === false ? false : true,
+    });
+  }
+  return out;
+}
+
+/** Load runners straight from dev.config.json. Used where there is no Ctx
+ *  (e.g. service discovery in services.ts). Returns [] on any read/parse error. */
+export function loadRunners(): Runner[] {
+  try {
+    if (!fs.existsSync(CONFIG_PATH)) return [];
+    const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as { runners?: unknown };
+    return parseRunners(raw.runners);
+  } catch {
+    return [];
+  }
+}
+
+/** Names of every registered runner — the set of `services/` directories that
+ *  are managed as runners and must therefore be excluded from app-service
+ *  discovery so they are not double-managed or boot-detected by marker file. */
+export function runnerNames(): Set<string> {
+  return new Set(loadRunners().map((r) => r.name));
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/services.ts

@@ -0,0 +1,221 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { PID_DIR, SERVICES_DIR, pidFile } from './paths';
+import { capture, sleep } from './proc';
+import { runnerNames } from './runners';
+
+export type ServiceType = 'go' | 'node' | 'python' | 'unknown';
+
+let composeServicesCache: Set<string> | null | undefined;
+
+/** Compose membership, resolved once per process. `null` means the topology
+ *  could not be read (no docker CLI / no compose file) — callers fall back to
+ *  directory listing so the CLI still degrades gracefully without Docker. */
+function getComposeServices(): Set<string> | null {
+  if (composeServicesCache !== undefined) return composeServicesCache;
+  const r = capture('docker', ['compose', 'config', '--services']);
+  composeServicesCache =
+    r.status === 0
+      ? new Set(
+          r.stdout
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean),
+        )
+      : null;
+  return composeServicesCache;
+}
+
+/** App services are the subdirectories of `services/` that are wired into the
+ *  workspace docker-compose topology. Surface apps (mobile, desktop, CLI)
+ *  live under `services/` too but never join compose — they have their own
+ *  Nx targets and are excluded from backend lifecycle commands
+ *  (start/migrate/doctor would otherwise boot phantom backends and create
+ *  phantom databases for them). */
+export function getAppServices(): string[] {
+  if (!fs.existsSync(SERVICES_DIR)) return [];
+  const runners = runnerNames();
+  const dirs = fs
+    .readdirSync(SERVICES_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    // A dir registered as a runner is managed as a native runner, not an app
+    // service — exclude it from both the compose-readable and the fallback path
+    // so it is never double-managed or boot-detected by marker file.
+    .filter((d) => !runners.has(d))
+    .sort();
+  const compose = getComposeServices();
+  if (compose === null) return dirs;
+  return dirs.filter((d) => compose.has(d));
+}
+
+/** Infra services are compose services that are NOT app services. */
+export function getInfraServices(): string[] {
+  const app = new Set(getAppServices());
+  const r = capture('docker', ['compose', 'config', '--services']);
+  if (r.status !== 0) return [];
+  return r.stdout
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .filter((s) => !app.has(s));
+}
+
+export function serviceDir(svc: string): string {
+  return path.join(SERVICES_DIR, svc);
+}
+
+/** Detect a service's type by marker file. Precedence matches the bash CLI:
+ *  .air.toml (go) → package.json (node) → pyproject.toml (python). */
+export function detectType(svc: string): ServiceType {
+  const dir = serviceDir(svc);
+  if (fs.existsSync(path.join(dir, '.air.toml'))) return 'go';
+  if (fs.existsSync(path.join(dir, 'package.json'))) return 'node';
+  if (fs.existsSync(path.join(dir, 'pyproject.toml'))) return 'python';
+  return 'unknown';
+}
+
+/** Locate a Python service's pydantic Settings module (it carries `server_port`).
+ *  The package name is dynamic, so walk `src/` rather than assuming a fixed path. */
+function findPythonConfig(dir: string): string | null {
+  const src = path.join(dir, 'src');
+  if (!fs.existsSync(src)) return null;
+  const stack = [src];
+  while (stack.length > 0) {
+    const cur = stack.pop() as string;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = path.join(cur, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.name === 'config.py') return full;
+    }
+  }
+  return null;
+}
+
+/** Resolve a service's HTTP port from its language marker file. Go reads
+ *  `.env` (PORT/SERVER_PORT); Node reads `package.json` (`next dev --port`);
+ *  Python reads `server_port` from its Settings module. Returns null when the
+ *  port can't be determined (the caller renders this as an "unknown port" row). */
+export function servicePort(svc: string): number | null {
+  const dir = serviceDir(svc);
+  switch (detectType(svc)) {
+    case 'go': {
+      const env = path.join(dir, '.env');
+      if (fs.existsSync(env)) {
+        const m = fs.readFileSync(env, 'utf8').match(/^(?:PORT|SERVER_PORT)=(\d+)/m);
+        if (m) return parseInt(m[1], 10);
+      }
+      return null;
+    }
+    case 'node': {
+      const pkg = path.join(dir, 'package.json');
+      if (fs.existsSync(pkg)) {
+        const m = fs.readFileSync(pkg, 'utf8').match(/next dev --port (\d+)/);
+        if (m) return parseInt(m[1], 10);
+      }
+      return null;
+    }
+    case 'python': {
+      const cfg = findPythonConfig(dir);
+      if (cfg) {
+        const m = fs.readFileSync(cfg, 'utf8').match(/server_port:\s*int\s*=\s*(\d+)/);
+        if (m) return parseInt(m[1], 10);
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+/** A service's health endpoint path. Next.js/Node apps expose `/api/healthz`;
+ *  Go and Python services expose `/health`. */
+export function serviceHealthPath(svc: string): string {
+  return detectType(svc) === 'node' ? '/api/healthz' : '/health';
+}
+
+/** The boot command for a service, faithful to the bash CLI. */
+export function bootCommand(svc: string): string | null {
+  const dir = serviceDir(svc);
+  switch (detectType(svc)) {
+    case 'go':
+      return `cd ${JSON.stringify(dir)} && air`;
+    case 'node':
+      return `cd ${JSON.stringify(dir)} && ([ -d node_modules ] || npm install --legacy-peer-deps) && npm run dev`;
+    case 'python':
+      return `cd ${JSON.stringify(dir)} && uv run python src/main.py`;
+    default:
+      return null;
+  }
+}
+
+export function readPid(svc: string): number | null {
+  const f = pidFile(svc);
+  if (!fs.existsSync(f)) return null;
+  const n = parseInt(fs.readFileSync(f, 'utf8').trim(), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True if the service has a live PID. Cleans up a stale pidfile, matching bash. */
+export function isRunning(svc: string): boolean {
+  const pid = readPid(svc);
+  if (pid === null) return false;
+  if (pidAlive(pid)) return true;
+  fs.rmSync(pidFile(svc), { force: true });
+  return false;
+}
+
+/** True if a pidfile exists but the process is dead. */
+export function isDead(svc: string): boolean {
+  const pid = readPid(svc);
+  return pid !== null && !pidAlive(pid);
+}
+
+export function writePid(svc: string, pid: number): void {
+  fs.mkdirSync(PID_DIR, { recursive: true });
+  fs.writeFileSync(pidFile(svc), `${pid}\n`);
+}
+
+export function removePid(svc: string): void {
+  fs.rmSync(pidFile(svc), { force: true });
+}
+
+/** Recursively terminate a process tree: SIGTERM, grace period, then SIGKILL. */
+export async function killTree(pid: number): Promise<void> {
+  const r = capture('pgrep', ['-P', String(pid)]);
+  const children = r.stdout
+    .split('\n')
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => Number.isFinite(n));
+  for (const child of children) {
+    await killTree(child);
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    /* already gone */
+  }
+  await sleep(1000);
+  if (pidAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/version.ts

@@ -0,0 +1,21 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ROOT } from './paths';
+
+/** The GroundWork package version this bundle was built from. Injected by
+ *  build.mjs via esbuild `define` so the deployed bundle knows its own vintage —
+ *  the upgrade path (./dev doctor, groundwork check) compares it against the
+ *  install's framework stamp to flag a trailing bundle. */
+export const DEV_CLI_VERSION: string = process.env.GW_DEV_CLI_VERSION || 'unknown';
+
+/** The framework version stamped into this project by groundwork init/update. */
+export function stampedFrameworkVersion(): string | null {
+  try {
+    const state = JSON.parse(
+      fs.readFileSync(path.join(ROOT, '.groundwork', 'config', 'state.json'), 'utf8'),
+    ) as { groundwork?: { version?: string } };
+    return (state.groundwork && state.groundwork.version) || null;
+  } catch {
+    return null;
+  }
+}

package/src/generators/workspace-dev-cli/cli-src/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2021"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/src/generators/workspace-dev-cli/files/.agents/skills/workspace-cli/SKILL.md.template

@@ -0,0 +1,74 @@
+---
+name: workspace-cli
+description: "The primary toolkit for managing local services and the bet delivery workflow in this workspace. Use for start/stop/status, running tests, scaffolding bet/milestone/slice stubs, and archiving delivered bet-progress suites."
+---
+
+# Workspace CLI Skill
+
+You are operating in a workspace that uses a custom `./dev` CLI to manage its local development environment and bet delivery workflow.
+Whenever the user asks you to start, stop, or check the status of the local services, or to scaffold a bet/milestone/slice, run bet-progress tests, or archive a delivered bet, you MUST use this CLI.
+
+## Capabilities
+
+The `./dev` CLI is an executable Node program in the root directory — a thin launcher over a prebuilt, zero-dependency bundle in `.dev/`. It needs no `npm install`; it runs on the Node the workspace already requires. It provides the following commands:
+
+### Lifecycle
+
+- `./dev start`: Starts all services. It automatically handles spinning up infrastructure (like databases) in Docker, and booting application code natively.
+- `./dev start --docker`: Forces ALL services, including application code, to run inside Docker.
+- `./dev stop`: Gracefully kills all native processes and shuts down Docker containers.
+- `./dev reset` / `./dev reset --docker`: Full-cycle recycle — stop, wipe volumes (`clean --hard`), start, then migrate. Use to recover from a corrupted local environment.
+- `./dev status`: Displays a human-readable table of running Docker and native processes.
+- `./dev status --json`: Returns JSON `{ "docker": [{service,status,ports}], "native": [{service,status,pid}] }` on stdout. **Always use this flag when you need to programmatically determine what is running** — never guess ports.
+- `./dev status --watch`: A live, self-refreshing dashboard for humans (TTY only; press `q` to exit). Do not call from a tool — use `--json` instead.
+- `./dev logs`: Prints the recent tail of native and Docker logs, then exits. Safe to run non-interactively.
+- `./dev logs <service>`: Filters to a single service — its native log file if it has one, otherwise its Docker container. An unknown name fails loud (exit 1).
+- `./dev logs --follow`: Streams logs continuously (TTY only). Do not run this from a tool call — it will not return.
+- `./dev health` / `./dev health --json`: Actively HTTP-polls every app service's health endpoint plus Jaeger and prints a pass/fail panel. Exits 1 when any endpoint is down — safe to run non-interactively.
+- `./dev doctor` / `./dev doctor --json`: Verify the local environment. Dependency checks are advisory, but runtime-connectivity failures (DB/Redis/Jaeger unreachable, stack down, missing migration tooling) gate the exit code (non-zero).
+- `./dev completion bash|zsh|fish`: Print a shell completion script.
+
+### Testing
+
+- `./dev test`: Run system tests against the already-running stack (fast inner loop).
+- `./dev test integration`: Boot the dev stack, run system tests with FAIL-LOUD flags, then tear down. Requires Docker — flag before running.
+- `./dev test bet <slug>`: Run a bet-progress suite at `tests/bets/<slug>/` against the already-running stack.
+- `./dev test bet <slug> --integration`: Boot the dev stack, run the bet-progress suite, then tear down. Requires Docker — flag before running.
+
+### Bet Workflow
+
+The bet workflow commands scaffold and manage bet-progress tests — the red, up-front proof-of-work suite written during Decomposition. Two test populations exist: **bet-progress tests** (temporary, in `tests/bets/<slug>/`, archived at delivery) and **permanent best-practice tests** (in service repos and `tests/system/`, stay forever).
+
+- `./dev new bet <slug>`: Create `docs/bets/<slug>/` and `tests/bets/<slug>/` directories for a new bet. `<slug>` must be lowercase kebab-case.
+- `./dev new milestone <bet-slug> <milestone-slug>`: Scaffold a red milestone test stub at `tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.py`. `N` is auto-incremented.
+- `./dev new slice <bet-slug> <milestone-slug> <service> <slice-slug>`: Scaffold a red slice test stub at `tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.py`. `N` is auto-incremented.
+- `./dev archive bet <slug>`: Archive a delivered bet's progress suite — `git mv tests/bets/<slug>/ tests/bets/_archive/<slug>/`.
+
+### Layout
+
+```
+tests/bets/<slug>/                     # Active bet-progress suite (Phases 3–4)
+├── test_milestone_<N>_<slug>.py       # Milestone proof: interface-level + API-level
+└── test_slice_<N>_<service>_<slug>.py # Slice proof, bounded by parent milestone
+
+tests/bets/_archive/<slug>/            # Archived at Phase 5 (delivery); permanent tests take over
+```
+
+Shared fixtures (`cluster`, `api_client`, `pure_state_reset`, `frontend_base_url`) are auto-discovered from `tests/conftest.py` — no explicit import needed in bet test files.
+
+## Best Practices for Agents
+
+1. **Service Discovery**: Do not guess what ports services are running on. Run `./dev status --json` to get the ground truth.
+2. **Log Reading**: `./dev logs` prints the recent tail and exits — safe to call. Only `./dev logs --follow` streams and will hang a tool call; never use `--follow` from `run_command`. For deeper history, read the per-service files in `.dev/logs/*.log`.
+3. **Idempotency**: `./dev start`, `./dev stop`, and `./dev new bet` are fully idempotent. It is safe to run them multiple times.
+4. **Bet test stubs**: After `./dev new milestone` or `./dev new slice`, fill in the `pytest.fail(...)` stub with the target-state assertion before starting Delivery. The stub is intentionally red — it should stay red until the implementation exists.
+5. **Docker gates**: `./dev test integration` and `./dev test bet <slug> --integration` boot Docker. Do not run these commands unless Docker is available and the user expects the boot cost.
+
+## Non-interactive behavior (the agent contract)
+
+The CLI never blocks an agent. `--json` and any non-TTY invocation skip all spinners, live rendering, and prompts — output is plain and the command always returns.
+
+- `./dev status --json` and `./dev doctor --json` emit machine-readable JSON to stdout; all human chrome goes to stderr, so the JSON is pipe-clean.
+- `./dev new bet|milestone|slice` with all arguments supplied runs fully non-interactively — always safe. (When run in a terminal with arguments omitted, it may prompt; supply the arguments to avoid that.)
+- `./dev logs` is non-streaming by default. Only `./dev logs --follow` streams, and it requires a TTY — never call it from a tool.
+- Exit codes: `0` success, `1` failure, `2` usage error (unknown command / bad arguments), `130` on interrupt.

package/src/generators/workspace-dev-cli/files/dev.template

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/*
+ * ./dev — the local development control plane.
+ *
+ * This is a thin launcher over a prebuilt, zero-dependency Node bundle in
+ * .dev/dev-bundle.js. The bundle is built from the GroundWork source and copied in
+ * verbatim, so no `npm install` is needed in this project — it runs on the Node that
+ * the Nx workspace already requires.
+ *
+ * Branding and theming come from .dev/dev.config.json (projected from the design
+ * system's brand tokens). See the workspace-cli skill for the agent-facing contract.
+ */
+'use strict';
+const path = require('path');
+process.env.DEV_ROOT = __dirname;
+require(path.join(__dirname, '.dev', 'dev-bundle.js'));

package/src/generators/workspace-dev-cli/files/docker-compose.yml.template

@@ -0,0 +1,20 @@
+version: '3.8'
+
+# No infrastructure is provisioned by default. There is intentionally no
+# `services:` block here — every backing service is opt-in, added on demand by
+# the generator for a service that actually uses it, so a project provisions
+# only what it needs and `./dev start` never boots an unused (or empty) stack:
+#
+#   - db (Postgres + pgvector) + jaeger (OTLP traces): added by the go / python
+#     microservice generators, which use a per-service database and export
+#     telemetry. jaeger alone is added by the nextjs generator.
+#   - redis / the pubsub emulator: added only for a WebSocket backplane, Redis
+#     pub/sub, or GCP Pub/Sub messaging.
+#
+# A workspace with no containerized service (e.g. a desktop or CLI app whose
+# stores are local-file) has no services at all; its surfaces and native
+# sidecars are managed as runners in .dev/dev.config.json instead.
+
+networks:
+  groundwork-net:
+    driver: bridge

package/src/generators/workspace-dev-cli/files/scripts/cli/templates/milestone-test.pytmpl.template

@@ -0,0 +1,46 @@
+"""Bet-progress test — Milestone @@N@@: @@MILESTONE@@
+Bet: @@BET@@
+
+This test is RED by design. It defines the target state for Milestone @@N@@.
+Run './dev test bet @@BET@@' to see it fail; it will pass when Delivery is complete.
+
+Two complementary proof layers — fill in both before starting Delivery:
+  Layer 1 — Interface: what the user observes in the product's interface
+  Layer 2 — API:       what the running service returns end-to-end over HTTP
+"""
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Layer 1: Interface-level proof
+# ---------------------------------------------------------------------------
+# Use the fixture that matches your project's interface track (docs/design-system.md):
+#   graphical-ui     → page   (pytest-playwright browser fixture)
+#   cli              → subprocess.run / pexpect
+#   agentic-protocol → httpx to the protocol endpoint
+#
+# def test_milestone_@@N@@_@@MILESTONE@@_interface(cluster, page, frontend_base_url):
+#     """Assert what the user observes at Milestone @@N@@."""
+#     page.goto(f"{frontend_base_url}/your-route")
+#     # assert page.locator("...").is_visible()
+#     pytest.fail("bet-progress test not yet implemented — describe the user-visible target state here")
+
+
+# ---------------------------------------------------------------------------
+# Layer 2: API-level system proof
+# ---------------------------------------------------------------------------
+# Uses shared fixtures from tests/conftest.py (auto-discovered, no import needed):
+#   cluster     — health-gates the running services
+#   api_client  — async httpx.AsyncClient with traceparent header
+#
+@pytest.mark.asyncio
+async def test_milestone_@@N@@_@@MILESTONE@@_api(cluster, api_client):
+    """Assert the API-level outcome for Milestone @@N@@: @@MILESTONE@@."""
+    # TODO: replace with the real end-to-end HTTP assertion
+    # resp = await api_client.get("http://localhost:<port>/api/v1/...")
+    # assert resp.status_code == 200
+    pytest.fail(
+        "bet-progress test not yet implemented — "
+        "assert the user-visible outcome via the running API for milestone @@N@@ (@@MILESTONE@@)"
+    )

package/src/generators/workspace-dev-cli/files/scripts/cli/templates/slice-test.pytmpl.template

@@ -0,0 +1,38 @@
+"""Bet-progress test — Slice @@N@@: @@SLUG@@ (service: @@SERVICE@@)
+Bet: @@BET@@  |  Parent milestone: @@MILESTONE@@
+
+This test is RED by design. It proves the vertical capability this slice contributes
+toward Milestone @@MILESTONE@@. Tests are bounded by — not duplicates of — the parent
+milestone tests.
+
+Run './dev test bet @@BET@@' to see it fail; it will pass when this slice is merged.
+"""
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Slice capability proof (@@SERVICE@@ service)
+# ---------------------------------------------------------------------------
+# Slice tests hit the running service from the outside.
+# They do not import application code, mock services, or assume internal schema details.
+#
+# Use shared fixtures from tests/conftest.py (auto-discovered, no import needed):
+#   cluster     — health-gates the running stack
+#   api_client  — async httpx.AsyncClient with traceparent header
+#
+@pytest.mark.asyncio
+async def test_slice_@@N@@_@@SLUG@@(cluster, api_client):
+    """Assert the vertical capability for slice @@N@@ (@@SLUG@@) in @@SERVICE@@.
+
+    This slice contributes to Milestone @@MILESTONE@@.
+    Each assertion here should trace to a Required Capability in decomposition.md.
+    """
+    # TODO: replace with a falsifiable end-to-end HTTP assertion against @@SERVICE@@
+    # resp = await api_client.post("http://localhost:<port>/api/v1/...", json={...})
+    # assert resp.status_code == 201
+    # assert resp.json().get("id") is not None
+    pytest.fail(
+        "bet-progress test not yet implemented — "
+        "assert the vertical capability for slice @@N@@ (@@SLUG@@) in @@SERVICE@@"
+    )

package/src/generators/workspace-dev-cli/generator.ts

@@ -0,0 +1,136 @@
+import { formatFiles, generateFiles, Tree } from '@nx/devkit';
+import * as path from 'path';
+import * as fs from 'fs';
+import { recordGeneratorProvenance } from '../shared/provenance';
+
+export interface WorkspaceDevCliGeneratorSchema {
+  appName?: string;
+  primaryColor?: string;
+  hexColor?: string;
+}
+
+const BRAND_TOKENS_PATH = '.groundwork/config/brand-tokens.json';
+
+/** Project the design system's brand tokens (or sensible defaults) into the runtime
+ *  config the ./dev bundle reads. Self-discovers brand-tokens.json if the design
+ *  system has run; otherwise builds a minimal Tier-1 identity from the options. */
+function buildDevConfig(
+  tree: Tree,
+  projectPrefix: string,
+  appName: string,
+  hexColor: string,
+): Record<string, unknown> {
+  if (tree.exists(BRAND_TOKENS_PATH)) {
+    try {
+      const raw = JSON.parse(tree.read(BRAND_TOKENS_PATH, 'utf-8') || '{}');
+      return {
+        projectPrefix,
+        identity: raw.identity,
+        terminal: raw.terminal,
+      };
+    } catch {
+      /* malformed tokens — fall through to defaults */
+    }
+  }
+  return {
+    projectPrefix,
+    identity: {
+      appName,
+      wordmark: '◢◤',
+      primary: hexColor || '#5fafff',
+      accent: '#d7afff',
+      voice: 'clear, modern',
+    },
+  };
+}
+
+export default async function (tree: Tree, options: WorkspaceDevCliGeneratorSchema) {
+  const projectRoot = '.';
+  const appName = options.appName || 'Workspace';
+  const projectPrefix = appName.toLowerCase().replace(/\s+/g, '-');
+
+  const templateOptions = {
+    ...options,
+    appName,
+    primaryColor: options.primaryColor || 'BLUE',
+    hexColor: options.hexColor || '',
+    projectPrefix,
+    tmpl: '',
+  };
+
+  // docker-compose.yml accretes service registrations from every service
+  // generator after this one runs. A re-run of this generator (e.g. to pick
+  // up a newer CLI bundle) must never reset the workspace topology to the
+  // base infra — preserve the existing file verbatim.
+  const existingCompose = tree.exists('docker-compose.yml')
+    ? tree.read('docker-compose.yml', 'utf-8')
+    : null;
+
+  // EJS-templated files: the launcher, docker-compose, bet stub templates, and the
+  // workspace-cli skill. The prebuilt bundle is deliberately NOT among these — EJS
+  // would corrupt `<%` sequences inside bundled code.
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'workspace-dev-cli', 'files'),
+    projectRoot,
+    templateOptions,
+  );
+
+  if (existingCompose !== null) {
+    tree.write('docker-compose.yml', existingCompose);
+  }
+
+  // Copy the prebuilt CLI bundle verbatim (raw write — never through EJS).
+  const bundlePath = path.join(
+    __dirname,
+    '..',
+    '..',
+    '..',
+    '..',
+    'src',
+    'generators',
+    'workspace-dev-cli',
+    'cli-src',
+    'dist',
+    'dev-bundle.js',
+  );
+  const bundle = fs.readFileSync(bundlePath, 'utf-8');
+  tree.write('.dev/dev-bundle.js', bundle);
+
+  // Project brand tokens into the runtime config the bundle reads. The runner
+  // registry accretes entries from surface/sidecar generators that run after
+  // this one — and a re-run (e.g. to pick up a newer bundle) must not reset it,
+  // exactly like the docker-compose topology above. Preserve any existing
+  // runners verbatim.
+  let preservedRunners: unknown = [];
+  let preservedCommands: unknown = undefined;
+  if (tree.exists('.dev/dev.config.json')) {
+    try {
+      const prev = JSON.parse(tree.read('.dev/dev.config.json', 'utf-8') || '{}');
+      if (Array.isArray(prev.runners)) preservedRunners = prev.runners;
+      // Project-owned commands (the composability seam) are never reset by a re-run —
+      // they belong to the project, not the framework. Carry them verbatim.
+      if (Array.isArray(prev.commands)) preservedCommands = prev.commands;
+    } catch {
+      /* malformed prior config — fall back to an empty registry */
+    }
+  }
+  const devConfig = buildDevConfig(tree, projectPrefix, appName, templateOptions.hexColor);
+  devConfig.runners = preservedRunners;
+  if (preservedCommands !== undefined) devConfig.commands = preservedCommands;
+  tree.write('.dev/dev.config.json', JSON.stringify(devConfig, null, 2) + '\n');
+
+  // Ensure the launcher is executable (generateFiles preserves the template's mode,
+  // but set it explicitly so the bit survives any environment that strips it).
+  if (tree.exists('dev')) {
+    tree.changePermissions('dev', '755');
+  }
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'workspace-dev-cli', {
+    appName,
+    primaryColor: templateOptions.primaryColor,
+    hexColor: templateOptions.hexColor,
+  });
+}