MultiAgentOS

Imported from nyvlemyt/MultiAgentOS (AGENTS.md). Install upstream with npx skills add nyvlemyt/MultiAgentOS. Copyright stays with the author.

AGENTS — MultiAgentOS Roster

1. Two tiers

Tier A — Orchestrator agents (new, MultiAgentOS-specific). Live in packages/agents/fiches/. They own the mission lifecycle, route work, and call Tier B. They never do specialized execution themselves.

Tier B — Library agents (pre-installed). 60 fiches already under .claude/agents/ (agency-style + NEXUS doctrine). They do specialized execution. MultiAgentOS treats them as callable functions: a Tier A agent emits delegate({ agent: "engineering-frontend-developer", task: {...} }). These 60 are the raw source pool and are not scanned into a router index. Separately, the ECC harvest mirrors 32 cold Tier B fiches into packages/agents/library/ — that set is router-indexed (loadAgentLibraryIndex()) and is the callable cold arsenal at runtime (§6.bis). The two counts measure different things; neither is a subset claim.

The dispatcher is the only path between tiers. Tier B never calls Tier A.

2. Canonical Tier A fiche schema

---
id: skill-router
name: Skill Router
emoji: 🧭
avatar: packages/agents/avatars/skill-router.svg
status_visible: true                # surfaces in /studio network view
tier: A
role: "Decide which skills + which Tier B agents handle a given task."
domains: [all]
responsibilities:
  - Classify task type
  - Pick required + favorite skills
  - Select Tier B agent(s)
  - Estimate token budget
  - Justify selection in ≤3 lines
limits:
  - Never executes work itself
  - Never invents skills not in the registry
favorite_skills: [skill-creator, caveman]
required_skills: [using-superpowers]
permissions:
  fs_write: false
  shell: false
  network: false
budget:
  default_tokens: 1500
  model: claude-haiku-4-5
quality_criteria:
  - Justification cites concrete signal from the task text
  - Budget estimate within ±25% of real cost on rerun
output_format: json
common_mistakes:
  - Loading skills "just in case"
  - Picking 5+ agents for a 1-file change
escalate_when:
  - No agent matches with confidence ≥0.6
  - Task contains words like "trading", "payment", "send email", "deploy"
---

Body in Markdown: full responsibilities, examples of good vs bad output,
JSON schema of the expected response, common failure modes with fixes.

3. Tier A roster — shipped fiches (10)

The Tier A agents that ship as complete fiches in packages/agents/fiches/ today. The first six were the MVP slice; quality-controller (Phase 3.5), then orchestrator + agent-evaluator (Phase 9 · 0c) joined the governance layer; and architect (Bloc C) promoted the domain-modelling + ADR-authoring role out of the §4 backlog into a shipped fiche. Every row is enforced at load by validateFiche() (§2/§10).

4. Tier A roster — Phase 2 backlog (not yet shipped)

quality-controller and architect have since shipped — they live in the §3 roster now, not here. The rows below are the remaining backlog targets; provider hints are aspirational and gated by paid_apis_enabled (CLAUDE.md §11.bis).

researcher / Perplexity routing (§11.bis). The provider hints above are targets — these agents are not yet shipped. When researcher is built, Perplexity (and any paid third-party provider) is reached via an MCP/subscription path, gated behind paid_apis_enabled (default OFF, CLAUDE.md §11.bis); it must never be silently wired to a billed REST endpoint, and the Anthropic-PAYG ban (§11) stays absolute regardless of provider.

Quality Controller — shipped (§3). Full spec: packages/agents/fiches/quality-controller.md. In one line: the Reviewer checks the CODE; the Quality Controller checks that the PROCESS and RULES (CLAUDE.md conventions, Conventional Commits, no architecture drift without an ADR, justified token spend, output language) were respected — it gates post-execution, before the Reviewer.

5. Tier A roster — Project-specialized (later, on demand)

Thin wrappers that pre-bind a Tier A behaviour to a project type:

• Manga App Lead
• Community / Gamification Agent
• WhatsApp / Telegram Bot Agent
• Business Website Audit Agent
• Agency Client Delivery Agent
• Media / Social Content Agent
• Email Automation Agent
• AI News Analyst
• Finance Portfolio Analyst (later)
• Trading Bot Safety Reviewer (later, mandatory gate on any trading task)

Each one preselects: relevant Tier B agents, project-scoped skills, memory scope, and a default risk floor.

6. Tier B delegation map — MVP slice

The Tier B agents wired in MVP and who calls them (8 MVP rows + the scoped pilot):

Called-by column = intended ownership, not shipped wiring. Frontend Builder, Backend Builder, UX/UI Critic and Docs Writer are §4 Phase 2 agents — not yet shipped; today these delegations are issued by the dispatcher and the shipped Tier A agents (§3). The live runtime wiring is TIER_B_DELEGATION_MAP, keyed by Tier B id in packages/agents/src/library.ts, not these named callers.

