design

Phase 2 of the Forge pipeline. CTO and Designer collaborate as a persistent Team (via TeamCreate + SendMessage) to produce architecture, code rules, interface contracts, and design specs. Analyst grounds them in the existing codebase before they begin. Researcher supports external option comparison, but CTO and Designer keep decision ownership. Every technical claim is verified via context7 before being committed to the design. No guessing — only evidence-backed decisions. In Autonomous Company Mode, design is an internal readiness gate by default, not a customer approval checkpoint. When design starts from a redesign or UX-improvement request, the design phase must first open the user's UX thinking before jumping into components and tokens.

<Use_When>

• After Phase 1 (discovery) completes
• state.json phase=2
• After forge:analyze writes .forge/design/ux-analysis.md for a design-improvement request </Use_When>

<Core_Rules>

1. CTO MUST use context7 to verify every framework pattern before deciding

   • No "I think Next.js supports..." — look it up, cite the doc
   • If context7 can't confirm it, flag it as unverified

2. Use Researcher before locking external choices that are still open

   • Researcher compares viable frameworks, packages, vendors, or service options
   • CTO still makes the final architecture call

3. Designer MUST define every component completely:

   • Size, color, spacing, typography, border radius
   • All states: default, hover, active, disabled, loading, error, empty
   • Responsive breakpoints: mobile, tablet, desktop

4. CTO and Designer MUST cross-review each other's work

   • CTO reviews design feasibility: can this be built with chosen stack?
   • Designer reviews architecture: does it support all UI needs?

5. If design and tech conflict → resolve internally first

   • Never silently drop a feature because it's "hard"
   • Never force a design that the architecture can't support
   • Escalate to the client only if the blocker is truly customer-owned:
     • unresolved business priority
     • subjective direction with no responsible default
     • incompatible requirements that only the client can choose between

6. code-rules.md MUST have examples (good + bad) for every rule:

   Example format:

   Rule: Component files use PascalCase
   
   GOOD:
   UserProfile.tsx
   PaymentForm.tsx
   
   BAD:
   userProfile.tsx
   payment-form.tsx
   

</Core_Rules>

<Progressive_Disclosure>

• Load references/design-deliverables.md for the complete deliverable and cross-review checklist.
• Load references/research-integration.md when discovery hands off research or design needs external option comparison.
• Load agents/design-team.md for the 4-phase CTO↔Designer collaboration protocol.
• Load agents/analyst.md for codebase analysis tool reference. </Progressive_Disclosure>

<Team_Collaboration> When both CTO and Designer are needed (the common case):

• Use TeamCreate(team_name="forge-design") to create a design team
• Add CTO and Designer as team members via Agent tool with team_name parameter
• They collaborate via SendMessage for real-time cross-review
• Reference: agents/design-team.md for the 4-phase collaboration protocol Phase 1: Parallel Analysis (CTO: architecture, Designer: UX) Phase 2: Cross-Review via SendMessage Phase 3: Convergence (resolve conflicts) Phase 4: Handoff (unified design artifact)

When only CTO is needed (pure backend/API project):

• Dispatch CTO as individual subagent (no Team needed)

When only Designer is needed (UI-only change):

• Dispatch Designer as individual subagent (no Team needed) </Team_Collaboration>

<Researcher_Scope> Researcher is for EXTERNAL investigation only:

• Dispatched when CTO or Designer needs external comparison (libraries, frameworks, vendors)
• NOT for internal codebase analysis — that is the Analyst's job
• Researcher uses context7 + WebSearch; Analyst uses codebase-memory-mcp
• CTO still makes the final architecture call after reviewing Researcher output </Researcher_Scope>

-1. **Analysis freshness check** - Read analysis metadata — if saved codebase analysis is stale or missing for a non-greenfield path, route to `forge:analyze` first.

-0a. UX Opening Mode (redesign / design-improvement path) If .forge/design/ux-analysis.md exists and the saved analysis type is design-improvement:

• Designer leads a short UX-opening interview before component design starts
• Ask only enough to unlock direction:
  • current frustration / stuck point
  • desired feeling after the redesign
  • must-not-break flows
  • safe-to-change areas
• Keep the structure consistent across locales (ko/en/ja/zh)
• Save the result to .forge/design/ux-brief.md
• CTO and Designer use ux-brief.md as an input artifact for the rest of design
• This is not a full discovery interview; it is a direction-opening layer for design improvement only

