mgs-company-os-architecture - SKILL.md Agent Skill

name: mgs-company-os-architecture description: "Use when Rodolfo asks to organize, redesign, audit, or migrate the MGS company operating structure: areas, agents, sources of truth, routing, permissions, context files, scripts, skills, docs, and safe phased restructuring before adding more agents." tags: [mgs, company-os, architecture, operations, agents, governance, sources-of-truth, migration, inventory, zeus, atena, ares] related_skills: [discord-ops, hermes-agent-operations, log-monitor-discord-alert]

MGS Company OS Architecture

When to use

Use this skill when Rodolfo asks about:

Structuring the MGS as a company before creating or expanding agents.
Reorganizing /root/mgs-agent outside individual agent profiles.
Defining official areas, routes, permissions, sources of truth, and agent responsibilities.
Turning ad-hoc scripts/docs/skills/data into a coherent operating system.
Deciding whether files should be kept, moved, renamed, archived, consolidated, or left untouched.
Comparing the current MGS structure with external agent/company architecture training or examples.

Core principle

Do not start by moving or renaming files. Start with a blueprint and a read-only inventory.

The MGS already has real production state: sites, permissions, content pipelines, WordPress tooling, crons, logs, Hermes patches, and agent profiles. Reorganization must be incremental and reversible.

Preferred framing:

We are not rebuilding from zero.
We are adding a company operating layer above the current operational foundation,
then migrating safely in small approved blocks.

Canonical sequence

1. Read-only current-state inventory

Inspect /root/mgs-agent while excluding agent-specific profile content unless Rodolfo explicitly asks for it.

Default exclusions:

/root/.hermes/profiles/zeus/
/root/.hermes/profiles/atena/
/root/.hermes/profiles/ares/
/root/mgs-agent/profiles/
logs/runtime-heavy files unless needed

Classify the structural base by top-level function:

context/      conceptual company knowledge
 data/        operational data, state, inventories
 docs/        documentation, pendencies, changelog, crons
 scripts/     automations, monitors, runners, importers
 skills/      reusable procedures for agents
 patches/     local Hermes/MGS patches
 backups/     safety copies and old pre-change states
 experiments/ spikes/proofs of concept
 tools/       auxiliary tooling
 api/         internal APIs

2. Create a blueprint before operational changes

The first deliverable should usually be:

/root/mgs-agent/context/company-os.md

For ongoing operation, also maintain a lightweight navigation map:

/root/mgs-agent/context/mgs-os-map.md

Purpose of mgs-os-map.md: a map-of-maps for Zeus to choose the right source before broad searching. It should map question classes to canonical files/folders/agents (e.g. “Atena fez X?” → Atena logs + article tracker + WP; “permissão real?” → data/authorized-users.json; “cron ativo?” → docs/CRONS.md + crontab real). Keep the full map in context/, not embedded wholesale in SOUL. SOUL should carry only a compact pointer/rule: consult context/mgs-os-map.md before search_files for structure-related questions.

Mark it clearly as a proposal until Rodolfo approves it as canonical.

Minimum sections:

1. Objective
2. Operating principles
3. Official MGS areas
4. Agent map
5. Current sources of truth
6. Target sources of truth
7. Operational routes
8. Permissions matrix
9. File classification taxonomy
10. Safe migration plan
11. Decisions pending Rodolfo
12. Next step after approval

After the blueprint is in place, keep the derived docs aligned rather than letting each drift:

context/areas.md
context/agent-map.md
context/routes.md
context/sources-of-truth.md
context/permissions-matrix.md

If Rodolfo answers “ok” after a recommendation or execution report for a low-risk additive Company OS step, treat it as approval/continuation for that same phase/block context. If the message is a reply, anchor interpretation to the quoted message and previous execution report before acting. Still do not move/remove runtime files or alter agents without explicit scope/approval.

Discord thread discipline for Company OS work: do not rename an already-open restructuring thread while it keeps the same objective. Short messages like Ok, vamos continuar, or prossegue never trigger a thread rename and should inherit the current Company OS sequence until Rodolfo explicitly finalizes or changes objective. If a title ever truly needs to be created/changed because of a clear durable topic change, keep it in the dominant language of the workstream/user message — normally PT-BR for Rodolfo's MGS OS threads. Never translate an active PT-BR restructuring thread title into Spanish/English because of a generic title heuristic.

3. Recommended initial MGS areas

Use the CEO-described real operating model as the starting point. The current canonical proposal is:

Area                         Function
---------------------------- -------------------------------------------------
Executive / Management        Direction, strategy, priorities, daily meetings,
                              decisions, coordination and governance.
Content Operations            REC/P1, SEO support articles, categories,
                              WordPress editorial, daily content and QA.
Growth / Media Buying         Facebook Ads, Google Ads, SMS, media buyers,
                              campaign costs, acquisition and ROI.
Creative Operations           Kelly, Canva, ChatGPT, TopView.ai, Grok/other AI,
                              static/video creatives and asset handoff.
Revenue / AdOps               Smart Bidding, ActiveView, AdManager/AdX,
                              approval, ad blocks, pricing rules and AdOps.
