ma-agents 3.12.2 → 3.13.0

package/lib/bmad-cache/wds/src/agents/wds-agent-saga-analyst/customize.toml

@@ -0,0 +1,70 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Saga, the WDS Analyst, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without
+# changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "Saga"
+title = "WDS Analyst"
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "📚"
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Strategic Business Analyst + Product Discovery Partner"
+identity = "Saga, goddess of stories and wisdom. Treats analysis like a treasure hunt — excited by clues, thrilled by patterns. Builds understanding through conversation, not interrogation. Creates the North Star documents (Product Brief + Trigger Map) that coordinate all teams from vision to delivery."
+communication_style = "Asks questions that spark 'aha!' moments while structuring insights with precision. Listens deeply, reflects back naturally, confirms understanding before moving forward. Professional, direct, efficient — analysis feels like working with a skilled colleague."
+
+principles = [
+  "Domain: Phases 1 (Product Brief), 2 (Trigger Mapping). Hand over other domains to specialist agents.",
+  "Replaces BMM Mary (Analyst) when WDS is installed.",
+  "Discovery through conversation — one question at a time, listen deeply.",
+  "Connect business goals to user psychology through trigger mapping.",
+  "Alliterative persona names for user archetypes (e.g. Harriet the Hairdresser).",
+  "Load micro-guides when entering workflows: discovery-conversation.md, trigger-mapping.md, strategic-documentation.md, dream-up-approach.md",
+  "When generating artifacts (not pure discovery), offer Dream Up mode selection: Workshop, Suggest, or Dream.",
+  "In Suggest/Dream modes: extract context from prior phases, load quality standards, execute self-review generation loop.",
+  "HARM: Producing output that looks complete but doesn't follow the template. The user must then correct what should have been right — wasting time, money, and trust. Plausible-looking wrong output is worse than no output. Custom formats break the pipeline for every phase downstream.",
+  "HELP: Reading the actual template into context before writing. Discussing decisions with the user. Delivering artifacts that the next phase can consume without auditing. The user's time goes to decisions, not corrections.",
+]
+
+[[agent.menu]]
+code = "AS"
+description = "Alignment & Signoff: Secure stakeholder alignment before starting the project (Phase 0)"
+skill = "bmad-wds-alignment"
+
+[[agent.menu]]
+code = "PB"
+description = "Product Brief: Create comprehensive product brief with strategic foundation (Phase 1)"
+skill = "bmad-wds-project-brief"
+
+[[agent.menu]]
+code = "TM"
+description = "Trigger Mapping: Create trigger map with user psychology and business goals (Phase 2)"
+skill = "bmad-wds-trigger-mapping"
+
+[[agent.menu]]
+code = "BP"
+description = "Brainstorm Project: Guided brainstorming session to explore project vision and goals"
+skill = "bmad-brainstorming"
+
+[[agent.menu]]
+code = "RS"
+description = "Research: Conduct market, domain, competitive, or technical research"
+skill = "bmad-market-research"
+
+[[agent.menu]]
+code = "DP"
+description = "Document Project: Analyze existing project to produce useful documentation (brownfield projects)"
+skill = "bmad-document-project"

package/lib/bmad-cache/wds/src/module-help.csv

