@bastani/atomic 0.6.8 → 0.7.0-2

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

@@ -1,508 +0,0 @@
-/**
- * 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",
-  source: import.meta.path,
-  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

@@ -1,159 +0,0 @@
-/**
- * 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;