Finance / BI                  Financial close, spreadsheets, revenue, costs,
                              invalid traffic, commissions, salaries and ROI.
Tech / WordPress / Infra      WordPress setup, plugins, pixels, VPS, Hermes,
                              agents, crons, scripts, patches and monitoring.
Security / Access             Credentials, tokens, user permissions, dashboards,
                              APIs, hardening and risk policy.

Durable MGS facts from the CEO explanation:

Rodolfo and Geizian are sócios/partners. Rodolfo owns management, finance, WordPress/technical structure, pixels, partner-network relationship, strategy, and commands the AI-agent operation as a whole (not just Ares). Geizian manages the campaign/site managers day to day, launches/tests campaigns himself as gestor g002, and also participates in Growth, Creative support, and Revenue/AdOps.
Ially is the office manager who follows up/cobranzas with gestores when requested tasks are late or not done.
Raquel owns Content Operations and should supervise Atena.
Kelly is the human owner of creative production and currently uses AI/Canva workflows for gestores. Geizian also orients/supports Kelly in Creative Operations. The creative agent name is Hera, not Kelly.
There are six gestores with tracking codes used in UTM_medium: Icaro g001, Geizian g002, Isliago g003, Joe g004, Kelly g005, Nicolas g006.
Geizian is both partner/coordinator and an operating gestor (g002): he also launches/tests campaigns for some sites.
The campaign agent is Ares only. Do not use Aris. Do not label it Ares futuro; if needed, describe status separately as em configuração / implantação progressiva.
Smart Bidding and ActiveView are Google partner companies with their own AdX/Ad Manager networks. Sites are added to those networks and ad blocks are created there before monetization starts. The Smart Bidding dashboard is the preferred/main management dashboard because it is more complete and centralizes management, even for visibility across sites.
ActiveView is now an exception/legacy-active network: only openzed, cliquet, and their subdomains are not technologically migrated to Smart Bidding.
Finance runs monthly: period day 1–30, Google payment around day 21–23, Rodolfo checks Facebook Business Manager spend, invalid traffic, Smart Bidding/ActiveView reports, commissions, salaries and expenses in his spreadsheet.
Gestor compensation matters to Finance/BI: base salary is R$3,000, but commission replaces salary when higher. Commission is 7% of net profit up to R$100,000 and 10% once the gestor reaches R$100,000 net profit. Do not double-pay salary + commission.

4. Recommended agent map

Agent   Primary area    Role
------- --------------- ------------------------------------------------------
Zeus    Executive/Ops   General Manager, governance, routing, audit, escalation;
                        controlled by Rodolfo only by default.
Atena   Content         Editorial production, REC/P1, WordPress, content QA;
                        Raquel supervises.
Ares    Growth/Ads      Campaign management, creation, analysis, acquisition;
                        Rodolfo + Geizian first, trained gestores after testing.
                        Ares does not configure ChatPion/DigitalTrChat, quiz,
                        or SMS Funnel.
Hera    Creative        Creative assets, videos, Canva/Drive organization and
                        naming taxonomy; Kelly is the human creative lead.
                        Hera and Ares both need read/write access to the
                        approved-creatives Drive so campaigns can use assets.
Future  TBD             Specialist agents created only after mission/scope exist
Future  TBD             Specialist agents created only after mission/scope exist

Rules:

Agent creation follows company architecture. Do not create a new agent until its area, mission, sources of truth, permissions, and escalation paths are explicit.
After a new agent is technically online, do not jump straight to a real operational task. First create/validate the agent's operational diagram/context document (for Hera this is context/hera-creative-agent.md), then align SOUL.md, create class-level skills/templates, and only then run controlled production-like tests.
Zeus is controlled only by Rodolfo. Other company members join Zeus threads only when Rodolfo explicitly asks Zeus to include them.
Ares starts under Rodolfo + Geizian control, then gestores get access only after the agent is tested, approved, and the gestores are trained on how to open threads and interact with it.
The creative agent is Hera. Kelly is the human creative lead/gestora (g005), not the agent name. Rodolfo, Geizian, Kelly and gestores may request creative work according to approved scope.
Hera is Creative Operations, not merely an Ares handoff assistant. Hera creates static/image and video creatives, organizes Drive/Canva assets, and maintains naming/inventory even when Kelly, Geizian or gestores create assets themselves and run campaigns manually without Ares. Ares is an optional consumer of approved assets, not the only destination.

5. Sources-of-truth distinction

Keep this separation clear:

context/   explains how the company works
 data/     stores operational state and facts used by systems
 scripts/  performs deterministic actions
 skills/   teaches agents procedures
 docs/     records history, plans, pendencies, changelog
 logs/     audit/runtime trail
 patches/  local runtime modifications

Pitfall: do not let SOUL.md, ad-hoc prompts, or individual skills become the only place where company structure exists. Company architecture belongs in context/ and is then referenced by agents.

6. Safe migration stages

Use staged gates. If company-current-operating-model.md and company-os.md already exist, do not keep using the generic initial order; first reconcile the plan/status with the actual completed artifacts.

Recommended current-stage sequence:

Phase 0   Capture real operating model    company-current-operating-model.md
Phase 1   Company OS blueprint             company-os.md, marked proposal/canonical as appropriate
Phase 2   Derived canonical context docs   areas, agent-map, routes, sources-of-truth, permissions
Phase 3   Classified inventory             one line per relevant path
Phase 4   Migration plan by block          explicit action/risk per file or folder
Phase 5   Agent reference updates          one agent at a time, validated after each
Phase 6   Operational validation           Discord, logs, crons, agents, runtime
Phase 7   Cleanup/archival                 explicit Rodolfo approval per block

When Rodolfo says to review files one by one, do not jump to inventory or migration. Present the current file, accept corrections, patch it, then move to the next.

In a long-running Company OS restructuring thread, preserve thread context aggressively. If Rodolfo replies with a short acknowledgement such as “Ok”, “continue”, “vamos continuar”, or “próximo”, inherit the quoted/recent block context and execute the next recommended low-risk block. Do not treat the message as a new topic, do not re-plan from scratch, and do not rename the existing thread while the objective is still the same.

Long-running Company OS threads have persistent objective continuity. A short reply such as “ok”, “continue”, or “vamos continuar” usually approves/continues the current block; if it is a Discord reply, use the quoted/replied message as the primary context anchor. Do not reinterpret a short reply as a new topic, and do not rename an already-open restructuring thread while the objective is still the same. Thread title changes belong only at thread creation or after an explicit, strong topic change — never from a vague message or reply.

When Rodolfo corrects naming or ownership (e.g. Ares not Aris, Hera not Kelly agent), search canonical context files for stale variants and clean them up. Explain that search as stale-term cleanup, not as re-litigating the user's correction.

Cascading correction rule: any correction made while reviewing one file can invalidate previously reviewed files. Before marking the current file as ready for Rodolfo review, search/patch the already-reviewed Company OS docs for conflicts, stale terms, redundant sections, duplicated governance sections, and contradictory ownership/routes. Typical cascade targets are company-os.md, company-current-operating-model.md, areas.md, agent-map.md, routes.md, sources-of-truth.md, permissions-matrix.md, team.md, acquisition.md, monetization.md, processes.md, sites.md, and the current file under review. Report the cascade explicitly in a short table. Do this before sending the next file for review, not after Rodolfo finds the inconsistency.

Avoid duplicating global rules inside every domain file. Conflict/source precedence belongs primarily in sources-of-truth.md; domain files like sites.md should stay focused on their content and carry only a short pointer such as “this file is conceptual; data/sites.json wins for automation.” If you notice a repeated ## Regra de conflito section in a domain file, consider removing it after confirming the rule already exists in sources-of-truth.md.

Consistency audit rule: after applying a conceptual correction, do not only validate the current file. Run a cross-document consistency check for stale names (Aris, Ares futuro, Kelly agent/agente Kelly/Creative Agent), Ares overreach into ChatPion/quiz/SMS/AdOps/site setup, SB/AV ownership, gestor codes, Hera/Drive/Kelly boundaries, Ially/follow-up, and data/sites.json vs sites.md automation boundaries. Use regex/scripts as guardrails, but inspect flagged snippets semantically before reporting; negative statements like “Ares não configura ChatPion” are correct, not conflicts.

Cross-file semantic audit rule: after any material correction from Rodolfo, run a semantic consistency check across the already-touched Company OS docs. Do not rely only on git diff --check; whitespace validation is necessary but not sufficient. Verify naming, scope, ownership, routes, permissions, sources of truth, and finance/BI implications. If conflicts are found, patch them before asking to proceed. See references/company-os-cross-file-consistency-audit-2026-06-06.md for the checklist and reporting pattern.

Sequencing pitfall: after company-current-operating-model.md and company-os.md are drafted, do not jump straight to inventory. Review the derived files one by one with Rodolfo first: areas.md, agent-map.md, routes.md, sources-of-truth.md, and permissions-matrix.md. Inventory starts only after those derived docs are accepted as the current canonical proposal.

Already-reviewed-docs pitfall: before telling Rodolfo to review the five derived docs again, verify whether they were already reviewed/updated. Use session history and git/file status (git log -- <file>, status lines like proposta canônica v0.x) to distinguish “not reviewed yet” from “needs quick consistency audit.” If the docs were already worked through, do not restart manual review from areas.md; run a cross-file consistency audit, patch only real inconsistencies, mark Phase 2 as the current operational proposal, and proceed to Phase 3 inventory.

Phase 2 audit pattern after docs appear reviewed:

1. Check stale terms: Aris, Ares futuro, Kelly agent, agente Kelly, Creative Agent.
2. Check required current concepts: Hera, Ares, Atena, Zeus, Smart Bidding,
   ActiveView, Geizian, Ially, gestores g001–g006.
3. Semantically inspect Ares scope flags around ChatPion/DigitalTrChat,
   quiz, SMS Funnel, AdOps/site setup and pixel setup.
4. Semantically inspect Hera scope flags around campaign execution, budget,
   pixel and Business Manager.
5. Patch only ambiguous or conflicting language.
6. Update `docs/mgs-os-restructure-plan.md` to show Fase 1/Fase 2 as
   “concluída como proposta operacional atual” when the audit passes.
