Skip to main content

Maestra (software factory)

Our software factory, built on Mastra Factory. Linear issues move through agent phases from code to human testing. Lives in the infra repo under maestra/.

Architecture​

  • Mastra Factory — runs the agent phases.
  • Linear — Mastra is registered as a Linear app. The board phases drive the work.
  • QA agent — tests the PR preview in a real browser, like a user.
  • Kubernetes — runs on the office cluster. Secrets in maestra-secrets.

Lifecycle​

  1. Coding phase builds the change and opens a PR (preview at prXXX.insfocus.com).
  2. Review phase reviews the PR.
  3. QA phase:
    • writes a test document from a template and attaches it to the Linear issue,
    • runs the tests in a browser and attaches screenshots,
    • posts the result as a Linear comment and a maestra/qa commit status.
  4. Pass → Human testing. Fail → back to coding, then repeat.

Configuration​

  • MAESTRA_QA=false turns QA off: Review goes straight to Human testing.
  • QA secrets in maestra-secrets: MAESTRA_QA_TEST_USERNAME, MAESTRA_QA_TEST_PASSWORD, MAESTRA_QA_CF_ACCESS_CLIENT_ID, MAESTRA_QA_CF_ACCESS_CLIENT_SECRET.
  • The Cloudflare Access service token is scoped to the pr*.insfocus.com Access app only.
  • Container image includes Chromium dependencies and Noto fonts. Pod uses /dev/shm; Playwright cache on the PVC.

Decisions​

  • 2026-11-18 — QA agent runs as a phase between Review and Human testing.
  • 2026-11-18 — Test credentials come from secrets. Results go to a Linear comment plus a commit status.
  • 2026-11-18 — Failed QA sends the issue back to coding and repeats.

Gotchas​

  • Problem: board update fails with phase_in_use. Fix: move cards out of the phase being removed (QA, QA blocked, Human testing), then restart.

Open​

  • QA phase shipped in InsFocusSystems/infra#13 — end-to-end run after deploy pending.