Architecture

Frankie reuses APEX's proven dispatcher → BigQuery queue → worker pod pattern (the same one behind Ascend and Sentinel). A /frankie gesture is parsed by the auto-responder, enqueued to apex.frankie_sessions, and claimed by a dedicated apex-frankie worker pod that runs the pipeline in its own thread and scales horizontally.

Runtime flow

flowchart TD
  S["Slack /frankie or PR label READY TO BUILD"] --> D["Dispatcher: parse, ack, enqueue"]
  D --> Q[("BigQuery apex.frankie_sessions")]
  Q --> W["apex-frankie worker (HPA, CAS claim, durable resume)"]
  W --> P1["1. Comprehend: clone, read PR + spec, profile repo"]
  P1 --> P2{"2. Spec review gate"}
  P2 -->|"incomplete"| BLK["Comment gaps and stop (unless --force)"]
  P2 -->|"pass"| P3["3. Implement or review and fix"]
  P3 --> P4["4. Verify local: lint, typecheck, build, cheap tests"]
  P4 --> P5["5. Push with anti-cheat diff (never merges)"]
  P5 --> P6["6. Watch CI and review comments"]
  P6 -->|"fixable"| P3
  P6 --> P7["7. Self-verify vs acceptance criteria"]
  P7 --> H["Ready for human review"]

While working inside a cloned repo, the agent has APEX's full MCP connections (git-excluded so tokens never commit) to debug failures with real data.

The 7-stage pipeline

Frankie is a durable state machine — each stage persists to BigQuery, so a pod restart resumes via orphan-reclaim.

1. Comprehend — clone, read PR + spec, profile the repo; read skills/CI/lint config critically and flag stale skills.
2. Spec review (gate) — if the plan is incomplete, comment the gaps on the PR and stop (unless --force).
3. Implement / review + fix — implement the plan, or if the PR already has code, complete the gap and fix defects without rewriting working code.
4. Verify local — run lint / typecheck / build (and cheap tests) and fix before pushing — shift CI left.
5. Push — anti-cheat the diff, then push to the PR branch. Never opens or merges.
6. Watch — poll CI and review comments; classify each as fix-now vs needs-a-human; fix, re-push, repeat.
7. Self-verify — re-check against the spec's acceptance criteria, post a summary, mark ready.

Loop termination

The governing principle is bounded autonomy with event-driven re-arm — never an open-ended spin. The active watch loop ends on the first of:

For the long human tail (a reviewer who replies a day later), Frankie goes dormant and is re-woken by a new PR event rather than staying spun up.

PR-state spectrum

PR label state machine

The AI FACTORY: label is the visible state of a run on the PR:

• READY TO BUILD — entry; a human applies it to trigger a run.
• BUILDING — claimed and running; a single sticky comment tracks the 7 stages.
• SPEC INCOMPLETE — the completeness gate failed; fix and re-trigger, or re-run with --force.
• READY FOR 1ST HUMAN REVIEW — green and review-clean; the PR stays a draft for the owner to review.
• NEEDS HUMAN — blocked, exhausted, expired, or failed; a new PR event can re-arm the run.
• CANCELLED — stopped via frankie_cancel.

Guardrails

• Never merges — hard-coded. Frankie pushes and reports ready; a human merges.
• Test integrity (anti-cheat) — a diff-level check refuses to push changes that skip/xfail/delete tests, remove assertions, or tamper with required-check config. It reaches green by fixing code, not gaming tests.
• Bounded autonomy — iteration / TTL / idle / oscillation budgets; hands off on ambiguity rather than guessing.
• Auditability & least privilege — every action logs to apex.question_log (actor, PR, SHAs, iteration).

Evaluation — built for model upgrades

Frankie's output is code + CI outcomes, so it uses a task-based, outcome-graded eval (distinct from APEX's Q&A harness):

• Offline gated suite — fixture cases (seed repo + spec + held-out grader) run in a sandbox; scored on correctness, false-green, anti-cheat trips, and state accuracy.
• Online telemetry — a live per-model scorecard from question_log (success / handoff / spec-gate / failure rates).

Promotion gate: a new model ships only if correctness doesn't regress and false-green and anti-cheat trips don't get worse — a multi-dimensional gate that catches "raw success went up but it games tests / declares done while wrong."