@bastani/atomic 0.5.25 → 0.5.26-0

package/src/sdk/workflows/builtin/open-claude-design/copilot/index.ts

@@ -0,0 +1,507 @@
+/**
+ * open-claude-design / copilot
+ *
+ * Copilot replica of the Claude open-claude-design workflow. Orchestrates
+ * the design skill ecosystem (impeccable, critique, shape, polish, audit,
+ * etc.) into a deterministic 5-phase pipeline:
+ *
+ *   Phase 1: Design System Onboarding — extract tokens, build Design.md (HIL)
+ *   Phase 2: Import — aggregate text/URL/file references
+ *   Phase 3: Generation — produce first design version
+ *   Phase 4: Refinement Loop — bounded iterate with critique + user feedback
+ *   Phase 5: Export/Handoff — HTML export + Claude Code handoff bundle
+ *
+ * Copilot-specific concerns (see references/failure-modes.md):
+ *
+ *   • F5 — every `ctx.stage()` is a FRESH session. Every specialist receives
+ *     its required context verbatim in its first prompt.
+ *   • F1 — Copilot's last assistant turn is often empty when the agent ends
+ *     on a tool call. Use `getAssistantText()` (concatenation of every
+ *     top-level non-empty assistant turn, ignoring sub-agent
+ *     `parentToolCallId` traffic) instead of `.at(-1).data.content`.
+ *   • F9 — `s.save()` receives `SessionEvent[]` from `s.session.getMessages()`.
+ *
+ * Sub-agents are dispatched via `sessionOpts.agent` (the Copilot-native way
+ * to bind a session to a single named sub-agent). Permissions default to
+ * `approveAll` so headless stages run unattended.
+ *
+ * See claude/index.ts for the full topology diagram and design rationale.
+ *
+ * Run: atomic workflow -n open-claude-design -a copilot "design a dashboard"
+ */
+
+import { defineWorkflow } from "../../../index.ts";
+import type { SessionEvent } from "@github/copilot-sdk";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { MAX_REFINEMENTS, DESIGNS_DIR } from "../helpers/constants.ts";
+import {
+  loadDesignSystem,
+  persistDesignSystem,
+  readImpeccableMd,
+  slugifyPrompt,
+  ensureScratchDir,
+} from "../helpers/design-system.ts";
+import {
+  isUrl,
+  isFilePath,
+  aggregateImportResults,
+} from "../helpers/import.ts";
+import { isRefinementComplete } from "../helpers/validation.ts";
+import { writeHandoffBundle } from "../helpers/export.ts";
+import {
+  hasBlockingFindings,
+  renderScanFindings,
+  runImpeccableScan,
+} from "../helpers/scan.ts";
+import {
+  buildDesignLocatorPrompt,
+  buildDesignAnalyzerPrompt,
+  buildDesignPatternPrompt,
+  buildDesignSystemBuilderPrompt,
+  buildWebCapturePrompt,
+  buildFileParserPrompt,
+  buildGeneratorPrompt,
+  buildRefineFeedbackPrompt,
+  buildCritiquePrompt,
+  buildScreenshotValidationPrompt,
+  buildApplyChangesPrompt,
+  buildForcedFixPrompt,
+  buildExportPrompt,
+} from "../helpers/prompts.ts";
+
+/**
+ * Concatenate every top-level assistant turn's non-empty content. The final
+ * `assistant.message` of a Copilot turn is often empty when the agent ends
+ * on a tool call (F1), and sub-agent traffic is signalled by `parentToolCallId`.
+ */
+function getAssistantText(messages: SessionEvent[]): string {
+  return messages
+    .filter(
+      (m): m is Extract<SessionEvent, { type: "assistant.message" }> =>
+        m.type === "assistant.message" && !m.data.parentToolCallId,
+    )
+    .map((m) => m.data.content)
+    .filter((c) => c.length > 0)
+    .join("\n\n");
+}
+
+export default defineWorkflow({
+  name: "open-claude-design",
+  description:
+    "AI-powered design workflow: design system onboarding → import → generate → refine → export/handoff",
+  inputs: [
+    {
+      name: "prompt",
+      type: "text",
+      required: true,
+      description:
+        "What to design (e.g., 'a dashboard for monitoring API latency')",
+    },
+    {
+      name: "reference",
+      type: "text",
+      required: false,
+      description:
+        "URL, file path, or codebase path to import as design reference",
+    },
+    {
+      name: "output-type",
+      type: "enum",
+      required: false,
+      values: ["prototype", "wireframe", "page", "component"],
+      default: "prototype",
+      description: "Type of design output to generate",
+    },
+    {
+      name: "design-system",
+      type: "text",
+      required: false,
+      description: "Path to existing Design.md (skips onboarding if provided)",
+    },
+  ],
+})
+  .for<"copilot">()
+  .run(async (ctx) => {
+    const prompt = ctx.inputs.prompt ?? "";
+    const reference = ctx.inputs.reference ?? "";
+    const outputType = ctx.inputs["output-type"] ?? "prototype";
+    const designSystemPath = ctx.inputs["design-system"] ?? "";
+
+    const root = process.cwd();
+    const slug = slugifyPrompt(prompt);
+    const isoDate = new Date().toISOString().slice(0, 10);
+    const scratchDir = await ensureScratchDir(root);
+    const designDir = path.join(scratchDir, slug);
+    await mkdir(designDir, { recursive: true });
+
+    // ══════════════════════════════════════════════════════════════════════
+    // PHASE 1: Design System Onboarding
+    // ══════════════════════════════════════════════════════════════════════
+
+    let designSystem;
+
+    if (designSystemPath.trim()) {
+      // Skip onboarding — user provided an existing Design.md
+      designSystem = await loadDesignSystem(designSystemPath);
+    } else {
+      // Layer 1: Parallel headless codebase analysis
+      const [locator, analyzer, patterns] = await Promise.all([
+        ctx.stage(
+          {
+            name: "ds-locator",
+            headless: true,
+            description: "Locate design files and tokens",
+          },
+          {},
+          { agent: "codebase-locator" },
+          async (s) => {
+            await s.session.send({
+              prompt: buildDesignLocatorPrompt({ root }),
+            });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+        ctx.stage(
+          {
+            name: "ds-analyzer",
+            headless: true,
+            description: "Analyze design tokens and patterns",
+          },
+          {},
+          { agent: "codebase-analyzer" },
+          async (s) => {
+            await s.session.send({
+              prompt: buildDesignAnalyzerPrompt({ root }),
+            });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+        ctx.stage(
+          {
+            name: "ds-patterns",
+            headless: true,
+            description: "Find existing design patterns",
+          },
+          {},
+          { agent: "codebase-pattern-finder" },
+          async (s) => {
+            await s.session.send({
+              prompt: buildDesignPatternPrompt({ root }),
+            });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+      ]);
+
+      // Layer 2: Visible stage with HIL — presents findings, asks user to
+      // approve/modify each design element category
+      await ctx.stage(
+        {
+          name: "design-system-builder",
+          description: "Build design system with user approval (HIL)",
+        },
+        {},
+        {},
+        async (s) => {
+          await s.session.send({
+            prompt: buildDesignSystemBuilderPrompt({
+              root,
+              locatorOutput: locator.result,
+              analyzerOutput: analyzer.result,
+              patternsOutput: patterns.result,
+              existingImpeccable: await readImpeccableMd(root),
+            }),
+          });
+          s.save(await s.session.getMessages());
+        },
+      );
+
+      // Deterministic: read back the Design.md the agent wrote
+      designSystem = await persistDesignSystem(root);
+    }
+
+    // ══════════════════════════════════════════════════════════════════════
+    // PHASE 2: Import
+    // ══════════════════════════════════════════════════════════════════════
+
+    const importResults = await Promise.all([
+      // Web capture (only if reference is a URL)
+      isUrl(reference)
+        ? ctx.stage(
+            {
+              name: "web-capture",
+              headless: true,
+              description: "Capture web reference via playwright",
+            },
+            {},
+            { agent: "codebase-online-researcher" },
+            async (s) => {
+              await s.session.send({
+                prompt: buildWebCapturePrompt({
+                  url: reference,
+                  screenshotDir: scratchDir,
+                }),
+              });
+              const messages = await s.session.getMessages();
+              s.save(messages);
+              return getAssistantText(messages);
+            },
+          )
+        : null,
+
+      // File parser (only if reference is a file path)
+      isFilePath(reference)
+        ? ctx.stage(
+            {
+              name: "file-parser",
+              headless: true,
+              description: "Parse reference document",
+            },
+            {},
+            { agent: "codebase-analyzer" },
+            async (s) => {
+              await s.session.send({
+                prompt: buildFileParserPrompt({ filePath: reference }),
+              });
+              const messages = await s.session.getMessages();
+              s.save(messages);
+              return getAssistantText(messages);
+            },
+          )
+        : null,
+    ]);
+
+    // Deterministic aggregation
+    const importContext = aggregateImportResults({
+      prompt,
+      reference,
+      webCapture: importResults[0]?.result ?? null,
+      fileParse: importResults[1]?.result ?? null,
+    });
+
+    // ══════════════════════════════════════════════════════════════════════
+    // PHASE 3: Generation
+    // ══════════════════════════════════════════════════════════════════════
+
+    await ctx.stage(
+      { name: "generator", description: "Generate first design version" },
+      {},
+      {},
+      async (s) => {
+        await s.session.send({
+          prompt: buildGeneratorPrompt({
+            prompt,
+            outputType,
+            designSystem,
+            importContext,
+            root,
+            outputDir: designDir,
+          }),
+        });
+        s.save(await s.session.getMessages());
+      },
+    );
+
+    // ══════════════════════════════════════════════════════════════════════
+    // PHASE 4: Refinement Loop
+    // ══════════════════════════════════════════════════════════════════════
+
+    for (let iteration = 1; iteration <= MAX_REFINEMENTS; iteration++) {
+      // Step 1: Collect user feedback via HIL
+      const feedback = await ctx.stage(
+        {
+          name: `user-feedback-${iteration}`,
+          description: `Collect refinement feedback (iteration ${iteration})`,
+        },
+        {},
+        {},
+        async (s) => {
+          await s.session.send({
+            prompt: buildRefineFeedbackPrompt({
+              prompt,
+              designDir,
+              iteration,
+              maxIterations: MAX_REFINEMENTS,
+            }),
+          });
+          const messages = await s.session.getMessages();
+          s.save(messages);
+          return getAssistantText(messages);
+        },
+      );
+
+      // Check if user signaled "done" via HIL response
+      if (isRefinementComplete(feedback.result)) break;
+
+      // Step 2: Parallel validation — critique + screenshot
+      const [critiqueResult, screenshotResult] = await Promise.all([
+        ctx.stage(
+          {
+            name: `critique-${iteration}`,
+            headless: true,
+            description: `Design critique (iteration ${iteration})`,
+          },
+          {},
+          { agent: "reviewer" },
+          async (s) => {
+            await s.session.send({
+              prompt: buildCritiquePrompt({
+                designDir,
+                designSystem,
+                userFeedback: feedback.result,
+              }),
+            });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+        ctx.stage(
+          {
+            name: `screenshot-${iteration}`,
+            headless: true,
+            description: `Visual validation (iteration ${iteration})`,
+          },
+          {},
+          { agent: "codebase-analyzer" },
+          async (s) => {
+            await s.session.send({
+              prompt: buildScreenshotValidationPrompt({
+                designDir,
+                scratchDir,
+              }),
+            });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+      ]);
+
+      // Step 3: Deterministic scan — surface banned anti-patterns so the
+      // apply-changes stage can fix them alongside user feedback. No LLM
+      // call; runs the `impeccable detect` CLI directly.
+      const scan = await runImpeccableScan(designDir);
+      const scanFindings =
+        scan.available && scan.findings.length > 0
+          ? renderScanFindings(scan.findings)
+          : scan.available
+            ? ""
+            : `(scanner unavailable: ${scan.reason} — proceed without scan input)`;
+
+      // Step 4: Apply changes based on feedback + critique + scanner findings
+      await ctx.stage(
+        {
+          name: `apply-changes-${iteration}`,
+          description: `Apply refinements (iteration ${iteration})`,
+        },
+        {},
+        {},
+        async (s) => {
+          await s.session.send({
+            prompt: buildApplyChangesPrompt({
+              prompt,
+              designDir,
+              designSystem,
+              userFeedback: feedback.result,
+              critiqueOutput: critiqueResult.result,
+              screenshotOutput: screenshotResult.result,
+              scanFindings,
+              iteration,
+            }),
+          });
+          s.save(await s.session.getMessages());
+        },
+      );
+    }
+
+    // ══════════════════════════════════════════════════════════════════════
+    // Hard enforcement gate — runs before export, independent of the
+    // refinement loop's exit condition. Guarantees no design ships with
+    // scanner findings even if the user approved early or MAX_REFINEMENTS
+    // was reached with the agent still introducing banned patterns.
+    // ══════════════════════════════════════════════════════════════════════
+
+    const preExportScan = await runImpeccableScan(designDir);
+    if (hasBlockingFindings(preExportScan)) {
+      const findings = (
+        preExportScan as Extract<typeof preExportScan, { available: true }>
+      ).findings;
+      const findingsText = renderScanFindings(findings);
+
+      await ctx.stage(
+        {
+          name: "forced-fix",
+          description: "Remove banned anti-patterns before export",
+        },
+        {},
+        {},
+        async (s) => {
+          await s.session.send({
+            prompt: buildForcedFixPrompt({
+              designDir,
+              designSystem,
+              scanFindings: findingsText,
+            }),
+          });
+          s.save(await s.session.getMessages());
+        },
+      );
+
+      const rescan = await runImpeccableScan(designDir);
+      if (hasBlockingFindings(rescan)) {
+        const remaining = (
+          rescan as Extract<typeof rescan, { available: true }>
+        ).findings;
+        throw new Error(
+          `open-claude-design: export blocked — ${remaining.length} ` +
+            `banned anti-pattern(s) remain after forced fix:\n` +
+            renderScanFindings(remaining),
+        );
+      }
+    }
+
+    // ══════════════════════════════════════════════════════════════════════
+    // PHASE 5: Export / Handoff
+    // ══════════════════════════════════════════════════════════════════════
+
+    const finalDesignDir = path.join(root, DESIGNS_DIR, `${isoDate}-${slug}`);
+
+    await ctx.stage(
+      {
+        name: "exporter",
+        description: "Export design and create handoff bundle",
+      },
+      {},
+      {},
+      async (s) => {
+        await s.session.send({
+          prompt: buildExportPrompt({
+            prompt,
+            designDir,
+            finalDesignDir,
+            designSystem,
+            outputType,
+          }),
+        });
+        s.save(await s.session.getMessages());
+      },
+    );
+
+    // Deterministic: package handoff bundle (copies Design.md, writes
+    // handoff-prompt.md and README.md — no LLM call)
+    await writeHandoffBundle(finalDesignDir, {
+      designSystem,
+      prompt,
+      outputType,
+    });
+  })
+  .compile();

package/src/sdk/workflows/builtin/open-claude-design/helpers/constants.ts

@@ -0,0 +1,159 @@
+/**
+ * Constants for the open-claude-design workflow.
+ *
+ * Design-rule constants (REFLEX_FONTS, IMPECCABLE_BANS, DESIGN_DONTS) mirror
+ * the canonical impeccable skill shipped at
+ * `~/.claude/skills/impeccable/SKILL.md`. The skill itself is only loaded
+ * opportunistically by the agent — so we inline the load-bearing rules here
+ * to guarantee every generation/refinement/critique turn sees them even if
+ * the skill is missing or fails to load. Re-sync when the skill updates.
+ */
+
+/** Maximum refinement iterations before the loop exits unconditionally. */
+export const MAX_REFINEMENTS = 5;
+
+/**
+ * Headless stages: structured analysis, tool orchestration, rubric-following.
+ * Uses Sonnet for cost efficiency. Bypasses permissions for unattended operation.
+ */
+export const HEADLESS_OPTS = {
+  permissionMode: "bypassPermissions",
+  allowDangerouslySkipPermissions: true,
+  model: "sonnet",
+} as const;
+
+/**
+ * Visible/creative stages: inherit orchestrator model (Opus).
+ * No model override — inherits from the parent session.
+ */
+export const VISIBLE_OPTS = {
+  permissionMode: "bypassPermissions",
+  allowDangerouslySkipPermissions: true,
+} as const;
+
+/** Name of the design system file written to the project root. */
+export const DESIGN_SYSTEM_FILENAME = "Design.md";
+
+/** Directory under project root where final design outputs are stored. */
+export const DESIGNS_DIR = "research/designs";
+
+/** Name of the existing impeccable brand context file. */
+export const IMPECCABLE_FILENAME = ".impeccable.md";
+
+/**
+ * Structured ban — rendered into generation/refinement/critique prompts as a
+ * `rule` (what is forbidden) plus `detail` (the CSS pattern + the rewrite).
+ */
+export interface ImpeccableBan {
+  readonly id: string;
+  readonly rule: string;
+  readonly detail: string;
+}
+
+/**
+ * Absolute CSS bans from the canonical impeccable skill's `<absolute_bans>`
+ * section. These are the two patterns that the skill flags as "NEVER
+ * acceptable" regardless of color, radius, or CSS variable naming. If you
+ * change this list, re-sync with `~/.claude/skills/impeccable/SKILL.md`.
+ */
+export const IMPECCABLE_BANS: readonly ImpeccableBan[] = [
+  {
+    id: "side-stripe-borders",
+    rule: "BAN 1 — Side-stripe borders on cards/list items/callouts/alerts",
+    detail:
+      "PATTERN: `border-left:` or `border-right:` with width greater than 1px. " +
+      "Forbidden for any color, any CSS variable name (including `--color-warning`, " +
+      "`--color-accent`, `--color-primary`). REWRITE: use a different element " +
+      "structure entirely — full borders, background tints, leading icons, numbers, " +
+      "or no visual indicator at all. Do NOT just swap to `box-shadow: inset`.",
+  },
+  {
+    id: "gradient-text",
+    rule: "BAN 2 — Gradient text",
+    detail:
+      "PATTERN: `background-clip: text` (or `-webkit-background-clip: text`) combined " +
+      "with a `linear-gradient`, `radial-gradient`, or `conic-gradient` background. " +
+      "Forbidden on any text element — headings, metrics, or inline spans. " +
+      "REWRITE: solid colors only for text.",
+  },
+] as const;
+
+/**
+ * Canonical reflex fonts from the impeccable skill's
+ * `<reflex_fonts_to_reject>` list. These are the training-data defaults that
+ * create monoculture across projects; every one of them is banned.
+ */
+export const REFLEX_FONTS: readonly string[] = [
+  "Fraunces",
+  "Newsreader",
+  "Lora",
+  "Crimson",
+  "Crimson Pro",
+  "Crimson Text",
+  "Playfair Display",
+  "Cormorant",
+  "Cormorant Garamond",
+  "Syne",
+  "IBM Plex Mono",
+  "IBM Plex Sans",
+  "IBM Plex Serif",
+  "Space Mono",
+  "Space Grotesk",
+  "Inter",
+  "DM Sans",
+  "DM Serif Display",
+  "DM Serif Text",
+  "Outfit",
+  "Plus Jakarta Sans",
+  "Instrument Sans",
+  "Instrument Serif",
+] as const;
+
+/**
+ * Non-ban DON'Ts distilled from the impeccable skill sections on Typography,
+ * Color, Layout/Space, Motion, UX Writing, and Responsive. These are not
+ * absolute bans, but they are the recognizable AI fingerprints from
+ * 2024-2025 and must be avoided in generated designs.
+ */
+export const DESIGN_DONTS: readonly string[] = [
+  // Typography
+  "Do not use monospace typography as lazy shorthand for 'technical/developer' vibes.",
+  "Do not put large icons with rounded corners above every heading.",
+  "Do not use only one font family for the entire page — pair a distinctive display font with a refined body font.",
+  "Do not use a flat type hierarchy where sizes are too close together — aim for at least a 1.25 ratio between steps.",
+  "Do not set long body passages in uppercase — reserve all-caps for short labels and headings.",
+  // Color & theme
+  "Do not use pure black (#000) or pure white (#fff) — always tint toward the brand hue.",
+  "Do not use the AI color palette (cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds).",
+  "Do not default to dark mode with glowing accents, or to light mode 'to be safe' — derive theme from audience and viewing context.",
+  "Do not use gray text on colored backgrounds — use a shade of the background color instead.",
+  // Layout & space
+  "Do not wrap everything in cards — not everything needs a container.",
+  "Do not nest cards inside cards.",
+  "Do not use identical card grids (same-sized cards with icon + heading + text, repeated endlessly).",
+  "Do not use the hero metric layout template (big number, small label, supporting stats, gradient accent).",
+  "Do not center everything — left-aligned text with asymmetric layouts feels more designed.",
+  "Do not use the same spacing everywhere — create rhythm with tight groupings and generous separations.",
+  "Do not let body text wrap beyond ~80 characters per line — use a max-width like 65–75ch.",
+  // Motion
+  "Do not animate layout properties (width, height, padding, margin) — use transform and opacity only.",
+  "Do not use bounce or elastic easing — real objects decelerate smoothly.",
+  // UX writing
+  "Do not repeat information (redundant headers, intros that restate the heading).",
+  "Do not make every button primary — use ghost buttons, text links, and secondary styles for hierarchy.",
+  // Responsive
+  "Do not hide critical functionality on mobile — adapt the interface, don't amputate it.",
+] as const;
+
+/**
+ * Command invocation for the impeccable scanner. The correct subcommand is
+ * `detect`; a bare `impeccable --json` just prints the top-level help.
+ * Exit code is always 0 — callers must parse the JSON array and check length
+ * to know whether findings exist.
+ */
+export const IMPECCABLE_SCAN_CMD = [
+  "bunx",
+  "impeccable",
+  "detect",
+  "--json",
+] as const;