@@ -1,19 +1,19 @@
-module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
-Web Design Studio,bmad-wds-idun,Wake Idun,IDUN,Setup and governance agent. Interviews org to configure Agent Space and authority model.,,0-wds-agents,,,false,,
-Web Design Studio,bmad-wds-saga,Wake Saga,SAGA,Strategic Analyst agent for Phases 1-2. Scans repos and offers next steps.,,0-wds-agents,,,false,,
-Web Design Studio,bmad-wds-freya,Wake Freya,FREYA,UX Designer agent for Phases 3-4. Checks prerequisites and offers next steps.,,0-wds-agents,,,false,,
-Web Design Studio,bmad-wds-alignment,Alignment & Signoff,AS,Stakeholder buy-in pitch and service agreement. Skip if building your own product.,,0-wds-pitch,,,false,design_artifacts/A-Product-Brief,"pitch service-agreement signoff"
-Web Design Studio,bmad-wds-project-brief,Project Brief,PB,Define product vision positioning and success criteria. Every design decision traces back to this.,,1-wds-strategy,,,true,design_artifacts/A-Product-Brief,project-brief.md
-Web Design Studio,bmad-wds-trigger-mapping,Trigger Mapping,TM,Map business goals to user psychology. Create personas and score features against driving forces.,,1-wds-strategy,bmad-wds-project-brief,,true,design_artifacts/B-Trigger-Map,"trigger-map.md personas/ feature-impact-analysis.md"
-Web Design Studio,bmad-wds-platform-requirements,Platform Requirements,PR,Technical boundaries: platforms devices integrations constraints. Skip for simple landing pages.,,1-wds-strategy,bmad-wds-project-brief,,false,design_artifacts/A-Product-Brief,platform-requirements.md
-Web Design Studio,bmad-wds-outline-scenarios,Outline Scenarios,OS,Define user journeys as persona+goal+outcome. Each connects to a Trigger Map driving force.,,2-wds-design,bmad-wds-trigger-mapping,,true,design_artifacts/C-UX-Scenarios,scenario-overview.md
-Web Design Studio,bmad-wds-conceptual-sketching,Conceptual Sketching,CS,Fast rough visual exploration before detailed specification. Skip for straightforward scenarios.,,2-wds-design,bmad-wds-outline-scenarios,,false,design_artifacts/C-UX-Scenarios,sketches
-Web Design Studio,bmad-wds-storyboarding,Storyboarding,SB,Sequence the user journey through screens with entry points transitions and error paths. Skip for simple scenarios.,,2-wds-design,bmad-wds-outline-scenarios,,false,design_artifacts/C-UX-Scenarios,storyboards
-Web Design Studio,bmad-wds-conceptual-specs,Conceptual Specifications,SP,Document every design decision for every element on every page. Developers build directly from this.,,2-wds-design,bmad-wds-outline-scenarios,,true,design_artifacts/C-UX-Scenarios,"page-specs scenario-specs"
-Web Design Studio,bmad-wds-functional-components,Functional Components,FI,Extract reusable patterns from specs into component definitions. Skip if Design System Mode None.,,2-wds-design,bmad-wds-conceptual-specs,,false,design_artifacts/C-UX-Scenarios,component-candidates
-Web Design Studio,bmad-wds-visual-design,Visual Design,VD,Transform specs into styled HTML prototypes with Figma round-trips.,,2-wds-design,bmad-wds-conceptual-specs,,false,design_artifacts/C-UX-Scenarios,"html-prototypes visual-designs"
-Web Design Studio,bmad-wds-design-system,Design System,DS,Manage component library and design tokens. Skip if Design System Mode None.,,2-wds-design,bmad-wds-functional-components,,false,design_artifacts/D-Design-System,"components/ design-tokens.md"
-Web Design Studio,bmad-wds-design-delivery,Design Delivery,DD,Validate specs are complete and package as DD yaml files for development handoff.,,2-wds-design,bmad-wds-conceptual-specs,,true,design_artifacts/E-Development,"delivery-package acceptance-criteria"
-Web Design Studio,bmad-wds-agentic-development,Agentic Development,AD,Iterative build-verify cycle with design log tracking and browser verification.,,3-wds-build,bmad-wds-design-delivery,,false,_progress/agent-experiences,experience-documents
-Web Design Studio,bmad-wds-usability-testing,Acceptance Testing,AT,Test on real users in their environment with retrospective think-aloud sessions.,,3-wds-build,bmad-wds-agentic-development,,false,design_artifacts/E-Development,"test-results findings"
-Web Design Studio,bmad-wds-product-evolution,Product Evolution,PE,Continuous improvement: feedback to Trigger Map to spec update to code to verify.,,3-wds-build,bmad-wds-usability-testing,,false,design_artifacts,updated-artifacts
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+Web Design Studio,bmad-wds-idun,Wake Idun,IDUN,Setup and governance agent. Interviews org to configure Agent Space and authority model.,,,0-wds-agents,,,false,,
+Web Design Studio,bmad-wds-saga,Wake Saga,SAGA,Strategic Analyst agent for Phases 1-2. Scans repos and offers next steps.,,,0-wds-agents,,,false,,
+Web Design Studio,bmad-wds-freya,Wake Freya,FREYA,UX Designer agent for Phases 3-4. Checks prerequisites and offers next steps.,,,0-wds-agents,,,false,,
+Web Design Studio,bmad-wds-alignment,Alignment & Signoff,AS,Stakeholder buy-in pitch and service agreement. Skip if building your own product.,,,0-wds-pitch,,,false,design_artifacts/A-Product-Brief,pitch service-agreement signoff
+Web Design Studio,bmad-wds-project-brief,Project Brief,PB,Define product vision positioning and success criteria. Every design decision traces back to this.,,,1-wds-strategy,,,true,design_artifacts/A-Product-Brief,project-brief.md
+Web Design Studio,bmad-wds-trigger-mapping,Trigger Mapping,TM,Map business goals to user psychology. Create personas and score features against driving forces.,,,1-wds-strategy,bmad-wds-project-brief,,true,design_artifacts/B-Trigger-Map,trigger-map.md personas/ feature-impact-analysis.md
+Web Design Studio,bmad-wds-platform-requirements,Platform Requirements,PR,Technical boundaries: platforms devices integrations constraints. Skip for simple landing pages.,,,1-wds-strategy,bmad-wds-project-brief,,false,design_artifacts/A-Product-Brief,platform-requirements.md
+Web Design Studio,bmad-wds-outline-scenarios,Outline Scenarios,OS,Define user journeys as persona+goal+outcome. Each connects to a Trigger Map driving force.,,,2-wds-design,bmad-wds-trigger-mapping,,true,design_artifacts/C-UX-Scenarios,scenario-overview.md
+Web Design Studio,bmad-wds-conceptual-sketching,Conceptual Sketching,CS,Fast rough visual exploration before detailed specification. Skip for straightforward scenarios.,,,2-wds-design,bmad-wds-outline-scenarios,,false,design_artifacts/C-UX-Scenarios,sketches
+Web Design Studio,bmad-wds-storyboarding,Storyboarding,SB,Sequence the user journey through screens with entry points transitions and error paths. Skip for simple scenarios.,,,2-wds-design,bmad-wds-outline-scenarios,,false,design_artifacts/C-UX-Scenarios,storyboards
+Web Design Studio,bmad-wds-conceptual-specs,Conceptual Specifications,SP,Document every design decision for every element on every page. Developers build directly from this.,,,2-wds-design,bmad-wds-outline-scenarios,,true,design_artifacts/C-UX-Scenarios,page-specs scenario-specs
+Web Design Studio,bmad-wds-functional-components,Functional Components,FI,Extract reusable patterns from specs into component definitions. Skip if Design System Mode None.,,,2-wds-design,bmad-wds-conceptual-specs,,false,design_artifacts/C-UX-Scenarios,component-candidates
+Web Design Studio,bmad-wds-visual-design,Visual Design,VD,Transform specs into styled HTML prototypes with Figma round-trips.,,,2-wds-design,bmad-wds-conceptual-specs,,false,design_artifacts/C-UX-Scenarios,html-prototypes visual-designs
+Web Design Studio,bmad-wds-design-system,Design System,DS,Manage component library and design tokens. Skip if Design System Mode None.,,,2-wds-design,bmad-wds-functional-components,,false,design_artifacts/D-Design-System,components/ design-tokens.md
+Web Design Studio,bmad-wds-design-delivery,Design Delivery,DD,Validate specs are complete and package as DD yaml files for development handoff.,,,2-wds-design,bmad-wds-conceptual-specs,,true,design_artifacts/E-Development,delivery-package acceptance-criteria
+Web Design Studio,bmad-wds-agentic-development,Agentic Development,AD,Iterative build-verify cycle with design log tracking and browser verification.,,,3-wds-build,bmad-wds-design-delivery,,false,_progress/agent-experiences,experience-documents
+Web Design Studio,bmad-wds-usability-testing,Acceptance Testing,AT,Test on real users in their environment with retrospective think-aloud sessions.,,,3-wds-build,bmad-wds-agentic-development,,false,design_artifacts/E-Development,test-results findings
+Web Design Studio,bmad-wds-product-evolution,Product Evolution,PE,Continuous improvement: feedback to Trigger Map to spec update to code to verify.,,,3-wds-build,bmad-wds-usability-testing,,false,design_artifacts,updated-artifacts

