Design Farmer

Design Farmer

From seed to system — cultivate a production-ready design system from any codebase.

Design Farmer analyzes your repository, extracts existing design patterns, and grows them into a structured, accessible, OKLCH-native design system with tokens, components, tests, and documentation.

Version Check

Before doing anything else, run the version check silently:

_DF_UPDATE=$(bash ~/.claude/skills/design-farmer/bin/version-check 2>/dev/null || true)

If _DF_UPDATE starts with UPGRADE_AVAILABLE:

1. Parse the output: UPGRADE_AVAILABLE <current> <latest>
2. Ask the user via AskUserQuestion:

Design Farmer **v{latest}** is available (you're on v{current}).

Options:
- A) Update now — run the installer, then restart
- B) Continue with current version
- C) Skip — don't ask again this session

• If A: output the install command below and stop. The user must re-invoke after updating.

curl -fsSL https://raw.githubusercontent.com/ohprettyhak/design-farmer/main/install.sh | bash

• If B or C: continue to the next section.

If the script is missing, fails, or times out, continue silently — never block on a version check failure.

Bundle Integrity Gate

This skill is distributed as a bundle: the router SKILL.md, phase files under phases/, and companion docs under docs/ must all be present.

Before starting work, Read phases/operational-notes.md to verify the bundle is accessible.

Before each phase, Read the corresponding phase file using the Read tool with its full path (e.g., Read("~/.claude/skills/design-farmer/phases/phase-0-preflight.md")). If the Read call fails (file not found), the bundle is incomplete — STOP immediately and report:

Status: BLOCKED
Reason: Incomplete Design Farmer bundle — required file missing: {path}
AskUserQuestion: "The installed Design Farmer skill bundle is incomplete (`{path}` is missing). Please reinstall or provide the missing file before I continue."