-0. Handoff Interview — Design Intake (tier-aware, see references/handoff-interview.md) a. CTO reads spec.md; at the top of .forge/design/architecture.md (draft), records any blockers (missing API boundaries, unspecified perf budgets, ambiguous integration points) and any consequential assumptions. Free-form bullets, no structured Q template. b. Designer reads spec.md; at the top of .forge/design/components.md (draft), records any UX blockers (missing flows, unclear navigation, ambiguous states) and consequential assumptions. c. For each blocker, the author pings the direct owner via SendMessage (PM for spec intent, CEO only if ownership is ambiguous or customer-owned). Non-consequential uncertainty is converted into fact-check tasks or QA checks, not questions. d. At full tier only, additionally write .forge/handoff-interviews/design.md consolidating blockers + assumptions (phase gate enforces this). e. Blockers resolved → design work begins. No separate understanding statement; the draft architecture / components artifact is the understanding record.

-0b. Lessons Check (harness learning) - CTO loads relevant pattern lessons from ~/.claude/forge-lessons/ when present - Known bug patterns for the chosen tech stack → add preventive rules to code-rules.md - Known QA-failure patterns → add to contracts as explicit constraints - Known estimation gaps → flag to CEO for scope calibration

0. Codebase Analysis (skip if greenfield project): Dispatch Analyst (forge:analyst) to map existing architecture:

   • Uses codebase-memory-mcp: get_architecture, search_graph, trace_call_path
   • Produces: module map, dependency graph, coupling hotspots, architectural patterns
   • Output saved to .forge/design/codebase-analysis.md
   • CTO uses this as input for architecture decisions
   • Designer uses this to understand existing UI patterns and components

1. Create design team and dispatch agents:

   • Use TeamCreate(team_name="forge-design") to create a persistent design team
   • Add CTO and Designer as team members via Agent tool with team_name parameter
   • Dispatch Researcher in parallel only when discovery handed off an open research brief or a design decision depends on outside option comparison
   • Researcher informs the choice; CTO still decides
   • If only CTO or only Designer is needed, dispatch as individual subagent instead