package/lib/bmad-cache/wds/src/module.yaml

@@ -127,6 +127,34 @@ directories:
   - "{design_artifacts}"
   - "{project_knowledge}"
 
+# Agent roster — essence only. External skills (party-mode, retrospective,
+# advanced-elicitation, help catalog) read these descriptors to route, display,
+# and embody agents. Full persona and behavior live in each agent's
+# customize.toml. `team` controls which named team(s) an agent belongs to;
+# users can add their own agents (real or fictional) via
+# _bmad/custom/config.toml or _bmad/custom/config.user.toml.
+agents:
+  - code: wds-agent-freya-ux
+    name: Freya
+    title: WDS Designer
+    icon: "🎨"
+    team: ux-design
+    description: "Norse goddess of beauty, magic, and strategy, thinks WITH you not FOR you, starts with WHY before HOW — design without strategy is decoration, creates artifacts developers can trust: detailed specs, prototypes, and design systems. Speaks as a creative collaborator with strategic depth — asks WHY? before WHAT?, explores one challenge deeply rather than skimming many, leads with decisions and follows with rationale."
+
+  - code: wds-agent-saga-analyst
+    name: Saga
+    title: WDS Analyst
+    icon: "📚"
+    team: ux-design
+    description: "Goddess of stories and wisdom, treats analysis like a treasure hunt — excited by clues, thrilled by patterns, builds understanding through conversation not interrogation, creates the North Star documents (Product Brief + Trigger Map). Asks questions that spark aha! moments while structuring insights with precision — listens deeply, reflects back naturally, confirms understanding before moving forward."
+
+  - code: wds-agent-mimir-builder
+    name: Mimir
+    title: WDS Builder
+    icon: "🔨"
+    team: ux-design
+    description: "God of wisdom and deep knowledge — the well beneath the world tree. Implementation agent who owns the tech audit, the PRD, and the build loop. Methodical, precise, empirical. Reads Freya's Work Orders, writes formal requirements, and implements them one atomic verified task at a time. Reads the spec completely before writing a line of code. Plans before acting. Verifies before moving on."
+
 # WDS folder structure to create within design_artifacts directory
 wds_folders:
   - A-Product-Brief

