@monster-orange/den 0.2.8 → 0.4.0

package/scripts/heal-config.ts

@@ -16,12 +16,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
 
-import { OP_ACCOUNT_DEFAULT } from "../src/shared/constants.js";
-
 import { product } from "../src/shared/product.js";
-// Ensure op (if used later) hits the right account when this script runs
-// standalone via npx tsx, matching the pattern in setup-1password.ts et al.
-process.env.OP_ACCOUNT ||= OP_ACCOUNT_DEFAULT;
 
 const ROOT = process.cwd();
 const CONFIG_PATH = path.join(ROOT, product().configFile);

package/scripts/setup-1password.ts

@@ -1,9 +1,12 @@
 /**
  * 1Password Developer API Keys setup.
  *
- * Creates and populates the developer-keys item (OP_DEV_KEYS_ITEM) inside the
- * personal vault (OP_API_KEYS_VAULT), which services can use to inject
- * secrets at `make up` time via `op run --env-file=.env.op`.
+ * Creates and populates the developer-keys item inside a vault, which
+ * services can use to inject secrets at `make up` time via
+ * `op run --env-file=.env.op`. Where it lives is the distribution's choice:
+ * `secrets.developer_keys.{vault,item}` in the org config, else the vault
+ * and item of `secrets.refs.sudo`. Den has no default; with neither set the
+ * script says "not configured" and exits 0 (1 with --check).
  *
  * Which keys to collect is org data: `secrets.developer_keys.fields` in the
  * org config (default: only the keys the engine itself uses), and
@@ -11,7 +14,8 @@
  * offered as defaults.
  *
  * Usage:
- *   make den-setup-1password          — full interactive setup
+ *   make <cli>-setup-1password        — full interactive setup (only when
+ *                                       secrets.provider is 1password)
  *   npx tsx scripts/setup-1password.ts --check   — non-interactive vault check
  *                                                   exits 0 if ready, 1 if not
  */
@@ -20,22 +24,23 @@ import { execFile, spawnSync } from "child_process";
 import { promisify } from "util";
 import * as fs from "fs";
 import * as path from "path";
-import { fileURLToPath } from "url";
 import chalk from "chalk";
 import {
-  OP_ACCOUNT_DEFAULT,
-  OP_API_KEYS_VAULT,
-  OP_DEV_KEYS_ITEM,
-} from "../src/shared/constants.js";
-import {
+  notConfiguredMessage,
   readSecretsConfig,
+  secretsStrategy,
   type DeveloperKeyDef,
 } from "../src/shared/secrets/index.js";
 
 import { product } from "../src/shared/product.js";
-// Ensure op invocations hit the den-owned account even when this script is
-// run directly via `npx tsx` (not through make, which already exports OP_ACCOUNT).
-process.env.OP_ACCOUNT ||= OP_ACCOUNT_DEFAULT;
+import { getDistRoot } from "../src/shared/paths.js";
+const SECRETS_CFG = readSecretsConfig();
+// op uses the distribution's account (secrets.onepassword.account) or the
+// engineer's own OP_ACCOUNT; Den has none of its own.
+Object.assign(
+  process.env,
+  secretsStrategy("1password")?.capabilities.env?.(SECRETS_CFG, process.env),
+);
 
 const execFileAsync = promisify(execFile);
 
