feat: Figma-specific agent prompts, auto-inject tokens, spec cap (#248)

* feat: add Figma-specific agent prompts in context builder

When sourceType is 'figma', inject domain-specific guidelines into the
agent preamble: auto-layout to flexbox/grid mapping, color token
extraction with @theme inline, typography fidelity, constraint
conversion, responsive breakpoints, and placeholder images.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: auto-inject Figma design tokens and cap spec size

When fetching from Figma in default 'spec' mode, also fetch design
tokens (CSS variables) and prepend them to the spec. The agent gets
ready-to-use tokens for @theme inline instead of parsing the raw tree.

Also pass all Figma CLI options through to fetchFromSource (previously
only label/status/limit/issue were passed).

Cap in-prompt spec at 15KB to reduce token waste — full spec remains
on disk in specs/ directory.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rubenmarcus

src/commands/run.ts

@@ -20,6 +20,7 @@ import { formatPresetsHelp, getPreset, type PresetConfig } from '../presets/inde
 import { autoInstallSkillsFromTask } from '../skills/auto-install.js';
 import { getSourceDefaults } from '../sources/config.js';
 import { fetchFromSource } from '../sources/index.js';
+import type { SourceOptions } from '../sources/types.js';
 import { detectPackageManager, formatRunCommand, getRunCommand } from '../utils/package-manager.js';
 import { showWelcome } from '../wizard/ui.js';
 
@@ -291,17 +292,47 @@ export async function runCommand(
         console.log(chalk.dim(`  Using default repo: ${projectId}`));
       }
 
-      const result = await fetchFromSource(options.from, projectId, {
+      const fetchOptions: SourceOptions = {
         label: options.label,
         status: options.status,
         limit: options.limit,
         issue: options.issue,
-      });
+        figmaMode: options.figmaMode,
+        figmaFramework: options.figmaFramework,
+        figmaFormat: options.figmaFormat,
+        figmaNodes: options.figmaNodes,
+        figmaScale: options.figmaScale,
+        figmaTarget: options.figmaTarget,
+        figmaPreview: options.figmaPreview,
+        figmaMapping: options.figmaMapping,
+      };
+
+      const result = await fetchFromSource(options.from, projectId, fetchOptions);
 
       spinner.succeed(`Fetched spec from ${result.source}`);
       sourceSpec = result.content;
       sourceTitle = result.title;
 
+      // Auto-inject design tokens when fetching Figma spec (default mode)
+      if (
+        options.from.toLowerCase() === 'figma' &&
+        (!options.figmaMode || options.figmaMode === 'spec')
+      ) {
+        try {
+          const tokensResult = await fetchFromSource(options.from, projectId, {
+            ...fetchOptions,
+            figmaMode: 'tokens',
+            figmaFormat: options.figmaFormat || 'css',
+          });
+          if (tokensResult.content) {
+            sourceSpec = `## Design Tokens\n\n${tokensResult.content}\n\n---\n\n${sourceSpec}`;
+            console.log(chalk.dim('  Auto-injected design tokens into spec'));
+          }
+        } catch {
+          // Tokens fetch failed — proceed with spec only
+        }
+      }
+
       // Extract issue reference from metadata for PR linking
       if (
         result.metadata?.type === 'github' &&
@@ -329,6 +360,22 @@ export async function runCommand(
       writeFileSync(specPath, sourceSpec);
       console.log(chalk.dim(`  Written to: ${specPath}`));
 
+      // Cap spec size for agent context (full spec remains on disk in specs/)
+      const MAX_SPEC_SIZE = 15_000;
+      if (sourceSpec.length > MAX_SPEC_SIZE) {
+        console.log(
+          chalk.yellow(
+            `  Spec is large (${(sourceSpec.length / 1024).toFixed(1)}KB). Trimming to ${(MAX_SPEC_SIZE / 1024).toFixed(0)}KB for agent context.`
+          )
+        );
+        const truncated = sourceSpec.slice(0, MAX_SPEC_SIZE);
+        const lastSection = truncated.lastIndexOf('\n## ');
+        sourceSpec =
+          lastSection > MAX_SPEC_SIZE * 0.7
+            ? `${truncated.slice(0, lastSection)}\n\n[Spec truncated — see specs/ directory for full design specification]`
+            : `${truncated}\n\n[Spec truncated — see specs/ directory for full design specification]`;
+      }
+
       // Prompt for project location when fetching from integration sources
       // Skip if --auto or --output-dir was provided
       const integrationSources = ['github', 'linear', 'notion', 'todoist'];

src/loop/context-builder.ts

@@ -35,6 +35,8 @@ export interface ContextBuildOptions {
   skipPlanInstructions?: boolean;
   /** Iteration log content from .ralph/iteration-log.md (previous iteration summaries) */
   iterationLog?: string;
+  /** Source integration type (github, linear, figma, notion, file) for source-specific prompts */
+  sourceType?: string;
 }
 
 export interface BuiltContext {
@@ -251,7 +253,21 @@ Design quality (IMPORTANT):
 - If no spec exists, choose ONE clear design direction (bold/minimal/retro/editorial/playful) and commit to it
 - Use a specific color palette with max 3-4 colors, not rainbow gradients
 - Avoid generic AI aesthetics: no purple-blue gradient backgrounds/text, no glass morphism/neumorphism, no Inter/Roboto defaults — pick distinctive typography (e.g. DM Sans, Playfair Display, Space Mono)
-`;
+${
+  opts.sourceType === 'figma'
+    ? `
+Figma-to-code guidelines (CRITICAL — your spec comes from a Figma design file):
+- AUTO-LAYOUT → FLEXBOX/GRID: "horizontal" = \`display: flex; flex-direction: row\`. "Vertical" = \`flex-direction: column\`. "Wrap" = \`flex-wrap: wrap\`. Use gap for item spacing.
+- COLORS: If the spec includes a "Design Tokens" section with CSS variables, put them in \`@theme inline { }\` and use Tailwind utilities (e.g. \`bg-primary\`, \`text-accent/80\`). If not, extract colors from the spec and create the @theme block yourself.
+- TYPOGRAPHY: Use the EXACT font names from the spec. Add Google Fonts import if needed. Do NOT substitute with generic fonts.
+- CONSTRAINTS: "Fill container" = \`width: 100%\` or \`flex: 1\`. "Fixed" = exact px value. "Hug contents" = \`width: fit-content\`.
+- SPACING: Apply padding/margin exactly as specified in the spec (top right bottom left notation).
+- RESPONSIVE: The Figma spec shows a single breakpoint. Add responsive breakpoints: stack columns on mobile, adjust font sizes, add appropriate padding.
+- IMAGES: Use placeholder images from https://placehold.co with exact dimensions from the spec (e.g. \`https://placehold.co/400x300\`).
+- FIDELITY: Match the design EXACTLY — don't add extra elements, animations, or decorations not in the spec.
+`
+    : ''
+}`;
 
   // Inject iteration log for iterations 2+ (gives agent memory of what happened before)
   const iterationLogSection =

src/loop/executor.ts

@@ -816,6 +816,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
       specSummary,
       skipPlanInstructions: options.skipPlanInstructions,
       iterationLog,
+      sourceType: options.sourceType,
     });
     const iterationTask = builtContext.prompt;