package/lib/bmad-cache/wds/src/scripts/README.md

@@ -0,0 +1,155 @@
+# WDS Scaffold Scripts
+
+Node.js scripts that enforce deterministic output from AI agents. Agents provide content via CLI flags; scripts produce structure.
+
+All scripts use only Node.js stdlib (no external dependencies). Run from the project root.
+
+---
+
+## Scripts
+
+### `wds-init-scenario.js` — Initialize a scenario
+
+Creates the scenario folder and a README index file.
+
+```bash
+node src/scripts/wds-init-scenario.js \
+  --scenario "01 New User Onboarding" \
+  --description "New user first visit to account creation"
+```
+
+Output: `C-UX-Scenarios/01-new-user-onboarding/README.md`
+
+---
+
+### `wds-init-page.js` — Initialize a page spec
+
+Creates a new page spec file with all required sections pre-filled with placeholders.
+
+```bash
+node src/scripts/wds-init-page.js \
+  --page "01 Start" \
+  --scenario "01 New User Onboarding" \
+  --platform "Mobile web" \
+  --visibility "Public"
+```
+
+Output:
+- `C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md`
+- `C-UX-Scenarios/01-new-user-onboarding/01-start/sketches/`
+
+After creating all pages in a scenario, run `wds-nav.js` to wire up navigation links.
+
+---
+
+### `wds-nav.js` — Update navigation links
+
+Scans pages in a scenario (sorted by name) and writes correct prev/next navigation rows into each page spec.
+
+```bash
+# One scenario
+node src/scripts/wds-nav.js --scenario "01 New User Onboarding"
+
+# All scenarios
+node src/scripts/wds-nav.js --all
+```
+
+Run this after adding or removing pages, or after reordering page numbers.
+
+---
+
+### `wds-add-object.js` — Append an object spec
+
+Appends a structured object spec block to a page spec under a named section.
+
+```bash
+node src/scripts/wds-add-object.js \
+  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md" \
+  --section "Hero" \
+  --object "Primary Headline" \
+  --component "H1 heading" \
+  --se "Välkommen" \
+  --en "Welcome" \
+  --behavior "Static display"
+```
+
+Object ID is auto-derived: `start-hero-primary-headline`
+
+The section heading (`### Section: Hero`) is created if it doesn't already exist.
+
+---
+
+### `wds-add-spacing.js` — Append a spacing object
+
+Appends a spacing notation entry to the `## Spacing` section of a page spec.
+
+```bash
+node src/scripts/wds-add-spacing.js \
+  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md" \
+  --direction v \
+  --type space \
+  --size xl \
+  --reason "major section boundary between hero and features"
+```
+
+Valid directions: `v` (vertical), `h` (horizontal)
+Valid types: `space`, `separator`, `line`
+Valid sizes: `zero`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `flex`
+
+Spacing ID is auto-derived: `start-v-space-xl`
+
+---
+
+### `wds-validate.js` — Validate page specs
+
+Checks page spec files for structural correctness.
+
+```bash
+# Single page
+node src/scripts/wds-validate.js \
+  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md"
+
+# All pages in a scenario
+node src/scripts/wds-validate.js --scenario "01 New User Onboarding"
+
+# All scenarios
+node src/scripts/wds-validate.js --all
+```
+
+Validates:
+- Required sections present
+- Object IDs are kebab-case with correct page prefix
+- No duplicate Object IDs
+- Navigation rows (3 expected)
+- Metadata table has all required properties
+- Sketches folder exists
+- SE + EN content present for each object
+
+---
+
+## How agents use these scripts
+
+1. Agent calls `wds-init-scenario.js` with scenario name and description
+2. Agent calls `wds-init-page.js` for each page in the scenario
+3. Agent calls `wds-nav.js` to wire navigation after all pages exist
+4. Agent calls `wds-add-object.js` for each UI object, providing Swedish and English content
+5. Agent calls `wds-add-spacing.js` for each spacing decision
+6. Agent calls `wds-validate.js` to confirm the spec is structurally correct before handoff
+
+The agent never writes raw markdown — it only supplies content as flag values. The scripts own all structural decisions.
+
+---
+
+## File location convention
+
+```
+C-UX-Scenarios/
+  {scenario-slug}/
+    README.md
+    {page-slug}/
+      {page-slug}.md
+      sketches/
+        {page-slug}-concept.jpg
+```
+
+Example: `C-UX-Scenarios/01-new-user-onboarding/02-signup/02-signup.md`

