@jaimevalasek/aioson 1.4.0 → 1.6.0

package/src/worker-runner.js

@@ -0,0 +1,339 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const SQUADS_DIR = path.join('.aioson', 'squads');
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_RETRY_ATTEMPTS = 3;
+const BACKOFF_BASE = [1000, 3000, 8000];
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadWorkerConfig(projectDir, squadSlug, workerSlug) {
+  const configPath = path.join(projectDir, SQUADS_DIR, squadSlug, 'workers', workerSlug, 'worker.json');
+  if (!(await pathExists(configPath))) return null;
+  const raw = await fs.readFile(configPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+async function listWorkers(projectDir, squadSlug) {
+  const workersDir = path.join(projectDir, SQUADS_DIR, squadSlug, 'workers');
+  let entries;
+  try {
+    entries = await fs.readdir(workersDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const workers = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const config = await loadWorkerConfig(projectDir, squadSlug, entry.name);
+    if (config) {
+      workers.push({ slug: entry.name, ...config });
+    }
+  }
+  return workers;
+}
+
+function resolveScript(projectDir, squadSlug, workerSlug) {
+  const base = path.join(projectDir, SQUADS_DIR, squadSlug, 'workers', workerSlug);
+  return {
+    js: path.join(base, 'run.js'),
+    py: path.join(base, 'run.py')
+  };
+}
+
+function validateInputs(inputPayload, inputSchema) {
+  if (!inputSchema) return { valid: true, errors: [] };
+  const errors = [];
+  for (const [key, spec] of Object.entries(inputSchema)) {
+    if (spec.required && (inputPayload[key] === undefined || inputPayload[key] === null)) {
+      errors.push(`Missing required input: ${key}`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function spawnWorker(scriptPath, inputPayload, env, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const ext = path.extname(scriptPath);
+    const cmd = ext === '.py' ? 'python3' : 'node';
+    const args = [scriptPath, JSON.stringify(inputPayload)];
+    const child = spawn(cmd, args, {
+      env: { ...process.env, ...env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        let output;
+        try {
+          output = JSON.parse(stdout);
+        } catch {
+          output = { raw: stdout.trim() };
+        }
+        resolve({ ok: true, output, stderr: stderr.trim() || null });
+      } else {
+        let errorDetail;
+        try {
+          errorDetail = JSON.parse(stderr);
+        } catch {
+          errorDetail = { message: stderr.trim() || `Process exited with code ${code}` };
+        }
+        resolve({ ok: false, error: errorDetail.error || errorDetail.message || String(errorDetail), code });
+      }
+    });
+
+    child.on('error', (err) => {
+      if (err.code === 'ETIMEDOUT' || err.killed) {
+        resolve({ ok: false, error: `Worker timed out after ${timeoutMs}ms`, code: -1 });
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+function resolveEnvVars(envKeys) {
+  const resolved = {};
+  for (const key of (envKeys || [])) {
+    if (process.env[key]) {
+      resolved[key] = process.env[key];
+    }
+  }
+  return resolved;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function runWorker(projectDir, squadSlug, workerSlug, inputPayload, options = {}) {
+  const config = await loadWorkerConfig(projectDir, squadSlug, workerSlug);
+  if (!config) {
+    return { ok: false, error: `Worker config not found: ${workerSlug}`, attempts: 0 };
+  }
+
+  // Validate inputs
+  const validation = validateInputs(inputPayload || {}, config.inputs);
+  if (!validation.valid) {
+    return { ok: false, error: `Input validation failed: ${validation.errors.join(', ')}`, attempts: 0 };
+  }
+
+  // Resolve script path
+  const scripts = resolveScript(projectDir, squadSlug, workerSlug);
+  let scriptPath;
+  if (await pathExists(scripts.js)) {
+    scriptPath = scripts.js;
+  } else if (await pathExists(scripts.py)) {
+    scriptPath = scripts.py;
+  } else {
+    return { ok: false, error: `No run script found for worker: ${workerSlug}`, attempts: 0 };
+  }
+
+  // Resolve env vars
+  const env = resolveEnvVars(config.env);
+
+  // Resolve MCP env vars if worker declares uses_mcp
+  if (config.uses_mcp && config.uses_mcp.length > 0) {
+    try {
+      const { listIntegrations, buildWorkerMcpEnv } = require('./mcp-connectors/registry');
+      const integrations = await listIntegrations(projectDir, squadSlug);
+      const mcpEnv = buildWorkerMcpEnv(projectDir, squadSlug, config.uses_mcp, integrations);
+      Object.assign(env, mcpEnv);
+    } catch { /* MCP resolution optional — fail silently */ }
+  }
+
+  // Timeout and retry config
+  const timeoutMs = config.timeout_ms || DEFAULT_TIMEOUT;
+  const maxAttempts = (config.retry && config.retry.attempts) || (options.noRetry ? 1 : DEFAULT_RETRY_ATTEMPTS);
+  const triggerType = options.triggerType || 'manual';
+
+  let lastResult;
+  const startTime = Date.now();
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    lastResult = await spawnWorker(scriptPath, inputPayload || {}, env, timeoutMs);
+    lastResult.attempt = attempt;
+    lastResult.triggerType = triggerType;
+
+    if (lastResult.ok) {
+      lastResult.durationMs = Date.now() - startTime;
+      return lastResult;
+    }
+
+    // Backoff before retry
+    if (attempt < maxAttempts) {
+      const delay = BACKOFF_BASE[attempt - 1] || BACKOFF_BASE[BACKOFF_BASE.length - 1];
+      await sleep(delay);
+    }
+  }
+
+  lastResult.durationMs = Date.now() - startTime;
+  return lastResult;
+}
+
+// --- Scaffold generation ---
+
+function generateWorkerJson(slug, name, triggerType, inputFields, outputFields, envVars) {
+  const trigger = { type: triggerType || 'manual' };
+  if (triggerType === 'event') {
+    trigger.source = 'content_item_created';
+    trigger.filter = {};
+  }
+  if (triggerType === 'scheduled') {
+    trigger.cron = '0 8 * * *';
+  }
+
+  const inputs = {};
+  for (const field of (inputFields || [])) {
+    inputs[field] = { type: 'string', required: true };
+  }
+
+  const outputs = {};
+  for (const field of (outputFields || [])) {
+    outputs[field] = { type: 'string' };
+  }
+
+  return {
+    slug,
+    name: name || slug,
+    type: triggerType || 'manual',
+    trigger,
+    inputs,
+    outputs,
+    env: envVars || [],
+    timeout_ms: 30000,
+    retry: { attempts: 3, backoff: 'exponential' }
+  };
+}
+
+function generateRunJs(slug, config) {
+  const inputParsing = Object.keys(config.inputs || {}).length > 0
+    ? Object.keys(config.inputs).map(k => `  // input.${k}`).join('\n')
+    : '  // No inputs defined';
+
+  const outputReturn = Object.keys(config.outputs || {}).length > 0
+    ? '    ' + Object.keys(config.outputs).map(k => `${k}: null`).join(',\n    ')
+    : '    result: "ok"';
+
+  return `#!/usr/bin/env node
+'use strict';
+
+// Worker: ${slug}
+// Trigger: ${config.type || 'manual'}
+// Generated by aioson squad:create
+
+const input = JSON.parse(process.argv[2] || '{}');
+
+async function execute(input) {
+  // Available inputs:
+${inputParsing}
+
+  // TODO: Implement worker logic here
+  // Examples:
+  //   - Send WhatsApp message via Business API
+  //   - Call external REST API
+  //   - Calculate metrics and save to squad_metrics
+  //   - Move a lead in CRM
+  //   - Send email via SMTP
+
+  return {
+${outputReturn}
+  };
+}
+
+execute(input)
+  .then(result => {
+    process.stdout.write(JSON.stringify(result));
+    process.exit(0);
+  })
+  .catch(err => {
+    process.stderr.write(JSON.stringify({ error: err.message }));
+    process.exit(1);
+  });
+`;
+}
+
+function generateWorkerReadme(slug, config) {
+  const envSection = (config.env || []).length > 0
+    ? config.env.map(e => `- \`${e}\``).join('\n')
+    : '- None';
+
+  return `# Worker: ${config.name || slug}
+
+## Trigger
+- **Type**: ${config.type || 'manual'}
+${config.trigger && config.trigger.cron ? `- **Cron**: \`${config.trigger.cron}\`` : ''}
+${config.trigger && config.trigger.source ? `- **Source**: ${config.trigger.source}` : ''}
+
+## Inputs
+${Object.entries(config.inputs || {}).map(([k, v]) => `- \`${k}\` (${v.type})${v.required ? ' *required*' : ''}`).join('\n') || '- None'}
+
+## Outputs
+${Object.entries(config.outputs || {}).map(([k, v]) => `- \`${k}\` (${v.type})`).join('\n') || '- None'}
+
+## Environment Variables
+${envSection}
+
+## Usage
+
+\`\`\`bash
+# Run manually
+aioson squad:worker --squad=<squad-slug> --worker=${slug} --input='{"key": "value"}'
+
+# Test with dry run
+aioson squad:worker --squad=<squad-slug> --worker=${slug} --sub=test
+
+# View execution logs
+aioson squad:worker --squad=<squad-slug> --sub=logs
+\`\`\`
+`;
+}
+
+async function scaffoldWorker(projectDir, squadSlug, workerSlug, options = {}) {
+  const workerDir = path.join(projectDir, SQUADS_DIR, squadSlug, 'workers', workerSlug);
+  await fs.mkdir(workerDir, { recursive: true });
+
+  const config = generateWorkerJson(
+    workerSlug,
+    options.name,
+    options.triggerType,
+    options.inputs,
+    options.outputs,
+    options.env
+  );
+
+  await fs.writeFile(path.join(workerDir, 'worker.json'), JSON.stringify(config, null, 2));
+  await fs.writeFile(path.join(workerDir, 'run.js'), generateRunJs(workerSlug, config));
+  await fs.writeFile(path.join(workerDir, 'README.md'), generateWorkerReadme(workerSlug, config));
+
+  return { workerDir, config };
+}
+
+module.exports = {
+  loadWorkerConfig,
+  listWorkers,
+  runWorker,
+  scaffoldWorker,
+  generateWorkerJson,
+  generateRunJs,
+  generateWorkerReadme,
+  validateInputs,
+  resolveEnvVars
+};

package/template/.aioson/agents/analyst.md

@@ -40,6 +40,25 @@ Check the following before doing anything else:
 - `.aioson/context/design-doc.md` + `readiness.md` (if present)
 - `.aioson/context/discovery.md` + `spec.md` (feature mode — project context, if present)
 
+## Context loading policy
+
+**Sempre carregar:**
+- `.aioson/context/project.context.md`
+- `prd*.md` ou `prd-{slug}.md` relevante
+- `sheldon-enrichment-{slug}.md` (se existir)
+
+**Carregar só se relevante ao scope:**
+- `architecture.md` (brownfield apenas)
+- skills do domínio atual
+
+**Nunca carregar:**
+- Arquivos de implementação (src/, routes/, etc.)
+- Specs de features não relacionadas
+
+## Disk-first principle
+
+Escreva `discovery.md` ou `requirements-{slug}.md` no disco antes de retornar qualquer resposta ao usuário. Se a sessão cair no meio do trabalho, os artefatos escritos são recuperáveis — análises apenas na conversa são perdidas. Para cada fase significativa: execute, escreva o artefato, então responda.
+
 ## Context integrity
 
 Read `project.context.md` before starting discovery.
@@ -91,6 +110,8 @@ Before deepening discovery:
 - use `readiness.md` to avoid unnecessary rediscovery
 - load only the docs that actually matter for this batch
 - consult local skills only when they improve domain mapping or flow clarity
+- check `.aioson/installed-skills/` for any installed skill relevant to the current discovery scope — load `SKILL.md` of matching skills, then load per-agent references only if they reduce ambiguity for the current phase
+- if `aioson-spec-driven` is installed (`.aioson/installed-skills/aioson-spec-driven/SKILL.md` exists), load it when starting feature discovery or project discovery — then load `references/analyst.md` from that skill
 
 Do not inflate context without need.
 
@@ -175,8 +196,15 @@ For each new or modified entity, produce field-level detail (same format as Phas
 4. Relationships (with existing entities from discovery.md)
 5. Migration additions (ordered)
 6. Business rules
-7. Edge cases
-8. Out of scope for this feature
+   - Use format: `REQ-{slug}-{N}` for each rule (e.g., `REQ-checkout-01`)
+   - Each rule must state: condition + expected behavior + who can trigger it
+7. Acceptance criteria
+   - Use format: `AC-{slug}-{N}` (e.g., `AC-checkout-01`)
+   - Each AC must be independently verifiable by QA without implementation knowledge
+8. Edge cases and failure modes
+   - Cover: invalid input, empty states, concurrent operations, external service failure
+9. Out of scope for this feature
+   - Be explicit — list what was deliberately excluded and why
 
 **`spec-{slug}.md`** — feature memory skeleton (will be enriched by @dev):
 
@@ -185,6 +213,12 @@ For each new or modified entity, produce field-level detail (same format as Phas
 feature: {slug}
 status: in_progress
 started: {ISO-date}
+phase_gates:
+  requirements: approved      # approved | pending | needs_work
+  design: pending             # approved | pending | skipped (MICRO/SMALL sem @architect)
+  plan: pending               # approved | pending | skipped (MICRO sem implementation-plan)
+last_checkpoint: null         # filled by @dev after each completed phase
+pending_review: []            # items that need human review before next phase
 ---
 
 # Spec — {Feature Name}
@@ -209,7 +243,19 @@ started: {ISO-date}
 [Anything @dev or @qa should know before touching this feature]
 ```
 
-After producing both files, tell the user: "Feature spec ready. Activate **@dev** to implement — it will read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`."
+After producing both files, use `AskUserQuestion` with `multiSelect: true` to confirm which requirements are approved:
+
+```
+AskUserQuestion:
+  question: "Quais requirements estão aprovados para prosseguir?"
+  multiSelect: true
+  options:
+    - label: "REQ-{slug}-01: [título]"
+    - label: "REQ-{slug}-02: [título]"
+    - label: "Todos aprovados"
+```
+
+Then tell the user: "Feature spec ready. Activate **@dev** to implement — it will read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`."
 
 ## MICRO shortcut
 If classification is MICRO (score 0–1) or the user describes a clearly single-entity project with no integrations, adapt the process:
@@ -226,6 +272,9 @@ The `@analyst` owns all technical and structural content: requirements, entities
 Copy, interface text, onboarding messages, and marketing content are not within `@analyst` scope.
 
 ## Output contract
+
+> **CRITICAL — FILE WRITE RULE:** Every artifact listed below MUST be written to disk using the Write tool before this agent session ends. Generating content as chat text is NOT sufficient. Always write the file, then confirm it was saved with: `✅ discovery.md written — @architect can proceed.`
+
 Generate `.aioson/context/discovery.md` with the following sections:
 
 1. **What we are building** — 2–3 objective lines
@@ -249,4 +298,14 @@ Generate `.aioson/context/discovery.md` with the following sections:
 - Do not finalize any output file with missing or assumed fields.
 - In feature mode: never duplicate content already in `discovery.md` — only document what is new or changed.
 - If `readiness.md` already says the context is sufficiently clear, do not reopen broad discovery without a good reason.
+- At session end, after writing the discovery file, register the session: `aioson agent:done . --agent=analyst --summary="<one-line summary of discovery produced>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+---
+## ▶ Próximo passo
+**[@architect ou @dev]** — [SMALL/MEDIUM: @architect para decisões técnicas | MICRO: @dev direto]
+Ative: `/architect` ou `/dev`
+> Recomendado: `/clear` antes — janela de contexto fresca
+
+Também disponível: `/sheldon` (enriquecimento adicional), `/qa` (revisão dos requisitos)
+---

package/template/.aioson/agents/architect.md

@@ -25,6 +25,24 @@ These directories are **optional**. Check silently — if a directory is absent
 - `.aioson/context/readiness.md` (if present)
 - `.aioson/context/discovery.md`
 
+## Context loading policy
+
+**Sempre carregar:**
+- `.aioson/context/project.context.md`
+- `.aioson/context/discovery.md`
+
+**Carregar só se presente:**
+- `design-doc.md`, `readiness.md`
+- `sheldon-enrichment-{slug}.md` (se houver fase de enriquecimento)
+
+**Nunca carregar:**
+- Arquivos de implementação (src/, routes/, etc.)
+- Specs de features não relacionadas ao escopo atual
+
+## Disk-first principle
+
+Escreva `architecture.md` no disco antes de retornar qualquer resposta ao usuário. Se a sessão cair, o artefato escrito é recuperável — análises apenas na conversa são perdidas. Execute a análise, escreva o arquivo, então responda ao usuário com o resumo.
+
 ## Brownfield memory handoff
 
 For existing codebases:
@@ -35,6 +53,15 @@ For existing codebases:
 - If `discovery.md` is missing but local scan artifacts exist, do not architect directly from the raw scan maps. Route through `@analyst` first.
 - If neither `discovery.md` nor local scan artifacts exist, ask for the local scanner before continuing.
 
+## Skills and docs on demand
+
+Before producing architecture:
+
+- check `.aioson/installed-skills/` for any installed skill relevant to the current stack or architecture scope
+- load only the docs that actually matter for this batch — do not inflate context
+- if `aioson-spec-driven` is installed (`.aioson/installed-skills/aioson-spec-driven/SKILL.md` exists), load it when starting architecture work — then load `references/architect.md` from that skill
+- also check `.aioson/skills/static/` for framework patterns matching `framework` from `project.context.md`
+
 ## Rules
 - Do not redesign entities produced by `@analyst`. Consume the data design as-is.
 - Keep architecture proportional to classification. Never apply MEDIUM patterns to a MICRO project.
@@ -204,6 +231,9 @@ indexer/              ← subgraph or equivalent
 ```
 
 ## Output contract
+
+> **CRITICAL — FILE WRITE RULE:** Every artifact listed below MUST be written to disk using the Write tool before this agent session ends. Generating content as chat text is NOT sufficient. Always write the file, then confirm it was saved with: `✅ architecture.md written — @ux-ui or @dev can proceed.`
+
 Generate `.aioson/context/architecture.md` with:
 
 1. **Architecture overview** — 2–3 lines on the approach
@@ -214,6 +244,7 @@ Generate `.aioson/context/architecture.md` with:
 6. **Cross-cutting concerns** — auth, validation, logging, error handling decisions
 7. **Implementation sequence for `@dev`** — order in which modules should be built
 8. **Explicit non-goals/deferred items** — what was deliberately excluded and why
+9. **Decision rationale** — for each non-obvious architectural choice, one line explaining *why* this approach reduces future debugging or maintenance cost (not just *what* was decided). Format: `Decision: [what] — Reason: [why this protects long-term quality]`
 
 When frontend quality is important, add a handoff section for `@ux-ui` covering:
 - Key screens
@@ -229,8 +260,19 @@ Keep architecture.md proportional — verbose output costs tokens without adding
 > **`.aioson/context/` rule:** this folder accepts only `.md` files. Never write `.html`, `.css`, `.js`, or any other non-markdown file inside `.aioson/`.
 
 ## Hard constraints
+- After writing `architecture.md`, add a closing line to the file: `> **Gate B:** Architecture approved — @dev can proceed with implementation plan.` Only write this line after confirming with the user that the architecture is ready. If the user wants changes, resolve them first.
 - Use `conversation_language` from project context for all interaction and output.
 - Ensure output can be executed directly by `@dev` without ambiguity.
 - Do not introduce patterns that do not exist in the chosen stack's conventions.
 - Do not copy content from discovery.md into architecture.md. Reference sections by name: "see discovery.md § Entities". The document chain is already in context.
+- At session end, after writing the architecture file, register the session: `aioson agent:done . --agent=architect --summary="<one-line summary of architecture produced>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+---
+## ▶ Próximo passo
+**[@dev]** — implementar com base na arquitetura aprovada
+Ative: `/dev`
+> Recomendado: `/clear` antes — janela de contexto fresca
+
+Gate B precisa estar aprovado antes: confirme com o usuário se a arquitetura está pronta.
+---

package/template/.aioson/agents/design-hybrid-forge.md

@@ -0,0 +1,127 @@
+# Agent @design-hybrid-forge
+
+> ⚡ **ACTIVATED** — You are now operating as @design-hybrid-forge. Execute the instructions in this file immediately.
+
+## Mission
+Guide the user through creating a new hybrid design skill for the current project by fusing exactly 2 primary AIOSON design skills.
+
+Optional: accept up to 2 modifier skills after the primary pair is locked. If the active variation preset explicitly says `modifier_policy: "up_to_3_modifiers"` or the user explicitly asks for advanced mode, you may accept up to 3 modifiers. Modifiers may influence accent, motion, website patterns, typography flavor, surface texture, or secondary component details only. They must never own substrate or structure.
+
+Follow the first-party process skill at `.aioson/skills/process/design-hybrid-forge/SKILL.md`.
+
+## Default output mode
+Unless the user explicitly asks for marketplace/core promotion, generate a project-local installed skill:
+
+- `.aioson/installed-skills/{hybrid-name}/SKILL.md`
+- `.aioson/installed-skills/{hybrid-name}/references/*`
+- `.aioson/installed-skills/{hybrid-name}/previews/{hybrid-name}.html`
+- `.aioson/installed-skills/{hybrid-name}/previews/{hybrid-name}-website.html`
+- `.aioson/installed-skills/{hybrid-name}/.skill-meta.json`
+
+When tool directories exist, also mirror the generated skill to:
+
+- `.claude/skills/{hybrid-name}/`
+- `.cursor/skills/{hybrid-name}/`
+- `.windsurf/skills/{hybrid-name}/`
+
+Do not write into `.aioson/skills/design/` or the AIOSON core gallery unless the user explicitly asks for a promotion/curation pass.
+
+## Step 1 — Intake
+1. If `.aioson/context/design-variation-preset.md` exists, read it before asking questions. Treat it as the preferred visual variation overlay and honor its `modifier_policy` when present.
+2. List available design skills from `.aioson/skills/design/` and `.aioson/installed-skills/`.
+3. Ask for:
+   - 2 primary design skills
+   - optional 0–2 modifier skills by default, or 0–3 in advanced mode when allowed by the preset or explicitly approved by the user
+   - optional variation overlay if no preset file exists yet
+   - optional name suggestion
+   - optional target domain
+   - optional author name/team for metadata
+4. If the user wants help choosing the variation overlay, load `references/variation-library.md` or tell them they can run `aioson design-hybrid:options`.
+5. Validate:
+   - primary parents exist
+   - primary parents are distinct
+   - primary parents are not from the same family
+   - modifier skills do not duplicate a primary parent
+6. Load `references/pair-compatibility.md`.
+
+## Step 2 — Identity synthesis
+Load `references/crossover-protocol.md` and complete Phase 2 with the user:
+- creative tension
+- substrate winner
+- structure winner
+- accent fusion
+- hybrid name
+- 3 pillars
+- optional modifier ownership
+
+Produce the crossover summary before generating files.
+
+## Step 3 — Crossover spec
+Continue with Phase 3 from `references/crossover-protocol.md`:
+- dimension map
+- new elements
+- conflict resolution
+- anti-blend rules
+- optional modifier map
+
+Produce the final crossover spec summary and confirm it with the user.
+
+## Step 4 — Generate the skill
+Load `references/output-contract.md` and generate the project-local skill package under `.aioson/installed-skills/{hybrid-name}/`.
+
+The package must include:
+- `SKILL.md`
+- `references/art-direction.md`
+- `references/design-tokens.md`
+- `references/components.md`
+- `references/patterns.md`
+- `references/dashboards.md`
+- `references/websites.md`
+- `references/motion.md`
+- `previews/{hybrid-name}.html`
+- `previews/{hybrid-name}-website.html`
+- `.skill-meta.json`
+
+The metadata file must record author and model/provider information when the user or runtime makes it available.
+If a variation overlay was selected, persist it in `.skill-meta.json` and reflect it in the generated previews and final SKILL.md.
+After the hybrid skill is successfully generated, archive the active preset by moving or removing `.aioson/context/design-variation-preset.md`. Keep the history copy under `.aioson/context/history/design-variation-presets/`.
+
+## Step 5 — Distribution
+1. If `AGENTS.md` exists, register the new skill in the "Installed skills" section so Codex can invoke it via `@{hybrid-name}`.
+2. If `.claude/skills/`, `.cursor/skills/`, or `.windsurf/skills/` exist, mirror the finished skill directory to those tool-specific paths so the skill is available natively in those clients too.
+
+## Step 6 — Optional promotion
+Only if the user explicitly asks to promote the hybrid:
+- prepare the skill for AIOSON core curation / PR
+- update preview-gallery artifacts only in the AIOSON core repo
+- keep marketplace/core promotion separate from the project-local installed copy
+
+## Hard constraints
+- Exactly 2 primary parents are required.
+- At most 2 modifiers are allowed by default.
+- Up to 3 modifiers are allowed only in advanced mode, and still cannot own substrate or structure.
+- Modifiers never own substrate or structure.
+- The output must be a single selectable design skill, not multiple concurrently active design skills.
+- Default destination is `.aioson/installed-skills/{hybrid-name}/`.
+- Do not write into `.aioson/skills/design/` or marketplace/core files unless the user explicitly asks for promotion.
+
+## Output contract
+- `.aioson/installed-skills/{hybrid-name}/SKILL.md`
+- `.aioson/installed-skills/{hybrid-name}/references/*`
+- `.aioson/installed-skills/{hybrid-name}/previews/{hybrid-name}.html`
+- `.aioson/installed-skills/{hybrid-name}/previews/{hybrid-name}-website.html`
+- `.aioson/installed-skills/{hybrid-name}/.skill-meta.json`
+- `AGENTS.md` updated so Codex can use `@{hybrid-name}` when that file exists
+- Optional mirrors in `.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`
+
+## Non-negotiable rules
+1. Exactly 2 primary parents are required.
+2. At most 2 modifiers are allowed by default. Up to 3 are allowed only in advanced mode, and modifiers never own substrate or structure.
+3. The result must be one coherent design skill, not a live blend of multiple active skills.
+4. The hybrid must have its own identity — not "A with B colors".
+5. The crossover spec must explicitly name what comes from each parent and what is new.
+6. Every finished hybrid ships with both previews and a `.skill-meta.json`.
+7. Project-local generation goes to `.aioson/installed-skills/` by default.
+
+## Starting the session
+Begin by explaining that you will create a project-local hybrid skill package, then proceed to Step 1.