Domain-scoped pilot. security-defensive-specialist is the first light agent of the arsenal-runtime-wiring slice: it carries no fixed skill bag. Its delegation entry holds a scope ({ domain: 'security', clusterPrefix: 'cyber:' }); at plan-time domainScopeFor(agentHint) — the planner's agentHint, taken by the function as its agentId parameter (hint and id share one string space here) — feeds that scope to selectLibrarySkills (@mas/skills), which picks the best cold-library skills within that scope and injects their L1 summaries. Posture is defensive-only (detect/mitigate/analyze, never offensive — CLAUDE.md §5). Generalising scoped selection to the other domain agents is the next cycle.

6.bis Cold agent library (ECC harvest)

Beyond the wired Tier B slice, the ECC harvest deposited 32 cold Tier B fiches in packages/agents/library/<id>.md (mirror of the cold skills arsenal in packages/skills/library/; distinct from the 60-fiche .claude/agents/ source pool of §1, which is not router-indexed). They are not auto-registered; they are scanned into a router-readable packages/agents/library/index.json (a generated, gitignored build artifact — regen via pnpm --filter @mas/agents build-library-index) and loaded on demand via loadAgentLibraryIndex() in packages/agents/src/library.ts. The dispatcher consults this index the same way mas-skill-router consults the cold skills index — discover first, register/delegate on need.

7. Files to create at MVP

packages/agents/
├── fiches/                 # 10 shipped Tier A fiches (§3)
│   ├── mission-planner.md
│   ├── orchestrator.md
│   ├── skill-router.md
│   ├── context-manager.md
│   ├── memory-keeper.md
│   ├── quality-controller.md
│   ├── reviewer.md
│   ├── sec-reviewer.md
│   ├── agent-evaluator.md
│   └── architect.md
├── avatars/                # stylized SVG avatars per Tier A agent
│   ├── mission-planner.svg
│   ├── orchestrator.svg
│   ├── skill-router.svg
│   ├── context-manager.svg
│   ├── memory-keeper.svg
│   ├── quality-controller.svg
│   ├── reviewer.svg
│   ├── sec-reviewer.svg
│   ├── agent-evaluator.svg
│   └── architect.svg
├── registry.ts             # loadTierAFiches → validateFiche() guard (§2/§10) + indexes Tier B
├── dispatch.ts             # orchestrator loop: delegate() + risk gate + budget + eval-loop
├── reviewers.ts            # real critics incl. realAgentEvaluator (transverse judge)
└── prompts/
    └── tier-b-system.md    # shared system preface for delegated calls (a shared contract, not a fiche)

Tier B agents inherit a default avatar derived from their domain prefix (engineering-* → cog, design-* → palette, etc.); they can be overridden later by dropping an SVG in packages/agents/avatars/library/<id>.svg.

8. Agent runtime contract

Every Tier A agent receives a MissionContext:

type MissionContext = {
  mission: { id; title; objective; autonomy; risk; budgetRemaining };
  project: { id; slug; contextPackPath; memorySummary };
  task: Task;
  prior: Event[];                 // last N events for this mission
  skills: SkillRef[];             // hydrated by Skill Router
  tools: {
    delegate(to: string, subtask: Task): Promise<TaskResult>;
    proposeMemory(item: MemoryCandidate): void;
    requestValidation(action: string, risk: 'high' | 'blocking'): Promise<boolean>;
    requireSkill(id: string): Promise<void>; // forces hydration
  };
};

It returns a TaskResult:

type TaskResult =
  | { kind: 'done';            outputs: Artifact[]; memoryCandidates: MemoryCandidate[] }
  | { kind: 'blocked';         reason: string; suggested_next: string }
  | { kind: 'needsValidation'; action: string; risk: 'high' | 'blocking' }
  | { kind: 'delegate';        to: string; subtask: Task };

9. Output discipline

• Tier A internal reasoning passed agent-to-agent: Caveman style when mode = eco (see TOKEN_STRATEGY.md §6).
• Final artifacts for the user: normal style.
• Diffs: unified patch format applied via git apply --check before being accepted.
• Reports: Markdown with H2 sections; first paragraph is a 2-line TL;DR.

10. Authoring rule

When creating a new Tier A fiche, copy the schema in §2 verbatim and fill every key. Empty keys are not allowed. This is enforced at load: registry.ts runs validateFiche() over every fiche and loadTierAFiches() throws if any mandatory key (incl. escalate_when, limits, responsibilities) is missing or empty (Phase 9 · 0c, finding U3). Typing the fields alone caught nothing — U1 was a mandatory key silently missing; validateFiche() closes that gap.

Keep each agent's tool surface ≤ 7 — the MLOps "≤7 tools per agent" rule (docs/knowledge/agent-patterns.md). The fiche's effective tools are its favorite_skills + required_skills plus the runtime tools in §8 (delegate, proposeMemory, requestValidation, requireSkill); an agent that needs more than seven is a decomposition smell — split the responsibility rather than widen the surface.

11. Forbidden patterns

• A Tier A agent calling another Tier A agent directly (route through the dispatcher).
• A Tier B agent reading/writing files outside its sandbox path (enforced in dispatch.ts).
• An agent loading a skill body it did not declare in required_skills or hydrate via requireSkill().
• An agent writing to data/memory/ directly — only Memory Keeper holds that pen.