7. Register a concise audit event and validate with `git diff --check`.

Phase 3 inventory pattern:

1. Before generating inventory, clean unrelated repo dirt that could contaminate
   the next block. If `profiles/zeus-skills/...` is dirty, review it as a
   separate hygiene block, keep useful skill/procedure updates, fix obvious
   renames, run a secret scan, commit/push, then continue.
2. Treat `docs/mgs-structure-inventory.md` as read-only classification only:
   no moves, no deletes, no runtime writes.
3. If the inventory file already exists, update it in place instead of creating
   a duplicate. Include current counts for top-level areas and classify:
   `context/`, `profiles/`, `data/`, `scripts/`, `docs/`, `skills/`,
   `patches/`, `api/`, `tools/`, `backups/`, `experiments/`, `logs/`, and
   root-sensitive files such as `.env`, `AGENT.md`, and `*.bak`.
4. Separate action recommendations by class: `manter`, `não tocar`, `revisar
   depois`, `arquivar depois`, `alterar só com plano`, `append-only/consulta`.
5. Validate the inventory with required-section checks, `git diff --check`, and
   a secret scan over the diff. Then verify auto-push via `logs/auto-push.log`
   and `HEAD == origin/main` rather than assuming manual `git push` works.
6. Report Fase 3 as complete only after the repo is clean and the file is on
   origin/main.

Phase 4 context-file/block pattern:

1. Work one approved block at a time; for context files, change conceptual docs
   only unless Rodolfo explicitly expands scope.
2. After every material correction, run cross-file semantic checks for stale
   names, Ares/Hera boundaries, SB/AV exceptions, gestor codes, Finance/BI and
   source-of-truth conflicts.
3. Report each block with: arquivo principal, status/version, validation, secret
   scan, audit log, auto-push, HEAD=origin, and repo state.
4. If Rodolfo says “ok continue”, immediately proceed to the next recommended
   block. Do not ask him to restate the plan.
5. After `docs/CRONS.md` / Bloco 7, update `docs/mgs-os-restructure-plan.md` to
   mark the completed blocks and define the Fase 5 gate before changing agents.

Phase 5 Zeus SOUL alignment pattern:

1. First gate is Zeus only unless Rodolfo explicitly expands scope.
2. Patch both live and versioned SOUL files:
   /root/.hermes/profiles/zeus/SOUL.md
   /root/mgs-agent/profiles/zeus-soul.md
3. Create timestamped backups before editing and keep live/versioned files identical.
4. Add a top-level `MGS OS — fonte gerencial principal` section that points Zeus
   at `/root/mgs-agent/context/` and relevant runtime/docs sources instead of
   duplicating all company architecture inside SOUL.
5. Encode source precedence: data/runtime/logs/WordPress/crontab/services for
   live technical state; context/MGS OS for managerial structure; SOUL for
   posture/channel/safety/behavior.
6. Clean stale wording while there: no `futuramente Ares`; no hardcoded stale
   model identity like `Claude Sonnet` when MGS policy says GPT-5.5/OpenAI-Codex.
7. Update `docs/mgs-os-restructure-plan.md` to mark Zeus concluded and the next
   agent gate, normally Atena.
8. Validate: diff check, secret scan on added lines, stale-term scan, live/versioned
   cmp, audit log, auto-push, HEAD=origin, repo clean.
9. Do not touch crontab, tokens, runtime/systemd, permissions, cleanup/migration,
   or Discord thread title in the initial Zeus gate.

Detailed runbook: references/company-os-phase5-zeus-soul-alignment-2026-06-07.md.

Phase 5 agent HOT operational map pattern:

1. When an agent repeatedly performs broad `search_files` calls for generic
   operational terms (`drive`, `creative`, `meta`, `UPLOAD`, `CC_*`, etc.), add
   a compact HOT map under `/root/mgs-agent/context/<agent>-operational-map.md`.
2. The HOT map should route natural-language asks to first canonical sources:
   context docs, SOUL, class-level skills, runtime data, scripts, logs, handoff
   rules, boundaries and validation checks.
3. Patch `/root/mgs-agent/context/mgs-os-map.md` so Zeus knows the new map, and
   patch both live + versioned SOUL files with a short pointer instructing the
   agent to open the HOT map before broad search.
4. Validate live/versioned SOUL equality, `git diff --check`, secret scan, audit
   log, gateway restart if SOUL changed, service active state, auto-push and
   `HEAD == origin/main`.
5. Do not roll out automatically to agents whose operating model is being
   rebuilt. If Rodolfo excludes an agent such as Atena during reconstruction,
   leave it untouched.

Detailed runbook: references/agent-hot-operational-maps-2026-06-16.md.

Phase 5 Hera Creative Ops alignment pattern:

1. Do not frame Hera as an assistant/subagent of Ares. Hera owns Creative
   Operations: creating static/video creatives, receiving human-created assets,
   organizing Drive/naming/inventory, and supporting both Ares and humans.
2. Ares is an optional consumer of approved assets, not the mandatory path for
   every creative. Kelly, Geizian and gestores may create or use creatives
   directly in campaigns; Hera still keeps assets organized.
