Auset Brain

maat-workflow-rules

4 min read

MAAT Workflow Rules (Established 2026-03-09, Updated 2026-03-11)

The Pipeline (NON-NEGOTIABLE)

Opus (Architect) → writes requirements to .claude/plans/ + writes /tmp/ status files for completed work
         ↓
Sonnet (Planner) → runs /maat-workqueue → reads plans + existing workqueue + /tmp/ status files → UPDATES (never overwrites) /tmp/maat-workqueue.md (LOCAL)
         ↓
Sync step → SCP /tmp/maat-workqueue.md to EC2 farm-1 (or git push task files to tasks/pending/)
         ↓
Haiku (EC2 cron) → phase0-workqueue-loop.sh (every 2 min) reads /tmp/maat-workqueue.md ON EC2 → dispatches via agentic-loop.js
         ↓
Haiku (EC2 cron) → haiku-dispatcher.js (every 5 min) polls tasks/pending/ → classifies → routes to workers
         ↓
Workers (EC2 farm / Quik Cloud) → execute tasks via agentic-loop.js → write /tmp/ status files when complete → post to #maat-agents Slack

CRITICAL: Haiku is NOT a local Claude session. Haiku = EC2 cron jobs running 24/7 autonomously on the build farm.

How Tasks Reach the Farm (FULLY AUTOMATED)

Sonnet commits tasks/maat-workqueue.md to the Auset Platform repo → git push → GitHub Action (.github/workflows/sync-workqueue-to-farm.yml) fires → SCPs workqueue to both EC2 farm instances → EC2 cron picks up within 2 minutes.

No manual SCP. No local Haiku session. Sonnet commits, pushes, done.

MethodHowSpeedBest For
Git push (PRIMARY)Sonnet commits tasks/maat-workqueue.md → push to develop → GitHub Action SCPs to EC2s~7 min (5 min Action + 2 min cron)Standard pipeline — Sonnet’s default
Git push (tasks)Push .md files to tasks/pending/ → same GitHub Action syncs~7 minIndividual task additions by Opus

CRITICAL: Always push to develop, NOT main. Main triggers template deploy workflows (backend, frontend, test-and-lint) that fail on the boilerplate repo. Develop only triggers sync-workqueue-to-farm.yml.

Command-to-Model Mapping

CommandWho Runs ItWhat It Does
/maat-workqueueSonnet (local)Read Opus plans → generate worker prompts → UPDATES /tmp/maat-workqueue.md locally
EC2 cron: phase0-workqueue-loop.shHaiku (EC2, every 2 min)Read /tmp/maat-workqueue.md on EC2 → parse deps → dispatch via agentic-loop.js
EC2 cron: haiku-dispatcher.jsHaiku (EC2, every 5 min)Poll tasks/pending/ → classify SIMPLE/COMPLEX/BUILD → route to workers
EC2 cron: phase0-orchestrator.shHaiku (EC2, every 5 min)Orchestrate overall dispatch, monitor completion

Execution Cycle

  1. Opus writes requirements → .claude/plans/ + writes /tmp/ status files for completed work
  2. Sonnet runs /maat-workqueue → reads plans + existing workqueue + status files → updates /tmp/maat-workqueue.md → copies to tasks/maat-workqueue.md → commits with detailed message via /git-commit-docs → pushes to develop (NOT main)
  3. GitHub Action (.github/workflows/sync-workqueue-to-farm.yml) fires → SCPs workqueue to both EC2 farm instances
  4. Haiku (EC2 cron) picks up within 2 minutes → parses dependencies → dispatches to workers
  5. Workers execute → write /tmp/*-done.md status files → post to maat-agents Slack
  6. Haiku retries failures automatically; escalates to Opus after 2 failures
  7. Repeat from step 1

Critical Rules for /maat-workqueue (Sonnet)

  1. READ existing workqueue FIRST — never start from scratch
  2. PRESERVE completed/in-progress/manually-added tasks — mark them done, don’t delete
  3. CHECK /tmp/ status files — if a status file exists, that task is DONE
  4. CHECK git logs — recent commits may indicate completed work
  5. APPEND new tasks with the next P## number — don’t renumber existing
  6. NEVER overwrite the entire file — update sections, add entries, but preserve history

Critical Rules for Opus (When Completing Work)

  1. ALWAYS write /tmp/ status file when completing ANY work (AWS, infra, manual fixes, etc.)
  2. Status file naming: /tmp/{project}-{task-slug}-done.md (matches workqueue status file convention)
  3. Include: what was done, commit hash (if applicable), verification results
  4. This is how Sonnet and Haiku know work is complete — without the file, they’ll duplicate it

The Phase 0 Lesson (March 9, 2026)

Opus built the entire build farm (EC2s, SSH, Groq API, agentic loop) but didn’t write /tmp/ status files. Sonnet then regenerated /maat-workqueue.md from scratch, adding P21-P24 to rebuild what was already done. Haiku dispatched Cursor to redo the work. Wasted tokens and time.

Also: Opus added P29 (Feedback App) to the workqueue. Sonnet then overwrote the entire file, losing P29.

Both problems caused by: (1) Opus not writing status files, (2) Sonnet overwriting instead of updating.

Heru Feedback QA Platform (P29)

  • Plan: .claude/plans/heru-feedback-qa-platform.md
  • Web + mobile app for Quik and Vision to submit QA feedback
  • Supports video submissions or session replay
  • Must be re-added to workqueue after the overwrite incident

Graph View

Backlinks