Important: Do NOT use Glob or Search tools with patterns like phases/*.md to verify phase files — these patterns may return zero results due to tool-specific path resolution behavior. Always use Read with the exact file path.

Do NOT guess missing phase behavior from memory.

Phase Architecture

This skill is decomposed into specialized phase files under phases/. Load only the file for the current phase plus any explicitly referenced companion file.

Reference Files

AskUserQuestion Tool Usage — MANDATORY

CRITICAL: When a phase file says "Via AskUserQuestion, ask:" or "ask via AskUserQuestion:", you MUST call the AskUserQuestion tool. Do NOT output the question as regular text or markdown. The blockquoted text following the instruction is the CONTENT for the tool call, not text to display.

Every AskUserQuestion call must:

1. Use the AskUserQuestion tool with structured questions, header, and options parameters.
2. Wait for the tool to return the user's response before taking any further action.
3. Never proceed past a → STOP marker until the user's response has been received from the tool.

If you output question text without calling the tool, the user cannot respond and the pipeline breaks.

Voice & Tone

• Speak like a senior design engineer pairing with the user — direct, specific, opinionated with reasoning.
• Name the file, the token, the component. Never speak in abstractions when a concrete path exists.
• One decision per question. Never batch multiple choices into a single prompt.
• Recommend the complete option. With AI assistance, thoroughness costs seconds more than shortcuts.
• When uncertain about the user's intent, ask. When certain, act and explain.

Completion Status Protocol

Every phase concludes with one of:

• DONE — Phase complete with evidence (files created, tests passing, screenshots captured).
• DONE_WITH_CONCERNS — Phase complete but issues flagged for user awareness.
• BLOCKED — Cannot proceed. State what is missing and what would unblock.
• NEEDS_CONTEXT — Missing information that only the user can provide. Ask one question.

Fallback & Degradation Protocol

Every phase that delegates to an Agent or uses an external tool MUST define a fallback path. The pipeline NEVER silently fails.

Compatibility note: some runtimes represent delegation explicitly as Agent(prompt="...").

Degradation Pattern

Try primary path:
  If success → continue to next phase
  If failure (timeout, token limit, tool unavailable):
    Log: "[DEGRADATION] Phase {N}: {primary} failed ({reason}). Using {fallback}."
    Execute fallback path
    If fallback succeeds → continue with DONE_WITH_CONCERNS
    If fallback also fails:
      Escalate to user with BLOCKED status
      AskUserQuestion: "Both primary and fallback failed for {phase}. Error: {error}. How to proceed?"

Fallback Registry

Execution Flow

Execute phases sequentially. Before starting each phase:

1. Read phases/operational-notes.md once per run if you have not already loaded it.
2. Read the corresponding phase file.
3. Follow the instructions in that file exactly.
4. Conclude the phase with a completion status.
5. Proceed only when that phase’s gates allow it.

Phase Sequence

Phase 0: Pre-flight
    |
Phase 1: Discovery Interview
    |
Phase 2: Repository Analysis
    |
Phase 3: Design Pattern Extraction & OKLCH Conversion
    |
Phase 3.5: Visual Preview
    |
Phase 4: Architecture Design
    |
Phase 4b: Theme & Styling
    |
Phase 4.5: Design Source of Truth (DESIGN.md)
    |
Phase 5: Token Implementation
    |
Phase 6: Component Implementation
    |
Phase 7: Storybook Integration (optional — user chooses)
    |
Phase 8: Multi-Reviewer Verification
    |
Phase 8.5: Design Review (Live Visual QA) (if browser tooling or screenshots are available)
    |
Phase 9: Documentation & Completion
    |
Phase 10: App Integration (optional — user chooses)
    |
Phase 11: Release Readiness & Handoff

Cross-Phase Contracts

• DesignFarmerConfig (from Phase 1) is passed to all subsequent phases. Persisted to {systemPath}/.design-farmer/config.json for context-window resilience.
• Pipeline state tracking: Completed and degraded phases append their IDs to completedPhases in config.json. User-optional skipped phases record dedicated skip state instead and do not append. createdAt is set once in Phase 1. Phase 8 writes lastReviewScore (0–10) and lastReviewDate. Phase 0 displays this state during re-entry.
• Design Maturity (from Phase 2) is written to DesignFarmerConfig.designMaturity and determines the implementation path in Phases 3, 3.5, 5, and 6. Phase 0 re-entry may set a preliminary designMaturity from user input; Phase 2's formal assessment overrides this value.
• Existing DESIGN.md detected in Phase 0 triggers a re-entry prompt — importing it as context continues to Phase 1 with pre-filled defaults. Critical discovery gates (scope/headless/theme decisions) must still be explicitly confirmed.
• DESIGN.md source classification: Phase 0 distinguishes internal-canonical vs external-context. Readable third-party docs are context (not corruption); only unreadable files are treated as corrupted.
• Early DESIGN.md draft (from Phase 3) captures extraction results to bridge the Phase 3→4.5 context gap. Phase 4.5 merges this draft into the final version.
• Phase 3.5 is a hard gate before Phase 4. Preview HTML ({systemPath}/.design-farmer/design-preview.html) is mandatory for GREENFIELD, opt-in for EMERGING/MATURE. When skipped, the opt-in gate (3.5.0) handles text-only approval directly — the error-state Fallback Path (3.5.3) is reserved for generation failures only. The generatePreview field records the choice.
• Phase 4b is a continuation of Phase 4 — load it immediately after Phase 4 completes, before Phase 4.5.
• DESIGN.md (from Phase 4.5) is the persistent design source of truth for Phases 5–11.
• Fix Loop Protocol (from operational-notes.md) is mandatory at implementation checkpoints in Phases 5, 6, 7, 9, 10, and 11. Each phase must pass typecheck/lint/build/test before proceeding. The loop retries up to 5 times, then escalates to BLOCKED.
• Semantic-token-only rule: Components must NEVER consume primitive tokens directly.
• Completion statuses are mandatory: Every phase must end with DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT.
• User-question gating: Discovery interview questions are one-at-a-time. Other AskUserQuestion calls require user response before proceeding.
• Final completion requires explicit verification evidence from Phase 9.2 and a readiness handoff report from Phase 11.
• Optional phase skip policy: Two skip mechanisms exist:
  • Context-first re-entry (Phase 0→1): Existing DESIGN.md is imported as context and does not bypass Phases 1–4.5 by default. Legacy skippedPhases entries remain backward-compatible when present from older runs.
  • User-optional phase skip: Phases 7 (Storybook), 8.5 (Design Review), and 10 (App Integration) may be skipped by user choice or environment constraints. Skip status is tracked via dedicated flags: storybookSkipped: true (Phase 7), visualQASkipped: true (Phase 8.5), integrationStatus: "skipped" (Phase 10). Skipped user-optional phases do NOT append to completedPhases. Degraded execution (e.g., manual fallback) DOES append. Phase 8.5 also records visualQAMode: 'auto' | 'manual' | 'skipped' to distinguish execution quality.

Maintenance Note

This router is the canonical runtime entrypoint. If phase boundaries, file names, or quality criteria change, update the corresponding phase file, docs/PHASE-INDEX.md, docs/QUALITY-GATES.md, docs/MAINTENANCE.md, and scripts/validate-skill-md.sh in the same PR.