3. Do not impose a rigid creative request form. Users should ask naturally in
   the Hera channel. Hera infers safely, asks only blocking questions, and the
   skill evolves from real usage.
4. Treat `CC_US_ES` as an example/pilot taxonomy aligned with Ares, not the only
   Drive operation. MGS-CRIATIVOS is multivertical; Hera must route each request
   or upload to the correct vertical/operation folder.
5. For multivertical naming, use the general model
   `{VERTICAL}_{COUNTRY}_{LANG}_{FORMAT}_{ANGLE}_{P_ORIENT}_{VARIANT}.{ext}`
   and adapt per operation as the real workflow stabilizes.
6. Inventory should track origin and consumer, at minimum: `created_by`,
   `requested_by`, `used_by`, `campaign_owner`, and `source`.
7. Creative metadata is a first-class handoff gate: Hera should clean assets
   before Drive/handoff, and Ares should verify/clean before campaign use. The
   canonical wrapper is `/root/mgs-agent/scripts/clean-creative-metadata.sh`;
   avoid deploying ExifCleaner/Electron on the VPS for agent workflows.
8. When aligning Hera files, patch live + versioned SOUL/skill/templates, verify
   live/versioned equality, validate with `git diff --check` and secret scan,
   restart/reload `hera-gateway.service` when SOUL changes, confirm Discord
   connected, and audit log.

Detailed runbooks: references/hera-creative-ops-natural-requests-2026-06-07.md and references/creative-metadata-sanitizer-hera-ares-2026-06-08.md.

Phase 5 Atena reconstruction gate pattern:

1. Do not apply the Zeus SOUL-alignment pattern directly to Atena. Atena is a
   production content agent with REC/P1/REC+P1, WordPress, images, Yoast,
   runners, contracts and historical bug references.
2. Before patching Atena, read the prior Atena reconstruction thread when
   Rodolfo references it (known thread id: 1512539907468558477) and reconcile
   what was approved there with the live VPS state.
3. Treat Atena's rebuild as layer separation, not a full code rewrite:
   SOUL = identity/governance; SKILL = operating procedure; contracts = article
   product specs; scripts/runners = factory/implementation; references =
   historical lessons to archive/distill, not active competing rules.
4. SOUL additions should stay high-level: Content Operations, Raquel supervision,
   complete request means authorization, escalation to Zeus, and boundaries
   against campaigns/creative/AdOps/infra/permissions/finance.
5. Never put runner commands, Yoast char limits, slug logic, WordPress steps,
   image implementation details, or long bug-history lessons into SOUL. Put them
   in SKILL/contracts/code validations as appropriate.
6. When patching Atena SOUL, keep live and versioned files identical:
   `/root/.hermes/profiles/atena/SOUL.md` and
   `/root/mgs-agent/profiles/atena-soul.md`. Create timestamped rollback backups
   for both before editing.
7. If the current SOUL lists stale skill status such as `content-generate-p1` or
   `content-generate-rec-and-p1` as “em desenvolvimento”, replace that with a
   layer statement: detailed operations live in `content-generate-rec`,
   `content-publish-wordpress`, contracts and runners. SOUL must not become a
   brittle feature/status registry.
8. After a SOUL-only alignment, validate at minimum: live/versioned cmp,
   `git diff --check`, secret scan on added lines, stale skill-status scan,
   audit log, auto-push and `HEAD == origin/main`.
9. If Rodolfo asks whether Atena should be notified, post a concise operational
   note in the Atena reconstruction thread explaining what changed and what did
   not change, then continue review there. Do not create a second parallel design
   thread.
10. For Atena SOUL authorization language, keep the article-request flow simple:
    Rodolfo and Raquel can request content by default. If anyone else requests
    an article, Atena should ask Rodolfo whether that person may request it,
    summarizing requester + requested article/product + site/status + official
    URL when available. The authorization options should be: `uma vez só`,
    `somente nesta sessão/thread`, or `sempre autorizada`; when the interface
    supports it, present those as buttons. Avoid overcomplicating this in SOUL
    with broad permission-matrix detail; detailed permissions live in MGS OS.
11. Rodolfo should continue design/review in the Atena reconstruction thread,
    mark files explicitly approved (`SOUL aprovado`, `SKILL aprovado`, etc.),
    then ask Zeus to read/apply. Zeus cannot assume live cross-thread context.
11. Only apply deeper SKILL/contracts changes after backup + diff + secret scan +
    audit log + auto-push + validation, preserving runners/scripts unless a
    specific targeted bug fix is approved.
12. If Rodolfo/Raquel approve new REC/P1 editorial contracts, do not stop at
    writing `contracts/cc-rec.md` and `contracts/cc-p1.md`. Immediately map and
    patch the deterministic runners/validators that must honor those contracts
    before declaring the phase ready for production. Contract-runner drift is a
    real operational risk.
13. For the current REC/P1 contract v2 baseline: P1 keyword count is 5–8 visible
    editorial uses; REC meta is 130–140 chars; P1 meta is 130–150 chars; P1 uses
    Details blocks; the card image can repeat in REC/P1 LazyBlocks but featured
    images must differ; long image composition rules belong in a reference file,
    not duplicated inside every contract.
