# The Three-Phase Flow

Connector development in this plugin runs through exactly three phases, in order:

```
Research  →  Build  →  Validate
```

Each phase is gated by a deterministic script under `scripts/gates/` — the phase is
complete when its gate exits 0, and its status is recorded in
`.connector-dev/<provider>/run.json` by `scripts/state/run.js`. The model does the
phase's work; the gate decides whether it counts.

| Phase | Doc | Command | Gate(s) | Produces |
|---|---|---|---|---|
| 1 — Research | [1-research.md](1-research.md) | `/connector:research` | `research.js` (R1–R11) | `.connector-dev/<provider>/research/…` — the full documented API surface |
| 2 — Build | [2-build.md](2-build.md) | `/connector:build` | `auth.js` (A1–A12), `build.js` (B1–B16), `conventions.js` (N1–N20) | Connector YAML — `*.connector.s1.yaml` + one `*.s1.partial.yaml` per resource |
| 3 — Validate | [3-validation.md](3-validation.md) | `/connector:validate` | `validate.js` (V1–V8) | `.connector-dev/<provider>/validation/…` — doc-comparison findings, reconciled |

`/connector:full` runs all three in sequence, unattended.

## Phase 1 — Research & Investigation

Enumerate the provider's full documented surface before anything is built: category,
API list with MoSCoW priority tiers, auth mechanisms, and per-endpoint detail
(parameters, response shapes, pagination). Scope is resolved here too — named resources
are built uncapped; an unscoped request selects the
provider's core use cases under a larger cap (30/50). Everything left out is recorded,
never silently dropped.

→ [1-research.md](1-research.md) for the skills, agents, and artifact tree.

## Phase 2 — Build Connector

Project the research faithfully into Falcon connector YAML. Two loops, auth first: the
auth block is driven to green (`auth.js` exits 0) before any action is written, because
a wrong auth block breaks every action at once. Then actions are built per resource and
checked by `build.js` (projection fidelity: built ÷ discovered-in-scope) and
`conventions.js` (corpus-mined rules from the shipped connector corpus).

→ [2-build.md](2-build.md) for the skill catalog and exit checkpoint.

## Phase 3 — Validation & Benchmarking

Re-derive the connector from the provider's **live documentation** and reconcile every
difference. This phase does not trust research — comparing the build against the
research that produced it would certify research's own omissions as correct, so the
gate (`validate.js`) demands evidence of an independent re-read.

→ [3-validation.md](3-validation.md) for the comparison rules and artifacts.

## The loop, in every phase

```
do the phase's work
run its gate
  exit 0  →  mark the phase complete, move on
  exit 1  →  fix what the gate reported, run it again
  exit 2  →  the gate could not evaluate; that is a bug, fix it and rerun
```

When two consecutive rounds resolve nothing, the phase is marked `exhausted` and the run
moves on carrying its open gaps. The run's terminal outcome is `complete` (all three
gates passed) or `partial` (at least one phase exhausted — connector delivered with its
gap list).