# 2. `instructionDriven` flag as explicit pipeline fork

**Status:** Accepted · 2025

## Context

The main 9-phase pipeline is TDD-centric. The Figma-to-SwiftUI workflow is
config-driven (design tokens, Code Connect, Wiki generation) and does not
map onto the red-green-refactor cycle. Earlier versions handled this with
implicit branching in Phase 3 - "if the task has a Figma URL, fork here".

Implicit branches had three problems:

1. Hard to debug - no single place where the fork was decided.
2. Silent failure when instruction files were missing or misnamed - Phase 6
   would fall through to standard commit flow, losing Figma-specific steps.
3. Phase 7 audit couldn't tell which branch was actually taken.

## Decision

Introduce an explicit boolean `instructionDriven` in `agent-state.json`
(`agent-state.schema.json:95`). Set at Phase 0 Step 9 after inspecting the
parsed task input (`figmaUrl` + detected instruction files). All downstream
phases that need to fork read this flag.

Phase 6 uses a **deterministic truth table** (documented at
`phase-6-commit.md:25`) to dispatch:

| `instructionDriven` | `instructionFiles.commit` exists | Action |
| ------------------- | -------------------------------- | ------ |
| true  | yes | Instruction-driven path |
| true  | no  | Log error, set `instructionDrivenFallback=true`, use standard path |
| false | -   | Standard path |

## Consequences

Positive:

- Fork decision is a single, auditable flag in state.
- Missing instruction files fail loud (`instructionDrivenFallback` surfaced in
  Phase 7 report) instead of silent.
- The Figma pipeline could be extracted to its own package without changing
  main pipeline code - it just writes the flag + files, and the main pipeline
  reads them.

Negative:

- Adds a schema field that must be maintained forever once shipped.
- Introduces a coupling between the Figma pipeline's instruction file naming
  and the main pipeline's expectations. Mitigated by documenting the contract
  in `instructionFiles` schema sub-object.

## Alternatives Considered

**Implicit detection (current-task-has-Figma-URL):** previous approach.
Rejected because a task might have a Figma URL but not need instruction-driven
mode (e.g. `/multi-agent "Fix text spacing in FigmaDesign-X"`).

**Separate top-level command (`/figma-to-swiftui` bypasses `/multi-agent`):**
considered. Rejected because it duplicates the 9-phase scaffolding
(branch creation, state management, Phase 6 commit flow). The current design
lets Figma reuse Phases 0, 6, 7 wholesale.