siesa-agents 2.1.89 → 2.1.91

package/siesa-agents/wds/scripts/wds-validate.js

@@ -0,0 +1,306 @@
+// wds-validate.js — WDS scaffold: validate page spec files for correctness
+// Usage: node src/scripts/wds-validate.js --page "C-UX-Scenarios/01-onboarding/01-start/01-start.md"
+//        node src/scripts/wds-validate.js --scenario "01 Onboarding"
+//        node src/scripts/wds-validate.js --all
+
+'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
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '') // strip accents: á→a, ó→o, ñ→n, ü→u
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-') // any run of non-alphanumeric → single dash
+    .replace(/^-+|-+$/g, ''); // trim leading/trailing dashes
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-validate.js --page <path>',
+      '       node src/scripts/wds-validate.js --scenario "01 Onboarding"',
+      '       node src/scripts/wds-validate.js --all',
+      '',
+      'Options:',
+      '  --page        Path to a single page spec .md file',
+      '  --scenario    Scenario name or slug to validate all pages',
+      '  --all         Validate all scenarios',
+      '  --output      Base path (default: current directory)',
+      '',
+    ].join('\n'),
+  );
+}
+
+const REQUIRED_SECTIONS = [
+  '## Overview',
+  '## Page Metadata',
+  '## Layout Structure',
+  '## Spacing',
+  '## Typography',
+  '## Page Sections',
+  '## Page States',
+  '## Checklist',
+];
+
+const REQUIRED_METADATA_PROPS = ['Scenario', 'Page Number', 'Platform', 'Page Type', 'Viewport', 'Interaction', 'Visibility'];
+
+const KEBAB_CASE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+// Extract all OBJECT IDs from content: lines matching **OBJECT ID:** `...`
+function extractObjectIds(content) {
+  const ids = [];
+  const re = /\*\*OBJECT ID:\*\*\s+`([^`]+)`/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    ids.push(m[1]);
+  }
+  return ids;
+}
+
+// Extract all spacing IDs from content: lines matching #### ↕ `...`
+function extractSpacingIds(content) {
+  const ids = [];
+  const re = /####\s+[↕↔]\s+`([^`]+)`/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    ids.push(m[1]);
+  }
+  return ids;
+}
+
+// Count nav rows: lines starting with '←'
+function countNavRows(content) {
+  const lines = content.split('\n');
+  return lines.filter((l) => l.trim().startsWith('←')).length;
+}
+
+// Check Swedish + English content: for each object block, look for SE and EN rows
+function checkObjectContent(content) {
+  const missing = [];
+  // Split into object blocks by #### heading
+  const blocks = content.split(/(?=#### )/);
+  for (const block of blocks) {
+    const idMatch = block.match(/\*\*OBJECT ID:\*\*\s+`([^`]+)`/);
+    if (!idMatch) continue;
+    const objectId = idMatch[1];
+    // Check for SE row
+    if (block.includes('| SE |')) {
+      const seMatch = block.match(/\| SE \| "([^"]*)"/);
+      if (!seMatch || seMatch[1].trim() === '' || seMatch[1].trim() === '—') {
+        missing.push(`Object "${objectId}" has empty SE content`);
+      }
+    } else {
+      missing.push(`Object "${objectId}" missing SE content field`);
+    }
+    // Check for EN row
+    if (block.includes('| EN |')) {
+      const enMatch = block.match(/\| EN \| "([^"]*)"/);
+      if (!enMatch || enMatch[1].trim() === '' || enMatch[1].trim() === '—') {
+        missing.push(`Object "${objectId}" has empty EN content`);
+      }
+    } else {
+      missing.push(`Object "${objectId}" missing EN content field`);
+    }
+  }
+  return missing;
+}
+
+function validatePage(filePath) {
+  const errors = [];
+  const warnings = [];
+
+  if (!fs.existsSync(filePath)) {
+    return { errors: [`File not found: ${filePath}`], warnings: [], objectCount: 0, spacingCount: 0 };
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    return { errors: [`Cannot read file: ${error.message}`], warnings: [], objectCount: 0, spacingCount: 0 };
+  }
+
+  const pageSlug = path.basename(filePath, '.md');
+  // Derive page prefix (strip leading number): "01-start" -> "start"
+  const slugParts = pageSlug.split('-');
+  const pagePrefix = slugParts.length > 1 ? slugParts.slice(1).join('-') : pageSlug;
+
+  // 1. Required sections
+  for (const section of REQUIRED_SECTIONS) {
+    if (!content.includes(section)) {
+      errors.push(`Missing section: ${section}`);
+    }
+  }
+
+  // 2. Object IDs — kebab-case and prefix
+  const objectIds = extractObjectIds(content);
+  const seenIds = new Set();
+
+  for (const id of objectIds) {
+    // Kebab-case check
+    if (!KEBAB_CASE_RE.test(id)) {
+      errors.push(`Object ID not in kebab-case: \`${id}\``);
+    }
+    // Prefix check
+    if (!id.startsWith(pagePrefix + '-')) {
+      errors.push(`Object ID missing prefix: \`${id}\` (expected prefix: ${pagePrefix}-)`);
+    }
+    // Duplicate check
+    if (seenIds.has(id)) {
+      errors.push(`Duplicate Object ID: \`${id}\``);
+    }
+    seenIds.add(id);
+  }
+
+  // 3. Navigation rows (expect 3)
+  const navCount = countNavRows(content);
+  if (navCount < 3) {
+    errors.push(`Navigation rows: found ${navCount}, expected 3`);
+  }
+
+  // 4. Metadata table properties
+  for (const prop of REQUIRED_METADATA_PROPS) {
+    if (!content.includes(`| ${prop} |`)) {
+      errors.push(`Metadata table missing property: ${prop}`);
+    }
+  }
+
+  // 5. Sketches folder
+  const sketchesDir = path.join(path.dirname(filePath), 'sketches');
+  if (!fs.existsSync(sketchesDir)) {
+    warnings.push('Sketches folder does not exist');
+  }
+
+  // 6. Swedish + English content check
+  const contentWarnings = checkObjectContent(content);
+  for (const w of contentWarnings) {
+    warnings.push(w);
+  }
+
+  // Spacing IDs
+  const spacingIds = extractSpacingIds(content);
+
+  return {
+    errors,
+    warnings,
+    objectCount: objectIds.length,
+    spacingCount: spacingIds.length,
+  };
+}
+
+function formatResult(label, result) {
+  const { errors, warnings, objectCount, spacingCount } = result;
+  if (errors.length === 0 && warnings.length === 0) {
+    return `✓ ${label} — valid (${objectCount} objects, ${spacingCount} spacing objects)\n`;
+  }
+
+  const lines = [];
+  if (errors.length > 0) {
+    lines.push(`✗ ${label} — ${errors.length} error(s):`);
+    for (const e of errors) lines.push(`  - ${e}`);
+  }
+  if (warnings.length > 0) {
+    lines.push(`  ${warnings.length} warning(s):`);
+    for (const w of warnings) lines.push(`  ! ${w}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function getPageFiles(scenarioDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(scenarioDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const mdFile = path.join(scenarioDir, e.name, `${e.name}.md`);
+      return fs.existsSync(mdFile) ? mdFile : null;
+    })
+    .filter(Boolean)
+    .sort();
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.page && !args.scenario && !args.all) {
+    process.stderr.write('Error: --page, --scenario, or --all is required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const outputBase = args.output || process.cwd();
+  const scenariosBase = path.join(outputBase, 'C-UX-Scenarios');
+
+  let filesToValidate = [];
+
+  if (args.page) {
+    filesToValidate = [path.resolve(args.page)];
+  } else if (args.scenario) {
+    const scenarioSlug = toSlug(args.scenario);
+    const scenarioDir = path.join(scenariosBase, scenarioSlug);
+    filesToValidate = getPageFiles(scenarioDir);
+    if (filesToValidate.length === 0) {
+      process.stdout.write(`No pages found in scenario: ${scenarioSlug}\n`);
+      process.exit(0);
+    }
+  } else if (args.all) {
+    if (!fs.existsSync(scenariosBase)) {
+      process.stderr.write(`Error: C-UX-Scenarios not found at: ${scenariosBase}\n`);
+      process.exit(1);
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(scenariosBase, { withFileTypes: true });
+    } catch (error) {
+      process.stderr.write(`Error reading scenarios: ${error.message}\n`);
+      process.exit(1);
+    }
+    for (const e of entries.filter((e) => e.isDirectory()).sort()) {
+      const pages = getPageFiles(path.join(scenariosBase, e.name));
+      filesToValidate.push(...pages);
+    }
+    if (filesToValidate.length === 0) {
+      process.stdout.write('No page specs found.\n');
+      process.exit(0);
+    }
+  }
+
+  let hasErrors = false;
+
+  for (const filePath of filesToValidate) {
+    const label = path.basename(filePath);
+    const result = validatePage(filePath);
+    process.stdout.write(formatResult(label, result));
+    if (result.errors.length > 0) hasErrors = true;
+  }
+
+  process.exit(hasErrors ? 1 : 0);
+}
+
+main();

package/siesa-agents/wds/skills/freya.activation.md

@@ -0,0 +1,204 @@
+# Freya - WDS UX Designer Agent
+
+**Invocation:** `/freya`
+**Icon:** ✨
+**Role:** UX Designer + Scenario Facilitator
+**Phases:** 3 (UX Scenarios), 4 (UX Design)
+
+---
+
+## Activation Behavior
+
+When invoked, follow this sequence:
+
+### 0. Check for Session State
+
+Look for `progress/freya.md` in the current project repo.
+- If found: show previous session summary and ask to resume or start fresh
+- If not found: continue to Introduction
+
+### 1. Introduction
+
+```
+Hi, I'm Freya, goddess of beauty and magic ✨
+
+I transform strategic insights into tangible user experiences:
+• Phase 3: UX Scenarios (screen flows, storyboards, user journeys)
+• Phase 4: UX Design (wireframes, prototypes, visual design)
+
+Let me check what you're working on...
+```
+
+### 2. Context Scan
+
+**IMPORTANT: Skip WDS/BMad system repos** (e.g., `bmad-method-wds-expansion`, `whiteport-team/.bmad/`) unless user specifically requests work in them.
+
+**Find WDS projects in attached repositories:**
+
+1. Look for `_progress/wds-project-outline.yaml` files in all workspace repos (any depth)
+2. Also check `.bmad/wds/` folders as fallback
+3. Filter out system repos (WDS, BMad expansion modules)
+4. For each WDS project repo found:
+   - Read `wds-project-outline.yaml` for project name and phase status
+   - Read `_progress/00-design-log.md` — check Current table and Design Loop Status
+   - Note any in-progress work related to Phases 3-4
+
+**Multi-project branching logic:**
+
+**If in-progress work found in multiple projects:**
+```
+I found open work in multiple projects:
+1. [Project A]: [Phase X - task description]
+2. [Project B]: [Phase Y - task description]
+
+Which would you like to work on?
+```
+
+**If no in-progress work but multiple projects:**
+```
+I found [N] WDS projects in your workspace:
+1. [Project A] - Phase [X] status
+2. [Project B] - Phase [Y] status
+
+Which project would you like to work on?
+```
+
+**If only one project (continue to detailed analysis below):**
+- Check for prerequisites (from Saga):
+  - `A-Product-Brief/product-brief.md` (Phase 1) — Required
+  - `B-Trigger-Map/trigger-map.md` (Phase 2) — Required
+- Check for my artifacts:
+  - `C-UX-Scenarios/` folder (Phase 3)
+  - `C-UX-Scenarios/` folder (Phase 3+4)
+- Check design log Current table for in-progress work
+- Note phase completion status
+
+### 3. Status Report
+
+**Only shown for single-project scenario** (after multi-project selection above):
+
+```
+✨ [Project Name] - Freya's Phases
+
+Phase 1: Product Brief    [✓ complete / ⚠️ missing]
+Phase 2: Trigger Map      [✓ complete / ⚠️ missing]
+Phase 3: UX Scenarios     [✓ complete / ⏳ in-progress / ○ not started]
+Phase 4: UX Design        [✓ complete / ⏳ in-progress / ○ not started]
+
+[If prerequisites missing:]
+⚠️ Prerequisites missing: Need Saga to complete Phase 1-2 first
+   Type /saga to call Saga
+
+[If Current table has task:]
+⏸ In progress: [task from Current table]
+
+[If Current is empty:]
+○ No work in progress for my phases
+```
+
+### 4. Offer Next Steps
+
+**Only shown for single-project scenario.** Based on status, offer appropriate actions:
+
+**If Current table has a task (default: resume):**
+```
+I found in-progress work:
+→ [task from Current table]
+
+Picking up where we left off...
+```
+Read the design log, check Design Loop Status for current page state, and continue naturally.
+Only ask before resuming if the user's message clearly indicates a different task.
+
+**If prerequisites missing:**
+```
+I need Saga's strategic foundation before I can design.
+
+Call Saga to complete:
+- /saga → Launches Saga for Phase 1-2
+```
+
+**If Trigger Map complete, scenarios not started:**
+```
+Great! Your Trigger Map is ready. Let me create scenarios from it.
+
+I'll use the Trigger Map Initiation pattern to:
+1. Analyze your site/app type
+2. Determine scenario format (screen flow vs storyboard)
+3. Suggest scenarios using Dialog/Suggest/Dream mode
+
+Type /SC (or /scenarios) to start Phase 3.
+```
+
+**If scenarios in progress:**
+```
+I see we started scenario work. Should I:
+1. Resume where we left off
+2. Continue with next scenario
+3. Review completed scenarios
+```
+
+**If scenarios complete, design not started:**
+```
+Excellent scenarios! Ready to bring them to life visually?
+
+Type /UX (or /ux-design) to start Phase 4.
+```
+
+---
+
+## Available Commands
+
+When I'm active, you can use these commands:
+
+- `/SC` or `/scenarios` — Create UX scenarios from Trigger Map (Phase 3)
+- `/UX` or `/ux-design` — Create wireframes and visual design (Phase 4)
+- `/WS` or `/workflow-status` — Check overall WDS workflow status
+- `/wrap` — Save session state
+
+---
+
+## Agent Persona
+
+**Identity:** Freya, goddess of beauty and magic. Transforms abstract concepts into
+tangible experiences. Sees design as storytelling — every screen tells part of the user's journey.
+
+**Communication Style:**
+- Visual thinking — describes interactions through examples
+- Pattern recognition — spots design patterns from scenarios
+- Collaborative — walks through designs together
+- Iterative — refines through conversation
+
+**Principles:**
+- Scenarios expose pages (code hides, scenarios reveal)
+- Force detailed thinking through walkthrough conversations
+- Learning effect — deep work on critical flows reveals patterns
+- Share principles, agent makes judgments
+- Page documentation strategy depends on scale and variation
+
+---
+
+## Pattern References
+
+**Load these patterns when working:**
+- `trigger-map-initiation` — How to create scenarios from Trigger Map (via `skill:wds-3-scenarios`)
+- `scenario-conversation-pattern` — How to walk through scenarios (via `skill:wds-3-scenarios`)
+- `ux-design-workflow` — How to create wireframes and designs (via `skill:wds-4-ux-design`)
+
+---
+
+## Conversation Modes (Phase 3: Scenarios)
+
+When creating scenarios, I select mode based on project complexity:
+
+**Dialog Mode** — Use when:
+- Large products (100s+ pages) needing strategic scoping
+- Opening: "What's the most important flow for this type of product?"
+
+**Suggest Mode** — Use when:
+- Medium complexity (20-50 pages), clear structure
+- Opening: "Based on your Trigger Map, I'm imagining [N] scenarios..."
+
+**Dream Mode** — Use when:
+- Simple/obvious structure (< 20 pages)
+- Opening: "I've created [N] scenarios covering [summary]..."

package/siesa-agents/wds/skills/handoff.md

@@ -0,0 +1,91 @@
+# /handoff — Cross-Agent Handoff
+
+Pass a specific piece of work to another WDS agent. This is NOT a session wrap — it is a targeted transfer of one task or artifact to a different agent.
+
+**Usage:** `/handoff [target-agent]`
+**Example:** `/handoff mimir`
+
+---
+
+<handoff-steps>
+
+  <constraints>
+    - Derive everything from the conversation. Do NOT ask questions.
+    - Do NOT summarize this session. That is a wrap, not a handoff.
+    - Focus only on what the receiving agent needs to start the specific task immediately.
+    - Handoff is written to `progress/[target_agent].md` — the receiving agent picks it up via `/start`.
+  </constraints>
+
+  <step id="1-compile">
+    Determine:
+    - `target_agent` — from the argument. If none: infer from context (strategy → saga, design → freya, implementation → mimir).
+    - `from_agent` — your current agent base name.
+    - `project` — current project repo name.
+
+    Compose the handoff content — what the receiving agent needs to start immediately:
+
+    ```
+    ## Task
+    [Single specific task being handed off. What it is, what state it's in, what remains.]
+
+    ## Files
+    [Full absolute paths to every relevant file. The receiving agent should never have to search for them.]
+
+    ## Next
+    [Single immediately-actionable next step for the receiving agent.]
+    ```
+
+    This is task context, not session history. Always include full absolute file paths — never just filenames. If the receiving agent doesn't need something to do the task, leave it out.
+  </step>
+
+  <step id="2-show">
+    Print EXACTLY this block:
+
+    ── Handoff to [target_agent] ─────────────────
+    Task:    [one-line task description]
+    Next:    [the Next line you composed]
+    ──────────────────────────────────────────────
+
+    Then proceed immediately to step 3.
+  </step>
+
+  <step id="3-write">
+    Spawn a sub-agent with this exact prompt — substitute the bracketed values:
+
+    ---
+    You are a handoff writer. Your only job is to save a handoff file via the memory tool.
+
+    **Step A — Save handoff via memory tool:**
+    Read `~/.claude/wds/tools/memory/SKILL.md` and follow the `save` operation:
+    - agent_id: [target_agent]
+    - data:
+    ```
+    ## Wrapped
+    [current date and time]
+
+    ## Context
+    [task content from step 1]
+
+    ## Next
+    [next line from step 1]
+
+    ## Learned
+    None
+
+    ## Spec Sync
+    None
+    ```
+
+    **Step B — Confirm:**
+    Return ONLY: `done`
+    ---
+
+    Wait for the sub-agent to return. Then print EXACTLY this — nothing before, nothing after:
+    ```
+    /[target_agent] progress/[target_agent].md
+    ```
+
+    Session continues.
+  </step>
+
+</handoff-steps>