2. CTO produces (informed by Analyst's codebase-analysis.md): a. .forge/design/architecture.md

   • Tech stack with version numbers (verified via context7)
   • Directory structure
   • Data flow diagram (text-based)
   • API route inventory
   • State management strategy b. .forge/code-rules.md
   • Naming conventions (files, variables, components)
   • Import ordering rules
   • Error handling patterns
   • Each rule with GOOD + BAD examples c. .forge/contracts/*.ts
   • TypeScript interfaces for all shared boundaries
   • API request/response types
   • Database model types
   • Component prop types

3. Designer produces (informed by Analyst's codebase-analysis.md): a. .forge/design/components.md

   • Component inventory (every UI element)
   • Per-component spec: size, color, spacing, states
   • Interaction patterns (click, hover, drag, swipe)
   • Accessibility requirements (ARIA roles, keyboard nav) b. .forge/design/tokens.json
   • Color palette (primary, secondary, neutral, semantic)
   • Typography scale (font family, sizes, weights, line heights)
   • Spacing scale (4px base grid)
   • Border radius values
   • Shadow definitions
   • Breakpoints c. .forge/design/ux-brief.md remains the source of truth for:
   • target users
   • desired feeling
   • critical flows
   • safe-to-change areas
   • non-negotiables

4. Cross-Review via Team:

   • CTO sends architecture proposal to Designer: SendMessage(to="designer", ...) "Please verify all components can be implemented with this architecture"
   • Designer sends UX proposal to CTO: SendMessage(to="cto", ...) "Supporting this interaction flow requires these APIs"
   • They negotiate directly until convergence
   • Conflict resolution: CTO decides technical feasibility, Designer decides UX quality
   • If deadlocked: escalate to CEO (rare)
   • If Researcher was used, CTO folds the brief into the architecture rationale and flags any remaining unknowns

5. Internal design-readiness gate:

   • CTO confirms the architecture is implementable at the chosen scale
   • Designer confirms the design covers required flows and states
   • Fact checker confirms technical claims are evidence-backed
   • If the gate fails, revise internally before moving on
   • Escalate to the client only for genuine customer-owned blockers

6. Fact checker validates all technical claims:

   • Every package referenced exists and is at claimed version
   • Every API pattern works as described (verified via context7)
   • Every TypeScript type is syntactically valid
   • Every framework feature is available in the chosen version

7. Optional client check-in only when needed:

   • If a real business-level design blocker remains, present it clearly in customer language
   • Otherwise keep the design decision internal and proceed

8. Internal design readiness passes → update state.json: phase=3, phase_id="plan", phase_name="plan", design_approved=true

   • Update company runtime for planning: node scripts/forge-lane-runtime.mjs set-company-gate --gate plan_readiness --gate-owner lead-dev --delivery-state in_progress
   • Update session handoff toward planning (summary only — blockers are recorded on Lead's own plan.md draft during Phase 3 handoff): node scripts/forge-lane-runtime.mjs set-session-brief --goal "Lock the execution plan and task breakdown" --next-owner lead-dev --handoff "{summary}"

9. Create git tag: forge/v1-design

10. Transition to Phase 3 (forge:plans)

<Scale_Decision> Project size determines architecture depth:

Size	Pages	Architecture Approach
Small	1-3	Single Next.js app, flat structure, minimal abstraction
Medium	4-10	Feature-based folders, shared lib, API route layer
Large	10+	Monorepo (Turborepo), shared packages, strict contracts

CTO determines size from spec.md and applies the matching approach. Over-engineering a small project is as bad as under-engineering a large one. </Scale_Decision>

<State_Changes>

• Creates: .forge/design/codebase-analysis.md (Analyst output, skipped for greenfield)
• Creates/updates: .forge/design/ux-brief.md (UX-opening output for redesign/design-improvement path)
• Creates: .forge/design/architecture.md
• Creates: .forge/design/components.md
• Creates: .forge/design/tokens.json
• Creates: .forge/contracts/*.ts
• Creates: .forge/code-rules.md
• Updates: .forge/state.json (phase=3, phase_name="plan", design_approved=true)
• Updates: .forge/runtime.json (plan_readiness gate + next session brief)
• Creates: git tag forge/v1-design </State_Changes>

<Tool_Usage>

• Agent tool: dispatch forge:analyst for codebase analysis (Step 0)
• TeamCreate: create forge-design team when both CTO and Designer are needed
• Agent tool (with team_name): add CTO and Designer to the forge-design team
• SendMessage: CTO↔Designer cross-review within the team
• Agent tool: dispatch forge:researcher for bounded external option research (external only)
• Agent tool: dispatch forge:cto or forge:designer individually when only one is needed
• context7 MCP: verify every framework pattern, package version, API behavior
• codebase-memory-mcp: Analyst uses get_architecture, search_graph, trace_call_path
• Write tool: create design files, contracts, code-rules
• Read tool: load .forge/spec.md for requirements reference
• Edit tool: update .forge/state.json
• Bash tool: git tag forge/v1-design </Tool_Usage>

<Failure_Modes_To_Avoid>

• CTO guessing framework behavior without verifying via context7
• Locking stack or vendor choices before reviewing needed Researcher evidence
• Designer skipping component states (only defining "happy path" appearance)
• Skipping cross-review between CTO and Designer
• Escalating internal design decisions to the client too early
• Proceeding to Phase 3 (plan) without internal design-readiness
• code-rules.md with rules but no GOOD/BAD examples
• Contracts missing request/response types for API routes
• Design tokens without responsive breakpoints
• Over-engineering a small project or under-engineering a large one
• Letting Researcher replace CTO decision-making
• Skipping Analyst step for non-greenfield projects (CTO designs blind)
• Using Researcher for internal codebase analysis (Analyst's job)
• Dispatching CTO and Designer as isolated subagents when Team is needed
• CTO and Designer producing independent outputs without SendMessage cross-review
• Starting design work before blockers recorded in the handoff artifact are resolved
• Writing a separate "understanding statement" or requiring a two-party sign-off when no blockers were recorded (obsolete ceremony — the draft architecture/components files are the record)
• Routing blocker questions through CEO when the direct owner is obvious (PM for spec, CTO for architecture, Designer for UX)
• Routing more than 2 questions to client when internal resolution is possible </Failure_Modes_To_Avoid>

<Auto_Chain> When design completes (architecture.md, code-rules.md, contracts/ all produced, CTO+Designer confirm):

1. Update state.json: phase_id → "plan", design_approved → true
2. IMMEDIATELY invoke Skill: forge:plans Do NOT stop, summarize, or ask the user. Lead Dev will decompose the work before developers start implementing. </Auto_Chain>