MicroCoreOS AGENTS.md

MicroCoreOS — AI Agent & Architecture Guide

This file is the single, absolute entry point for any AI agent (Gemini, Claude, GPT, etc.) working in this codebase. All development must strictly adhere to these principles to maintain the integrity of the Elastic Monolith.

---

🚦 Start here: microcoreos status

One command, before anything else. It answers the three questions that silently derail a session: which plan is actually active (and whether it is still the shipped template), how much of it is done, and whether AI_CONTEXT.md still describes the code on disk.

There is exactly one plan path: plans/active_plan.yaml. The workflows, the executor prompts and the checklist cross-check read that path and no other. A plan written to plans/my_feature.yaml is a plan nothing will ever execute — and because the shipped template is itself a valid plan, an agent that opens active_plan.yaml and finds it untouched will build the example domain and report success. That is why the template carries template: true and fails validation until you delete the line.

---

📖 Your reading route — find your role, read those files, stop

Four roles do the work, and each needs a different slice. Reading outside your slice is not thoroughness, it is budget: the Planner that also loads the plugin templates spends ~3,000 tokens on code it will never write.

They are phases, not people. Doing all of them yourself is the fifth row — the common case for one or two features — and it means playing the four in order, taking each slice as you enter it, not reading everything up front.

You are…	Read exactly this	Write exactly this	Not this
Planner — turning a request into a plan	1. plans/active_plan.yaml — the file you are about to overwrite. It ships as a worked example of all three feature shapes, and it is the cheapest, densest statement of the format there is. 2. AI_CONTEXT.md down to ## 🧩 Plugin Authoring Guide (existing tools, tables, models, routes, events). 3. docs/PARALLEL_DEVELOPMENT.md § Phase 1 for the rules behind it	plans/active_plan.yaml + plans/active_plan.md, overwriting them. Never a new filename — plans/twitter_plan.yaml is a plan nothing will execute	The Authoring Guide, Phases 2-3, domains/, tools/, tests/, extras/
Phase 0 Builder — migrations, models, tools	plans/active_plan.yaml § phase_0 only	Exactly the files phase_0 names: its migrations, its models, its tools	Everything else. The plan already decided every column
Executor — one plugin + its test	Nothing. Your prompt already contains AI_CONTEXT.md + the plan + your one task line	Exactly two files: the file: and test: your task declares	Any file at all — opening one only invites guessed paths
Coordinator — dispatch, verify, reconstruct	plans/active_plan.md (the checklist/state machine) + docs/PARALLEL_DEVELOPMENT.md § Phases 2-3	Only the checkboxes in plans/active_plan.md	The plan's internals; the checklist is the state
Solo — one agent, every phase, in sequence	The row above you, as you reach it — the Planner's slice first, and nothing else until you are past planning	Everything the four rows write, in their order	Skipping the plan because it is "only two features". See below