package/lib/bmad-cache/wds/src/scripts/wds-add-object.js

@@ -0,0 +1,202 @@
+// wds-add-object.js — WDS scaffold: append an object spec block to a page spec file
+// Usage: node src/scripts/wds-add-object.js --page "C-UX-Scenarios/01-onboarding/01-start/01-start.md" \
+//          --section "Hero" --object "Primary Headline" --component "H1 heading" \
+//          --se "Välkommen" --en "Welcome"
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i++;
+    }
+  }
+  return args;
+}
+
+function toSlug(str) {
+  return str.toLowerCase().replaceAll(/\s+/g, '-');
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-add-object.js --page <path> --section <name> --object <name> [options]',
+      '',
+      'Required:',
+      '  --page        Path to the page spec .md file',
+      '  --section     Section name (e.g. "Hero")',
+      '  --object      Object name (e.g. "Primary Headline")',
+      '',
+      'Optional:',
+      '  --component   Component name (default: "—")',
+      '  --translation Translation key (auto-derived if omitted)',
+      '  --se          Swedish text content',
+      '  --en          English text content',
+      '  --behavior    Behavior description (e.g. "onClick: submit form")',
+      '  --component-path  Path to component file (default: "—")',
+      '',
+    ].join('\n'),
+  );
+}
+
+// Derive page slug from file path: "01-start/01-start.md" -> "01-start"
+function pageSlugFromPath(filePath) {
+  const base = path.basename(filePath, '.md');
+  return base;
+}
+
+// Derive Object ID: pageSlug + sectionSlug + objectSlug
+// e.g. page=01-start, section=Hero, object=Primary Headline -> 01-start-hero-primary-headline
+function deriveObjectId(pageSlug, sectionName, objectName) {
+  // Strip leading page number from pageSlug for ID prefix
+  // "01-start" -> "start", "02-signup" -> "signup"
+  const slugParts = pageSlug.split('-');
+  const pagePrefix = slugParts.length > 1 ? slugParts.slice(1).join('-') : pageSlug;
+  const sectionSlug = toSlug(sectionName);
+  const objectSlug = toSlug(objectName);
+  return `${pagePrefix}-${sectionSlug}-${objectSlug}`;
+}
+
+function buildObjectBlock({ objectName, objectId, component, componentPath, translationKey, se, en, behavior }) {
+  const compDisplay = componentPath && componentPath !== '—' ? `[${component}](${componentPath})` : component || '—';
+
+  const lines = [
+    `#### ${objectName}`,
+    '',
+    `**OBJECT ID:** \`${objectId}\``,
+    '',
+    '| Property | Value |',
+    '|----------|-------|',
+    `| Component | ${compDisplay} |`,
+    `| Translation Key | \`${translationKey}\` |`,
+    `| SE | "${se || '—'}" |`,
+    `| EN | "${en || '—'}" |`,
+    `| Behavior | ${behavior || '—'} |`,
+    '',
+  ];
+
+  return lines.join('\n');
+}
+
+// Insert content after a section heading. Creates the section heading if it doesn't exist.
+function insertUnderSection(content, sectionHeading, objectBlock) {
+  const lines = content.split('\n');
+  const headingLine = `### Section: ${sectionHeading}`;
+  const headingIdx = lines.findIndex((l) => l.trim() === headingLine);
+
+  if (headingIdx === -1) {
+    // Section doesn't exist — append it before the next ## heading after ## Page Sections
+    const pageSectionsIdx = lines.findIndex((l) => l.trim() === '## Page Sections');
+    if (pageSectionsIdx === -1) {
+      // Just append at end before last nav row
+      return content + `\n${headingLine}\n\n${objectBlock}\n`;
+    }
+
+    // Find end of ## Page Sections block
+    let insertIdx = pageSectionsIdx + 1;
+    while (insertIdx < lines.length) {
+      const t = lines[insertIdx].trim();
+      if (t.startsWith('## ') || t === '---') break;
+      insertIdx++;
+    }
+
+    const before = lines.slice(0, insertIdx);
+    const after = lines.slice(insertIdx);
+    return [...before, '', headingLine, '', objectBlock, ...after].join('\n');
+  } else {
+    // Find the end of this section (next ### or ## or end of file)
+    let insertIdx = headingIdx + 1;
+    // Skip blank lines after heading
+    while (insertIdx < lines.length && lines[insertIdx].trim() === '') insertIdx++;
+    // Skip comment lines
+    while (insertIdx < lines.length && lines[insertIdx].trim().startsWith('<!--')) insertIdx++;
+
+    // Find end of section
+    let endIdx = insertIdx;
+    while (endIdx < lines.length) {
+      const t = lines[endIdx].trim();
+      if (t.startsWith('### ') || t.startsWith('## ') || t === '---') break;
+      endIdx++;
+    }
+
+    // Insert object block before end of section
+    const before = lines.slice(0, endIdx);
+    const after = lines.slice(endIdx);
+    return [...before, '', objectBlock, ...after].join('\n');
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.page || !args.section || !args.object) {
+    process.stderr.write('Error: --page, --section, and --object are required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const filePath = path.resolve(args.page);
+
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`Error: File not found: ${filePath}\n`);
+    process.exit(1);
+  }
+
+  const pageSlug = pageSlugFromPath(filePath);
+  const objectId = deriveObjectId(pageSlug, args.section, args.object);
+
+  // Auto-derive translation key from objectId
+  const translationKey = args.translation || objectId.replaceAll('-', '.');
+
+  const objectBlock = buildObjectBlock({
+    objectName: args.object,
+    objectId,
+    component: args.component || '—',
+    componentPath: args['component-path'] || '—',
+    translationKey,
+    se: args.se || '',
+    en: args.en || '',
+    behavior: args.behavior || '—',
+  });
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error reading file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  // Check for duplicate object ID
+  if (content.includes(`\`${objectId}\``)) {
+    process.stderr.write(`Error: Object ID already exists in file: ${objectId}\n`);
+    process.exit(1);
+  }
+
+  const updated = insertUnderSection(content, args.section, objectBlock);
+
+  try {
+    fs.writeFileSync(filePath, updated, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error writing file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Added object ${objectId}\n`);
+  process.stdout.write(`  File: ${filePath}\n`);
+}
+
+main();

package/lib/bmad-cache/wds/src/scripts/wds-add-spacing.js

@@ -0,0 +1,158 @@
+// wds-add-spacing.js — WDS scaffold: append a spacing object to a page spec file
+// Usage: node src/scripts/wds-add-spacing.js --page "C-UX-Scenarios/01-onboarding/01-start/01-start.md" \
+//          --direction v --type space --size xl --reason "major section boundary between hero and features"
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i++;
+    }
+  }
+  return args;
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-add-spacing.js --page <path> --direction <v|h> --type <type> --size <size> [options]',
+      '',
+      'Required:',
+      '  --page        Path to the page spec .md file',
+      '  --direction   v (vertical) or h (horizontal)',
+      '  --type        space | separator | line',
+      '  --size        zero | sm | md | lg | xl | 2xl | 3xl | flex',
+      '',
+      'Optional:',
+      '  --reason      Why this spacing exists',
+      '',
+      'Valid directions: v, h',
+      'Valid types:      space, separator, line',
+      'Valid sizes:      zero, sm, md, lg, xl, 2xl, 3xl, flex',
+      '',
+    ].join('\n'),
+  );
+}
+
+const VALID_DIRECTIONS = ['v', 'h'];
+const VALID_TYPES = ['space', 'separator', 'line'];
+const VALID_SIZES = ['zero', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', 'flex'];
+
+// Derive page prefix from slug: "01-start" -> "start"
+function pagePrefix(slug) {
+  const parts = slug.split('-');
+  return parts.length > 1 ? parts.slice(1).join('-') : slug;
+}
+
+function pageSlugFromPath(filePath) {
+  return path.basename(filePath, '.md');
+}
+
+function buildSpacingBlock(spacingId, reason) {
+  const icon = '↕';
+  const reasonText = reason ? ` — ${reason}` : '';
+  return `#### ${icon} \`${spacingId}\`${reasonText}\n`;
+}
+
+function appendToSpacingSection(content, spacingBlock) {
+  const lines = content.split('\n');
+  const spacingIdx = lines.findIndex((l) => l.trim() === '## Spacing');
+
+  if (spacingIdx === -1) {
+    // No spacing section — append before first ## after metadata
+    return content + `\n## Spacing\n\n${spacingBlock}\n`;
+  }
+
+  // Find end of spacing section (next ## or ---)
+  let endIdx = spacingIdx + 1;
+  while (endIdx < lines.length) {
+    const t = lines[endIdx].trim();
+    if ((t.startsWith('## ') && t !== '## Spacing') || t === '---') break;
+    endIdx++;
+  }
+
+  // Insert just before the end marker
+  const before = lines.slice(0, endIdx);
+  const after = lines.slice(endIdx);
+  return [...before, spacingBlock, ...after].join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.page || !args.direction || !args.type || args.size === 0) {
+    process.stderr.write('Error: --page, --direction, --type, and --size are required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!VALID_DIRECTIONS.includes(args.direction)) {
+    process.stderr.write(`Error: Invalid direction "${args.direction}". Must be: ${VALID_DIRECTIONS.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  if (!VALID_TYPES.includes(args.type)) {
+    process.stderr.write(`Error: Invalid type "${args.type}". Must be: ${VALID_TYPES.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  if (!VALID_SIZES.includes(args.size)) {
+    process.stderr.write(`Error: Invalid size "${args.size}". Must be: ${VALID_SIZES.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  const filePath = path.resolve(args.page);
+
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`Error: File not found: ${filePath}\n`);
+    process.exit(1);
+  }
+
+  const slug = pageSlugFromPath(filePath);
+  const prefix = pagePrefix(slug);
+  const spacingId = `${prefix}-${args.direction}-${args.type}-${args.size}`;
+  const reason = args.reason || '';
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error reading file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  // Check for duplicate spacing ID
+  if (content.includes(`\`${spacingId}\``)) {
+    process.stderr.write(`Error: Spacing ID already exists in file: ${spacingId}\n`);
+    process.stderr.write('Use a different combination of direction/type/size or manually edit the file.\n');
+    process.exit(1);
+  }
+
+  const spacingBlock = buildSpacingBlock(spacingId, reason);
+  const updated = appendToSpacingSection(content, spacingBlock);
+
+  try {
+    fs.writeFileSync(filePath, updated, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error writing file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Added spacing object ${spacingId}\n`);
+  process.stdout.write(`  File: ${filePath}\n`);
+}
+
+main();