# 2. `instructionDriven` flag as explicit pipeline fork

**Status:** Accepted · 2025

> **Phase numbers below are the eight-phase ones.** [ADR-0014](./0014-six-phase-consolidation.md) renumbered the contract in v19.0.0 (Phase 6 Commit is now Phase 4, Phase 7 Report is now Phase 5). The decision this ADR records is unchanged; only the labels moved, and they are left as written because an ADR records what was decided.

## 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.