oc-app-architect

# App Architect

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Unified planning + build skill. Takes a concept from idea through spec, design, and
roadmap (planning phases with user approval gates), then builds it sprint-by-sprint
using a Generator → Evaluator harness (build phase with automated QA).

This is one skill, not two. Planning and building are the same pipeline.

## /oc-app — Command Reference

```
APP ARCHITECT COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  PLANNING PHASES
  /oc-discover       Discovery interview (Phase 1)
  /oc-spec           Spec generation + oc-stack-forge (Phase 2)
  /oc-design         Design pipeline — style book, wireframes, prototypes (Phase 3)
                    auto-routes data-heavy screens to /oc-data-forge
  /oc-roadmap        Sprint plan generation (Phase 4)

  BUILD PHASES
  /oc-scaffold       Generate runnable project structure (Phase 5)
  /oc-build          Start or resume Generator → Evaluator sprint loop (Phase 6)
  /eval           Run Evaluator on current sprint (ad-hoc QA)
  /oc-launch         Launch checklist + deploy handoff (Phase 7)

  UTILITIES
  /status         Current phase, gates passed, sprint scores, next action
  /approve        Approve current gate and advance
  /oc-export-spec    Generate master spec document (.docx)
  /oc-punch-list     View or edit the screen & component punch list
  /contract       View or edit current sprint contract

  SESSION
  /checkpoint     Show checkpoint status
  /checkpoint show    Full checkpoint JSON
  /checkpoint reset   Archive and restart

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Architecture

```
CONCEPT
  │
  ▼
┌─────────────────── PLANNING (user-driven, gate-controlled) ──────────┐
│                                                                      │
│  Phase 1: Discovery ──► Phase 2: Spec ──► Phase 3: Design           │
│  (interview)      ★GATE  (+ oc-stack-forge) ★GATE  (style+wireframes)  │
│                                                    ★GATE             │
│  Phase 4: Sprint Plan                                                │
│  (roadmap → sprint decomposition)  ★GATE                             │
│                                                                      │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
                               ▼
┌─────────────────── BUILD (agent-driven, evaluator-controlled) ──────┐
│                                                                      │
│  Phase 5: Scaffold (one-time project setup)                          │
│                                                                      │
│  Phase 6: Sprint Build Loop (repeat per sprint)                      │
│  ┌────────────┐  contract   ┌─────────────┐                         │
│  │ GENERATOR  │◄──negotiate──►│ EVALUATOR  │                         │
│  │ builds +   │              │ grades +    │                         │
│  │ tests      │──code+tests─►│ reports     │                         │
│  │            │◄──feedback───│ (skeptical) │                         │
│  └────────────┘              └─────────────┘                         │
│       PASS → next sprint | FAIL → iterate | MAX → escalate          │
│                                                                      │
│  Phase 7: Launch                                                     │
│  (audit gate → deploy → monitor)                                     │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘
```

### Why One Skill?

Earlier versions of opchain split planning and building into two skills with a fuzzy
handoff between them. Both produced specs. Both decomposed sprints. Both tried to
scaffold. Merging them into oc-app-architect eliminates:
- Duplicate spec generation
- Conflicting sprint formats
- The "which skill do I use now?" question
- Context loss at the planning → building transition

The planning phases remain user-driven with approval gates (you stay involved in every
design decision). The build phases use the Generator → Evaluator loop (automated QA
that catches what single-pass generation misses). Same skill, different operating modes.

---

## Session Persistence (Checkpoint Protocol)

Checkpoint: `{project-dir}/.checkpoints/oc-app-architect.checkpoint.json`

### Resume on Start

When any command is invoked:
1. Check for checkpoint
2. If exists: show phase, gates, sprint scores, next action
3. Ask: "Continue, restart, or show full checkpoint?"

### progress_table

```json
[
  { "id": "discovery",       "label": "Discovery interview",      "status": "not_started" },
  { "id": "spec",            "label": "Spec + oc-stack-forge",        "status": "not_started" },
  { "id": "spec-gate",       "label": "★ Spec approval",           "status": "not_started" },
  { "id": "design",          "label": "Design pipeline",           "status": "not_started" },
  { "id": "design-gate",     "label": "★ Design approval",         "status": "not_started" },
  { "id": "punch-list",      "label": "Punch list",                "status": "not_started" },
  { "id": "punch-gate",      "label": "★ Punch list approval",     "status": "not_started" },
  { "id": "sprint-plan",     "label": "Sprint plan",               "status": "not_started" },
  { "id": "sprint-gate",     "label": "★ Sprint plan approval",    "status": "not_started" },
  { "id": "scaffold",        "label": "Scaffold generation",       "status": "not_started" },
  { "id": "sprint-1",        "label": "Sprint 1: [name]",          "status": "not_started" },
  { "id": "sprint-2",        "label": "Sprint 2: [name]",          "status": "not_started" },
  { "id": "sprint-3",        "label": "Sprint 3: [name]",          "status": "not_started" },
  { "id": "launch",          "label": "Launch & deploy",           "status": "not_started" }
]
```