# Shared Protocols: Spec-Driven UI

## Execute-Verify-Record Pattern

Every mandatory step in this skill follows the EVR triplet:

1. **EXECUTE:** The exact action to perform — a specific tool call (Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion) or data operation
2. **VERIFY:** How to confirm the action happened — check file exists via Glob, content matches via Grep, exit code is 0, data key is populated
3. **RECORD:** CLI command to persist completion — `devforgeai-validate phase-record ${IDENTIFIER} ${WORKFLOW_FLAG} --phase=NN --step=N.M --project-root=. 2>&1` (`${WORKFLOW_FLAG}` is `--workflow=ui` for story/standalone, `--workflow=ui-extract` for extract — set in SKILL.md Step 0.1b)

No step may be skipped, abbreviated, or declared "not applicable" without explicit user authorization.

---

## Self-Check Violations

If ANY of the following is true during execution, it is a VIOLATION — stop and correct immediately:

- [ ] Stopping to ask about token budget
- [ ] Stopping to offer execution options ("should I proceed?")
- [ ] Waiting passively for results
- [ ] Asking "should I execute this?"
- [ ] Skipping a phase because "it seems simple"
- [ ] Combining multiple phases into one
- [ ] Summarizing instead of loading a reference file via Read()
- [ ] Skipping a RECORD step because "the CLI might not be installed"
- [ ] Consolidating multiple phase reference loads into one
- [ ] Skipping verification because "I already wrote the file"

---

## Phase File Loading Protocol

Each phase file MUST be loaded via Read() at the start of that phase. Do not:
- Load all phase files at once during initialization
- Rely on memory of a phase file loaded in a previous invocation
- Summarize a phase file instead of loading it

The correct pattern:
```
# At the start of Phase NN:
Read(file_path=".claude/skills/spec-driven-ui/phases/phase-NN-{name}.md")
# If fails, try operational path:
Read(file_path=".claude/skills/spec-driven-ui/phases/phase-NN-{name}.md")
```

---

## Reference File Loading Protocol

Reference files are loaded per-phase based on the Reference Files Index in SKILL.md. Each phase loads only the references it needs — no consolidated pre-loading.

---

## CLI Gate Backward Compatibility

The `devforgeai-validate` CLI may not be installed in all environments. Handle gracefully:

| Exit Code | Meaning | Action |
|-----------|---------|--------|
| 0 | Success | Continue normally |
| 2 | Identifier format not recognized | Continue — backward compatible |
| 127 | CLI not found | Continue without CLI gates — execute ALL steps regardless |

When CLI is unavailable, the remaining 3 anti-skip layers (reference loading, checkpoint state, artifact verification) still enforce execution discipline.

---

## Phase Routing by Mode

spec-driven-ui routes phases by `$MODE` (set in SKILL.md Step 0.1). Phases 00, 01,
06, 07, 08 run on every invocation. The middle phases differ:

- **story / standalone** (`--workflow=ui`): `01 → 02 → 03 → 04 → 05 → 06 → 07 → 08`
- **extract** (`--workflow=ui-extract`): `01 → 02a → 06 → 07 → 08` — Phase 02a
  (Mockup Extraction) runs instead of 02, then skips 03–05 and proceeds to 06.

Within each phase that DOES run, ALL steps are mandatory — there is no within-phase
step skipping. (The `02a → 03` user fallback in phase-02a is a deliberate mode switch
to standalone, not a skip.)