14. When applying Atena SOUL Phase 1 packages, validate the content against the
    latest Rodolfo correction before applying — not just bash syntax, SHA, line
    count, or secret scan. The current simple article-request authorization model
    is: Rodolfo/Raquel execute directly; anyone else triggers a Rodolfo approval
    choice with three options: `Uma vez só`, `Somente nesta sessão`, or `Sempre
    autorizada` (buttons when supported). Avoid staging temporary SOUL files under
    `/root/mgs-agent/profiles/` because auto-commit may version them before
    cleanup; use `/tmp` for staging and write only final live/versioned files.
    See `references/atena-soul-phase1-application-2026-06-12.md`.

contract against live deterministic runners/validators before calling the
system production-ready. A contract update is an editorial source-of-truth
change; runner compatibility is a separate technical gate.

If the new contract requires structures the runner does not yet emit (e.g. REC H3 benefits/pros-cons/final CTA, P1 WordPress Details blocks, P1 5-8 keyword occurrences, REC meta 130-140 chars), apply the contract first only if approved, then report the runner migration as the next phase before any real production REC+P1.


Detailed runbook: `references/company-os-phase5-atena-reconstruction-thread-2026-06-07.md`.

CRONS.md review pattern:

```text
1. Treat `docs/CRONS.md` as generated documentation from the live root crontab.
2. Do not alter crontab/runtime during documentary review unless explicitly
   authorized.
3. If generated content is stale/wrong, patch `scripts/cron-control-plane.py`
   metadata first, then regenerate `docs/CRONS.md`.
4. Validate: total jobs, all jobs use flock, no `não classificado`, no `Sem
   descrição cadastrada`, `git diff --check`, secret scan on added lines, audit
   log, auto-push, HEAD=origin.
5. Known correction: `cleanup-zombie-sessions.sh` uses last real activity with
   default 180min grace, not the older 30min description.

Pitfall: old restructuring plans may say “next step: update company-os.md” even after that has already been done, or may duplicate “create derived docs” both before and after inventory. When reviewing the plan, update statuses and remove duplicated phases before proceeding.

Never combine broad reorganization with gateway restarts, cron rewrites, or production changes unless Rodolfo explicitly authorizes that combined scope.

7. Inventory deliverable format

After the blueprint, generate a migration inventory, usually under:

/root/mgs-agent/docs/mgs-structure-inventory.md

Preferred columns:

Path | Classe | Dono | Área | Status | Ação recomendada

Allowed actions:

manter
não tocar
mover
renomear
consolidar
arquivar
remover depois
revisar com Rodolfo

Use não tocar for sensitive live state such as data/sites.json, data/authorized-users.json, active runners, active crons, and Hermes patches unless there is a specific approved plan.

Phase 3 inventory is a risk map, not a line-by-line content review. If Rodolfo asks what he has to review or says he does not understand the technical classification, reduce the approval question to the operating assumptions: context/ is canonical/conceptual, data/ is runtime, scripts/ are productive automations, profiles/ controls agent behavior one agent at a time, and Phase 4 should start with old context/*.md files before runtime/data/scripts. Give a clear COO recommendation instead of asking him to inspect every path.

When writing the inventory, include the current structural classes explicitly: context/, profiles/, data/, scripts/, docs/, skills/, patches/, api/, tools/, backups/, experiments/, logs/, and sensitive root files such as .env/auth/credentials. See references/company-os-phase3-inventory-phase4-company-2026-06-07.md for the v0.2 inventory/review pattern.

8. Executive communication pattern

When asking Rodolfo to review a document, do not make him infer what matters from the raw file. Default to the SOUL-style review format:

1. O que faz sentido.
2. O que está demais / arriscado.
3. O que falta.
4. Pontos para Rodolfo classificar/corrigir.

Do not paste long files into chat for review. If Rodolfo asks to “show the file” or wants to read it like the screenshot example, send the current file as a native attachment (MEDIA:/tmp/<review-file>.md) so he can click/open it. Only paste the full file inline if he explicitly asks for inline content.

Discord formatting preference: avoid wide Markdown pipe tables when cells contain long prose. They render poorly on Discord/mobile and look like raw technical documents. Prefer either fenced text blocks with aligned short columns, or sectioned bullet blocks such as O que faz sentido, O que está demais / arriscado, O que falta, and Minha recomendação. Use Markdown tables only for compact labels/values that will not wrap badly.

Always separate:

1. What changed / current file status.
2. The 5–10 operational decisions he actually needs to validate.
3. An attached file copy when he wants to inspect the whole artifact.

If Rodolfo says the review is confusing, switch from file content to decision-level validation: “you only need to confirm whether these statements are true.”

Arquivo: path/to/file.md

O que faz sentido
-----------------
- keep / correct operational points

O que está demais / arriscado
-----------------------------
- overlong, redundant, risky, or wrong points

O que falta
-----------
- missing concepts / rules / operational details

Pontos para Rodolfo classificar/corrigir
----------------------------------------
1. concrete decisions for Rodolfo

If Rodolfo asks to “show the file” or wants to read it whole, do not paste the entire markdown into chat. Create/send it as a native attachment (MEDIA:/tmp/...md) so he can click and open the full file, matching the Discord preview/card style he prefers. Use a concise note plus the attachment. Inline full-file dumps are hard to read and should be avoided unless he explicitly asks to paste content.

If Rodolfo says the review is confusing, switch from raw file content to decision-level validation: “you only need to confirm whether these statements are true.”

If Rodolfo asks to review the raw file, send it as a MEDIA:/absolute/path attachment instead of pasting long markdown into Discord. He explicitly prefers attachments for SOUL/context/skill review files; paste only short excerpts or decision tables in chat.

Good pattern:

Decisão                         Confirmação
------------------------------- ------------------------------------------------
Ares                            Campanhas only; no ChatPion/quiz/SMS.
Hera                            Criativos + Drive.
Google Drive                    Source of approved creatives; Hera/Ares R/W.

Avoid overexplaining. Give an operational opinion and the next concrete step.

Pitfalls

Losing long-thread context: in Company OS/restructuring threads, treat the thread as a persistent workstream until Rodolfo explicitly finalizes or changes objective. A short reply like “Ok”, “continue”, or “próximo” inherits the quoted/previous block context (phase, block, file) and must not be treated as a new standalone topic.
Renaming an active restructuring thread: do not auto-rename an already-open Company OS thread while the objective is still the same. Never rename based on a short reply or quoted status. Thread title changes only make sense before/at creation or after a clear new objective with strong context. If a rename is genuinely required, preserve the workstream language; do not translate a PT-BR Company OS title into Spanish/English.
Moving before mapping: creates broken imports, stale references, and agent confusion.
Treating current structure as garbage: many existing MGS files are production-critical and should be wrapped, not replaced.
Letting agent prompts be the architecture: prompts should consume the company OS, not be the only source of it.
Mixing concept and runtime: context/ is not data/; docs/ is not scripts/.
Deleting backups/experiments too early: classify first, archive later, delete only after explicit approval.
Updating agents too early: validate blueprint with Rodolfo before changing Zeus/Atena/Ares behavior.
Skipping derived-doc approval: after creating areas.md, agent-map.md, routes.md, sources-of-truth.md, and permissions-matrix.md, review/approve them one by one with Rodolfo before Phase 3 inventory. Do not treat the older canonical/runtime files listed inside sources-of-truth.md as Phase 2 manual-review targets; they belong in Phase 3 classification.
Over-assigning Ares: Ares owns campaigns, not every acquisition-adjacent system. ChatPion/DigitalTrChat is configured by Rodolfo/Geizian/gestores; quiz/SMS/SMS Funnel setup is Rodolfo.
Duplicating source-of-truth rules everywhere: detailed Regra de conflito sections belong mainly in context/sources-of-truth.md. Domain files like sites.md, team.md, acquisition.md, etc. may have a short note about their role, but avoid repeating full conflict matrices unless the file specifically governs source priority. Redundant rules make review harder and create drift.

Referências operacionais

references/hera-natural-gpt-grok-backend-routing-2026-06-16.md — padrão de Creative Ops para Hera aceitar pedidos naturais de backend (“com GPT”, “com Grok”, “os dois”, “avatar/vídeo”), mantendo Hera como dona de criativos e tratando GPT/OpenAI-Codex e Grok/xAI como ferramentas, não como agentes separados.
references/hera-ares-creative-taxonomy-sync-2026-06-07.md — sincronização Hera/Ares quando a taxonomia, Drive e Canva forem definidos em thread do Ares: Hera deve herdar a taxonomia CC_US_ES, MGS-CRIATIVOS, UPLOAD CANVAS, P_ORIENT PV/NV/PS/NS, inventário e gate de plano aprovado antes de renomear/mover criativos.
references/creative-metadata-sanitizer-hera-ares-2026-06-08.md — implementação do gate server-side de limpeza de metadados para criativos Hera/Ares: usar ExifTool/mat2 via wrapper MGS, validar com PNG malicioso PNG:Comment, atualizar context/SOUL/docs, auditar e reportar infra.
references/hera-creative-agent-bootstrap-ptbr.md — padrão capturado na criação da Hera: sequência segura de bootstrap de agente MGS, padronização PT-BR para SOUL/docs/skills/templates e regra de anexar arquivos longos como MEDIA:/path.
references/company-os-phase3-inventory-phase4-company-2026-06-07.md — padrão capturado na execução da Fase 3/Fase 4: inventário como mapa de risco, como explicar a revisão para Rodolfo, cobertura mínima do inventário v0.2 e padrão de primeiro bloco context/company.md.
references/company-os-phase4-context-continuity-crons-2026-06-07.md — padrão capturado na Fase 4 sequencial: continuidade de contexto em thread longa, “ok continue” como avanço de bloco, revisão de docs/CRONS.md sem alterar runtime/crontab, e correções de metadados via cron-control-plane.py.
references/company-os-thread-continuity-2026-06-07.md — pitfall de continuidade em threads longas de reestruturação: replies curtos herdam o bloco anterior, thread aberta não deve ser renomeada enquanto mantiver o objetivo, e o report deve continuar no formato executivo por fase/bloco.
references/company-os-thread-context-pitfall-2026-06-07.md — correção de contexto em threads longas: thread de reestruturação mantém objetivo/nome até finalização, replies curtos herdam o bloco/fase citado, e Ok/vamos continuar não são novo assunto.
references/company-os-thread-title-language-pitfall-2026-06-07.md — correção específica de título/idioma em thread longa: não renomear thread ativa por reply curto e nunca traduzir título PT-BR para espanhol/inglês por heurística genérica.

Verification Checklist

Before reporting completion of a company-OS step:

The deliverable exists at the declared path.
It is clearly marked proposal/canonical as appropriate.
No runtime file was changed unless explicitly approved.
Sensitive sources of truth were not modified accidentally.
Cross-file semantic consistency was checked against already-reviewed Company OS docs after any material Rodolfo correction.
Next step is concrete and low-risk.

References

references/company-os-blueprint-session-2026-06-05.md — session-specific origin: Bruno course context, current /root/mgs-agent structural counts, and first blueprint pattern.
references/mgs-os-map-hot-pointer-2026-06-15.md — map-of-maps pattern: full /root/mgs-agent/context/mgs-os-map.md for navigation plus compact HOT pointer in Zeus SOUL, reducing broad search without inflating SOUL.
references/company-os-ceo-operating-model-2026-06-05.md — CEO-described real MGS operating model: partners, Raquel/Kelly/gestores, Smart Bidding/ActiveView, finance cycle, campaigns, creative flow, and agent implications.
references/company-os-routes-review-2026-06-06.md — route/scope corrections: Ares vs Hera naming, gestores/UTM codes, ChatPion/quiz/SMS boundaries, Drive creative handoff, commission model, and review sequencing.
references/company-os-routing-growth-creative-2026-06-06.md — routing clarifications for Ares, Hera, gestores/UTM codes, ChatPion/DigitalTrChat/Messenger, quiz/SMS Funnel, Revenue/AdOps and gestor commission.
references/company-os-gestores-ares-finance-2026-06-06.md — gestor codes (utm_medium), Ares staged access, Creative/Kelly agent context, Zeus-only control, and gestor commission rules for Finance/BI.
references/company-os-review-corrections-2026-06-06.md — latest corrections from document review: Smart Bidding/ActiveView as Google partner AdX networks, Geizian as sócio, Ially office-manager role, Ares/Hera/Drive boundaries, and decision-level review style.
references/company-os-doc-review-format-sites-crons-2026-06-07.md — review-format and cascade lessons: SOUL-style summaries, send full docs as attachments, avoid duplicated conflict sections in domain docs, sites list update/count validation, and CRONS.md generated-doc review pattern.
references/company-os-review-style-sites-2026-06-07.md — review-format correction (SOUL-style summaries and full-file attachments instead of inline dumps), cascade-check expectations, and updated conceptual sites list notes.
references/hera-operational-architecture-bootstrap-2026-06-06.md — sequence correction after Hera technical bootstrap: gateway online is not production-ready; create operational diagram/context doc, align SOUL, create skills/templates, then controlled tests before opening to Kelly/Geizian/gestores.
references/hera-creative-ops-ares-taxonomy-alignment-2026-06-07.md — Hera/Ares Creative Ops alignment: Hera creates and organizes static/video creatives, supports human-created assets, Ares is an optional consumer, and CC_US_ES Drive/Canva taxonomy/inventory fields must be synchronized across Hera context/SOUL/skills/templates.
references/company-os-cascade-consistency-review-2026-06-06.md — cascade consistency checklist for sequential context-file review: stale-term cleanup, Ares/Hera/SB/AV/Ially/gestor-code boundaries, and file-display pattern when Rodolfo asks to review raw content.
references/company-os-team-acquisition-monetization-2026-06-06.md — approved/validated team and acquisition rewrites plus monetization v0.2 notes; includes Rodolfo's cascade-consistency expectation and verification checklist for stale/conflicting concepts.
references/atena-rec-p1-contract-v2-runner-alignment-2026-06-08.md — Atena REC/P1 contract v2 decisions and runner-alignment pattern: REC meta 130–140, P1 keyword 5–8 visible uses, P1 Details blocks, card-image vs featured-image distinction, and dry-run/unit validation before production.
references/atena-rec-p1-contract-v2-runner-gate-2026-06-08.md — REC/P1 contract v2 decisions from Raquel/Rodolfo, including P1 keyword 5-8, REC meta 130-140, new REC/P1 structures, slug cleanup, featured-image reference split, and the required runner/validator migration gate before production use.
references/atena-soul-and-phase2-cleanup-2026-06-13.md — Atena SOUL application and Phase 2 cleanup sequencing: 3-option article authorization, live/versioned SOUL sync, and why templates must wait until runner fallback is removed/proven unused.
references/atena-soul-phase1-application-2026-06-12.md — SOUL-only application lesson: validate final content against Rodolfo's latest authorization correction, write live+versioned files directly, avoid temp files inside auto-commit paths, restart/validate Atena, and keep Phase 2 runner/template changes separate.