@@ -46,11 +51,19 @@ async function opJson<T>(args: string[]): Promise<T> {
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DEN_ROOT = path.resolve(__dirname, "..");
+// dotenv paths are relative to the distribution root, never the engine.
+const DEN_ROOT = getDistRoot();
 
-const VAULT_NAME = OP_API_KEYS_VAULT;
-const ITEM_NAME = OP_DEV_KEYS_ITEM;
+const pick = (...v: Array<string | undefined>): string =>
+  v.map((x) => (typeof x === "string" ? x.trim() : "")).find(Boolean) ?? "";
+const VAULT_NAME = pick(
+  SECRETS_CFG.developer_keys?.vault,
+  SECRETS_CFG.refs?.sudo?.vault,
+);
+const ITEM_NAME = pick(
+  SECRETS_CFG.developer_keys?.item,
+  SECRETS_CFG.refs?.sudo?.item,
+);
 
 // ─── .env reader ─────────────────────────────────────────────────────────────
 
@@ -89,7 +102,7 @@ function parseEnvFile(filePath: string): Record<string, string> {
   return result;
 }
 
-const DEVELOPER_KEYS = readSecretsConfig().developer_keys ?? {};
+const DEVELOPER_KEYS = SECRETS_CFG.developer_keys ?? {};
 
 /**
  * The dotenv file `secrets.developer_keys.env_file` names (relative to the
@@ -560,7 +573,16 @@ async function setupMode(): Promise<void> {
 
 const isCheck = process.argv.includes("--check");
 
-if (isCheck) {
+if (!VAULT_NAME || !ITEM_NAME) {
+  // No place for the developer keys: nothing to set up, and no op call.
+  console.log(
+    `Developer keys item ${notConfiguredMessage("sudo").replace(
+      /secrets\.refs\.sudo/,
+      "secrets.developer_keys.vault + .item (or secrets.refs.sudo)",
+    )}`,
+  );
+  process.exit(isCheck ? 1 : 0);
+} else if (isCheck) {
   checkMode().catch(() => process.exit(1));
 } else {
   setupMode().catch((err: Error) => {

package/scripts/setup-secrets.ts

@@ -1,17 +1,21 @@
 /**
  * Backend-agnostic developer-secrets setup.
  *
- * Dispatches to the strategy selected by `secrets.provider` in
- * config/den.yml (override: DEN_SECRETS_PROVIDER or
- * config/local/user.yml). See src/shared/secrets.
+ * Dispatches to the `setup` capability of the strategy selected by
+ * `secrets.provider` in the org config (override: DEN_SECRETS_PROVIDER or
+ * config/local/user.yml). See src/shared/secrets/strategies.ts.
  *
  * Usage:
  *   make den-setup-secrets                 — interactive setup
  *   npx tsx scripts/setup-secrets.ts --check    — non-interactive; exit 0 when ready
  *   npx tsx scripts/setup-secrets.ts --cli      — print "<provider> <binary> <formula>"
- *   npx tsx scripts/setup-secrets.ts --gate     — like --check, but a backend that
- *                                                 is not ready only warns unless
- *                                                 secrets.required is true
+ *   npx tsx scripts/setup-secrets.ts --provider — print the selected strategy id
+ *   npx tsx scripts/setup-secrets.ts --gate     — the up / web gate: passes
+ *                                                 silently unless secrets.required
+ *                                                 is true, then like --check
+ *
+ * With `secrets.provider: none` there is nothing to set up: it says so and
+ * exits 0.
  */
 import { spawnSync } from "child_process";
 import * as path from "path";
@@ -20,6 +24,8 @@ import chalk from "chalk";
 import {
   getSecretsProvider,
   readSecretsConfig,
+  resolveProvider,
+  strategyFor,
 } from "../src/shared/secrets/index.js";
 
 import { envKey, product } from "../src/shared/product.js";
@@ -31,126 +37,86 @@ function run(cmd: string, args: string[]): number {
   return spawnSync(cmd, args, { stdio: "inherit", cwd: ROOT }).status ?? 1;
 }
 
-function installed(cmd: string): boolean {
-  return !spawnSync(cmd, ["--version"], { stdio: "ignore" }).error;
-}
-
-const INSTALL: Record<string, string> = {
-  doppler: "brew install dopplerhq/cli/doppler",
-  op: "brew install 1password-cli",
-};
-
-function otherBackends(current: string): string {
-  return (
-    "Or pick another backend for just you (config/local/user.yml):\n" +
-    "    secrets:\n" +
-    `      provider: env        # or 1password / doppler (team default: ${current})\n` +
-    `  or for one shell: ${envKey("SECRETS_PROVIDER")}=env make web`
-  );
-}
+const NONE_MESSAGE =
+  "No secrets backend is configured (secrets.provider: none), so there is nothing to set up.\n" +
+  `To use one, set secrets.provider (doppler | 1password | env) and secrets.refs.<name> in ${product().configFile}.`;
 
 async function main(): Promise<number> {
-  const provider = getSecretsProvider();
   const cfg = readSecretsConfig();
-  const label = `secrets backend: ${provider.name}`;
+  const resolved = resolveProvider(cfg);
+  const strategy = strategyFor(resolved.name);
+  const label = `secrets backend: ${resolved.name}`;
+
+  // `--provider`: print the selected strategy id (make reads it to offer
+  // backend-specific targets). Never probes the backend.
+  if (process.argv.includes("--provider")) {
+    console.log(resolved.name);
+    return 0;
+  }
 
   // `--cli`: print "<provider> <binary> <brew formula>" for make setup's
-  // install step ("env -" when the backend needs no CLI).
+  // install step ("<provider> - -" when the backend needs no CLI). An unset
+  // provider needs nothing installed until something asks for a secret.
   if (process.argv.includes("--cli")) {
-    const bin =
-      provider.name === "doppler"
-        ? "doppler"
-        : provider.name === "1password"
-          ? "op"
-          : "";
-    const formula = bin ? INSTALL[bin].replace(/^brew install /, "") : "";
-    console.log(`${provider.name} ${bin || "-"} ${formula || "-"}`);
+    const cli = resolved.implicit ? undefined : strategy.capabilities.cli;
+    console.log(`${resolved.name} ${cli?.bin ?? "-"} ${cli?.formula ?? "-"}`);
     return 0;
   }
 
+  // The up / web gate: only a distribution that requires its backend
+  // (secrets.required) is checked. Nothing required: pass, silently, whatever
+  // the provider; a feature that needs a secret reports it when it asks.
+  if (gate && !cfg.required) return 0;
+
   if (check || gate) {
-    const r = await provider.preflight();
-    if (r.ok) return 0;
-    if (gate && !cfg.required) {
-      // Signed in but no default scope: secret_env refs name their own
-      // (<project>/<config>/<key>), so only the engine's own secrets lack one.
-      if (await provider.isReady()) {
-        console.error(
-          chalk.gray(
-            `   ${label}: signed in, no default scope set (secret_env refs still resolve;` +
-              ` test logins and the saved sudo password need one: \`make ${product().cli}-setup-secrets\`).`,
-          ),
-        );
-        return 0;
-      }
-      console.error(
-        chalk.yellow(
-          `⚠️  ${label} is not ready — continuing.\n` +
-            "   Test logins and the saved sudo password need it; run " +
-            `\`make ${product().cli}-setup-secrets\` when you want them.`,
-        ),
-      );
+    if (resolved.name === "none" || (resolved.implicit && !cfg.required)) {
+      if (resolved.name === "none")
+        console.log(`  ✓ ${NONE_MESSAGE.split("\n")[0]}`);
       return 0;
     }
+    const r = await getSecretsProvider().preflight();
+    if (r.ok) return 0;
     console.error(chalk.red(`✗ ${label}\n${r.message ?? ""}`));
     return 1;
   }
 
+  const setup = strategy.capabilities.setup;
+  if (resolved.name === "none" || !setup) {
+    console.log(NONE_MESSAGE);
+    return 0;
+  }
+  if (resolved.implicit && !cfg.required) {
+    // Nothing chose a backend and nothing requires one: no store to set up.
+    console.log(
+      "secrets.provider is not set, so there is nothing to set up.\n" +
+        `To use a backend, set secrets.provider (doppler | 1password | env | none) in ${product().configFile}.`,
+    );
+    return 0;
+  }
   console.log(
     chalk.bold(`\n${product().title} developer secrets (${label})\n`),
   );
-  switch (provider.name) {
-    case "doppler": {
-      if (!installed("doppler")) {
-        console.error(
-          chalk.red("✗ The Doppler CLI is not installed.\n") +
-            `  Install it:  ${INSTALL.doppler}\n  then re-run: make ${product().cli}-setup-secrets\n\n  ` +
-            otherBackends(provider.name),
-        );
-        return 1;
-      }
-      if (!(await provider.isReady())) {
-        console.log("→ doppler login");
-        if (run("doppler", ["login"]) !== 0) return 1;
-      }
-      const scope: string[] = [];
-      if (cfg.doppler?.project) scope.push("--project", cfg.doppler.project);
-      if (cfg.doppler?.config) scope.push("--config", cfg.doppler.config);
-      console.log(`→ doppler setup ${scope.join(" ")}`.trim());
-      if (
-        run("doppler", ["setup", "--no-interactive", ...scope]) !== 0 &&
-        scope.length === 0
-      ) {
-        run("doppler", ["setup"]);
-      }
-      break;
-    }
-    case "1password":
-      if (!installed("op")) {
-        console.error(
-          chalk.red("✗ The 1Password CLI (op) is not installed.\n") +
-            `  Install it:  ${INSTALL.op}\n\n  ` +
-            otherBackends(provider.name),
-        );
-        return 1;
-      }
-      return run(path.join(ROOT, "node_modules", ".bin", "tsx"), [
-        path.join(ROOT, "scripts", "setup-1password.ts"),
-      ]);
-    case "env":
-      console.log(
-        "The env backend reads secrets from the process environment.\n" +
-          `Export them yourself (direnv, CI secrets, \`doppler run -- ${product().cli} up\`).`,
-      );
-      break;
-  }
+  const provider = getSecretsProvider();
+  const code = await setup({
+    cfg,
+    provider,
+    engineRoot: ROOT,
+    cli: product().cli,
+    run,
+    log: (l) => console.log(l),
+    error: (l) => console.error(chalk.red(l)),
+  });
+  if (code !== 0) return code;
   const r = await provider.preflight();
   console.log(
     r.ok ? chalk.green(`✓ ${label} ready`) : chalk.red(`✗ ${r.message}`),
   );
+  if (!r.ok)
+    console.log(
+      `  Or for one shell: ${envKey("SECRETS_PROVIDER")}=none make web`,
+    );
   return r.ok ? 0 : 1;
 }
-
 main().then(
   (code) => process.exit(code),
   (err: unknown) => {

package/src/pillars/api/global-setup.ts

@@ -86,7 +86,7 @@ async function globalSetup(_config: FullConfig) {
           `  ⚠  No credentials for ${role} — authenticated ${role} tests will fail`,
         );
         console.warn(
-          `     eval $(op signin) && make auth-configure (admin) or verify 1Password vault`,
+          `     set E2E_${role.toUpperCase()}_EMAIL / _PASSWORD, or set up the secrets backend (secrets.provider)`,
         );
       } else {
         // Token mint failure, IdP misconfiguration, etc. — fail fast

package/src/pillars/journeys/sandbox.ts

@@ -36,10 +36,10 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { OP_API_KEYS_VAULT, OP_DEV_KEYS_ITEM } from "../../shared/constants.js";
 import {
   getSecretsProvider,
   namedSecretRef,
+  notConfiguredMessage,
   type SecretRef,
 } from "../../shared/secrets/index.js";
 import type { Environment } from "../../shared/types/index.js";
@@ -51,22 +51,12 @@ import { getDistRoot } from "../../shared/paths.js";
 import { containsValue } from "../../shared/redact.js";
 // ── Layer 1: captureSecrets ──────────────────────────────────────────────────
 
-/** 1Password field label holding the Cursor API key (= env var name). */
+/** The Cursor API key's env var name (and the usual field label). */
 export const CURSOR_API_KEY_FIELD = "CURSOR_API_KEY";
 
 /** Name of the agent-key ref under `secrets.refs` in the org config. */
 export const JOURNEYS_AGENT_KEY_REF = "journeys_agent_key";
 
-/**
- * Where the agent key lives when `secrets.refs.journeys_agent_key` is not
- * configured: the engineer's own developer-keys item (neutral default).
- */
-export const JOURNEYS_AGENT_KEY_DEFAULT: SecretRef = {
-  vault: OP_API_KEYS_VAULT,
-  item: OP_DEV_KEYS_ITEM,
-  field: CURSOR_API_KEY_FIELD,
-};
-
 /**
  * Secrets captured into memory before environment sanitization.
  *
@@ -84,6 +74,7 @@ export interface OpFieldRequest {
   item: string;
   vault: string;
   field: string;
+  key?: string;
 }
 
 export interface CaptureSecretsDeps {
@@ -91,8 +82,11 @@ export interface CaptureSecretsDeps {
   opReadField?: (request: OpFieldRequest) => Promise<string>;
   /** Env-var source; defaults to process.env. */
   env?: NodeJS.ProcessEnv;
-  /** Where the key lives; defaults to the configured `journeys_agent_key` ref. */
-  agentKeyRef?: SecretRef;
+  /**
+   * Where the key lives; defaults to the configured `journeys_agent_key`
+   * ref. null: not configured (there is no built-in location).
+   */
+  agentKeyRef?: SecretRef | null;
 }
 
 /** Default reader: the configured secrets strategy. */
@@ -118,14 +112,25 @@ export async function captureSecrets(
   if (cursorApiKey.length === 0) {
     let opError = "";
     const ref =
-      deps.agentKeyRef ??
-      namedSecretRef(JOURNEYS_AGENT_KEY_REF, JOURNEYS_AGENT_KEY_DEFAULT);
+      deps.agentKeyRef !== undefined
+        ? deps.agentKeyRef
+        : namedSecretRef(JOURNEYS_AGENT_KEY_REF);
+    if (!ref) {
+      // No configured place for the key: say so, without asking a backend.
+      throw new Error(
+        `No Cursor API key available for journey agents.\n` +
+          `  Options:\n` +
+          `    • set the ${CURSOR_API_KEY_FIELD} env var\n` +
+          `    • secrets backend: ${notConfiguredMessage(JOURNEYS_AGENT_KEY_REF)}\n`,
+      );
+    }
     try {
       cursorApiKey = (
         await opReadField({
           item: ref.item,
           vault: ref.vault,
           field: ref.field,
+          ...(ref.key ? { key: ref.key } : {}),
         })
       ).trim();
     } catch (error) {
@@ -137,8 +142,8 @@ export async function captureSecrets(
           `  Options:\n` +
           `    • CI: set the ${CURSOR_API_KEY_FIELD} env var\n` +
           `    • Local: sign in to the secrets backend (make ${product().cli}-setup-secrets) and\n` +
-          `      make sure the "${ref.item}" item in the "${ref.vault}" vault has a\n` +
-          `      ${ref.field} field (move it with secrets.refs.${JOURNEYS_AGENT_KEY_REF})\n` +
+          `      make sure secrets.refs.${JOURNEYS_AGENT_KEY_REF} (item "${ref.item}", vault "${ref.vault}",\n` +
+          `      field ${ref.field}) holds the key\n` +
           (opError ? `  Secrets backend error: ${opError}\n` : ""),
       );
     }

package/src/pillars/journeys/tools/browser-session.ts

@@ -32,7 +32,7 @@ import { product } from "../../../shared/product.js";
  * Mint a fresh authenticated browser session for `role` against `env`'s
  * web surface and return the storageState auth-file path (and nothing
  * else). Throws a loud, actionable error when credentials cannot be
- * sourced — naming both the 1Password path (local) and the E2E_* env-var
+ * sourced — naming both the secrets-backend path (local) and the E2E_* env-var
  * path (CI), mirroring browser/global-setup.ts.
  */
 export async function provisionBrowserSession(
@@ -47,7 +47,7 @@ export async function provisionBrowserSession(
   if (!credentials) {
     const localHint =
       role === "admin"
-        ? `  Local: make auth-configure env=${env}  (handles 1Password sign-in automatically)\n`
+        ? `  Local: with secrets.provider: 1password, make auth-configure env=${env}\n`
         : `  Local: sign in to the secrets backend (make ${product().cli}-setup-secrets); the ${role} account comes from test_accounts in the org config\n`;
     throw new Error(
       `No credentials for ${role}.\n` +

package/src/scripts/setup-default-workspace.ts

@@ -145,7 +145,7 @@ async function main() {
     '  This builds the "default" workspace — every standard system repo,\n' +
       `  all managed: ${product().cli} clones and keeps each one up to date for\n` +
       "  you, no checkouts or decisions required. For anything you actively\n" +
-      "  develop, flip that repo to dev-managed in the web UX (Local Dev)\n" +
+      "  develop, flip that repo to dev-managed in the web UX (Workspaces)\n" +
       "  and point it at your own checkout.\n",
   );
 
@@ -183,7 +183,7 @@ async function main() {
     `\n  ✓ Default workspace configured with ${seed.length} service(s), all managed.`,
   );
   console.log(
-    "  Change any repo to dev-managed in the web UX: make web → Local Dev.",
+    "  Change any repo to dev-managed in the web UX: make web → Workspaces.",
   );
   console.log(`  Run 'make ${product().cli}-up' to start your services.\n`);
 }

package/src/shared/agents/default-pack/be-dev.md

@@ -0,0 +1,20 @@
+---
+name: be-dev
+description: Implements back-end stories, test first, keeping contracts stable.
+context:
+  [
+    the story and its acceptance criteria,
+    the service's API contracts,
+    the repo's conventions,
+  ]
+---
+
+You are a back-end developer. Implement one story end to end.
+
+- Write a failing test for each acceptance criterion first, then make it pass.
+- Keep public contracts backward compatible unless the story says otherwise;
+  call out any migration.
+- Validate input at the boundary, handle errors explicitly, and never log
+  secrets.
+- Run the repo's checks before opening a pull request, and describe what you
+  verified in it.

package/src/shared/agents/default-pack/devops.md

@@ -0,0 +1,14 @@
+---
+name: devops
+description: Builds and maintains pipelines, environments and service configuration.
+context: [the story, the workspace's service manifests, CI configuration]
+---
+
+You are a devops engineer. Make services easy to build, run and ship.
+
+- Prefer declarative configuration and small, reversible changes.
+- Keep secrets in the configured secret store; never write a value into a
+  file, a log or a pull request.
+- Prove each change locally (bring the service up, check its health) before
+  proposing it.
+- Explain the operational impact and the rollback in the pull request.

package/src/shared/agents/default-pack/fe-dev.md

@@ -0,0 +1,20 @@
+---
+name: fe-dev
+description: Implements front-end stories, test first, to the design system.
+context:
+  [
+    the story and its acceptance criteria,
+    the design system,
+    the front-end conventions of the repo,
+  ]
+---
+
+You are a front-end developer. Implement one story end to end.
+
+- Write a failing test for each acceptance criterion first, then make it pass.
+- Use the design system's components and tokens; do not invent new ones
+  without the ux-designer.
+- Keep the change small and focused on the story. Check accessibility and
+  narrow screens.
+- Run the repo's checks before opening a pull request, and describe what you
+  verified in it.

package/src/shared/agents/default-pack/orchestrator.md

@@ -0,0 +1,16 @@
+---
+name: orchestrator
+description: Takes the next ready story, picks the persona for it and starts that agent.
+standing: true
+context: [ready work items, running agents in the workspace]
+---
+
+You are the orchestrator. Keep work flowing without overloading the machine
+or the people reviewing it.
+
+- Take the next ready story, in priority order. Pick the persona that fits it:
+  fe-dev, be-dev or devops for implementation, ux-designer for design work.
+- Start one agent per story, in its own worktree, and link it to the story.
+- Respect the workspace's concurrency cap; wait rather than queueing more.
+- When a pull request is opened, ask the reviewer for a review. Never approve
+  or merge anything yourself.

package/src/shared/agents/default-pack/planner.md

@@ -0,0 +1,17 @@
+---
+name: planner
+description: Writes stories and their acceptance criteria for the workspace.
+standing: true
+context: [the workspace's specs and docs, open work items, the design system]
+---
+
+You are the planner. Turn goals and requests into small, independently
+shippable stories, each with a clear user outcome and testable acceptance
+criteria.
+
+- Read the existing specs and work items before writing a new story; extend
+  them rather than duplicating them.
+- Keep each story to one vertical slice that can be reviewed on its own.
+- Suggest an architecture or design record (ARD, ADR or LLD) only when a story
+  changes a contract, a data model or a boundary between components.
+- Hand each ready story to the orchestrator. You do not write code.

package/src/shared/agents/default-pack/reviewer.md

@@ -0,0 +1,14 @@
+---
+name: reviewer
+description: Reviews a pull request adversarially. Never approves or merges.
+context: [the pull request and its story, the repo's conventions and tests]
+---
+
+You are the reviewer. Try to prove the change wrong before anyone relies on it.
+
+- Check it against the story's acceptance criteria, then look for what the
+  author did not test: edge cases, failure paths, security, performance.
+- Verify each finding by reading the code; drop anything you cannot show.
+- Report findings ranked by impact, each with a concrete scenario and a
+  suggested fix.
+- You never approve, merge or push. A person decides.

package/src/shared/agents/default-pack/ux-designer.md

@@ -0,0 +1,15 @@
+---
+name: ux-designer
+description: Designs flows and screens with the design system, on request.
+context: [the story, the design system, existing screens of the product]
+---
+
+You are the UX designer. Make the next step obvious for the person using the
+product.
+
+- Start from the user's goal and the story's acceptance criteria.
+- Compose from the design system's components; propose a new component only
+  when none fits, and say why.
+- Describe states (empty, loading, error, success) and narrow screens, not only
+  the happy path.
+- Hand off a short spec the developers can implement and test.