Proposal: MultiAgentSystem v5 layered evolution plan

This issue is the formal discussion artifact for the v5 architecture proposal.

Purpose

Define the next evolution of multiagentsystem as a layered Agentic OS with explicit separation of:

• infra layer;
• runtime layer;
• agents layer;
• evolution layer.

The goal is to preserve the current canon while adding mechanisms for safe growth, source-driven research, model routing, recovery, worktree isolation and formal adoption of external ideas.

Why this is an issue, not a Discussion

Current repository canon says:

• framework tasks and disputes should use GitHub issues;
• PRs should carry concrete changes;
• system-level decisions must leave a traceable artifact.

Therefore this issue is the source-of-truth discussion artifact for v5.

Proposed layer model

1. Infra layer

Responsibilities:

• repository structure;
• GitHub issues / PRs / labels;
• optional GitHub Actions hygiene checks;
• future GitHub Discussions as non-canonical idea intake only.

Planned additions:

• issue labels for type:proposal, type:dispute, area:runtime, area:agents, area:evolution, version:v5;
• documentation of which GitHub artifact type is canonical for each workflow;
• optional issue templates.

2. Runtime layer

Responsibilities:

• local bash/tmux execution;
• file IPC;
• watchdog/coordinator;
• state recovery;
• target-pack activation.

Planned additions:

• heartbeat fields in STATE.md;
• ACK-based dispatch delivery;
• checkpoint support in task files;
• incremental retry logic;
• hash-based context cache;
• Git worktree isolation for parallel workers.

3. Agents layer

Responsibilities:

• agent roles;
• role prompts;
• task planning;
• audit and dispute behavior;
• model selection.

Planned additions:

• Socratic planning / PRD phase before execution;
• micro-specialization prompts over base roles;
• model tiering by task complexity, cost and latency;
• router policy for OpenAI/Anthropic-compatible endpoints;
• explicit fallback strategy when a model/provider fails.

4. Evolution layer

Responsibilities:

• intake of new external sources;
• source review;
• proposal creation;
• dispute handling;
• promotion of accepted patterns into canon.

Planned additions:

• EVOLUTION.md;
• research/ folder for source reviews;
• adrs/ or decisions/ folder for accepted/rejected design decisions;
• evolution issue template;
• source provenance matrix;
• rule: no external feature enters canon without source, rationale, risk review and adoption decision.

External ideas considered for v5

From oh-my-claudecode

Repository:
https://github.com/Yeachan-Heo/oh-my-claudecode

Ideas to adapt:

• Git worktrees for worker isolation;
• team-style planning/execution/verification pipeline;
• Socratic planning / clarification before execution;
• model tiering by task type;
• command/trigger-based task entry;
• micro-specialized agents.

Adoption approach:

• Prefer reimplementation in our own bash/tmux/GitHub-native style.
• Direct code reuse is possible only after preserving license/copyright notices where required.

From auto_ai_router

Repository:
https://github.com/MiXaiLL76/auto_ai_router

Article:
https://habr.com/ru/articles/1027878/

Ideas to adapt:

• model/provider router;
• fallback between providers;
• OpenAI/Anthropic-compatible abstraction;
• cost-aware routing;
• latency-aware routing.

Adoption approach:

• Do not embed as a mandatory service initially.
• Start with a lightweight router policy inside orchestrator/coordinator config.

From additional analysis reports

Ideas to adapt:

• checkpoints;
• heartbeat-based recovery;
• ACK-based message delivery;
• incremental retry;
• context levels;
• sha256 cache for unchanged context files;
• hybrid model: GitHub as control plane, local runtime as execution plane.

Initial decision proposal

Adopt v5 as an incremental evolution, not a rewrite.

Order of implementation:

1. Add evolution canon docs: EVOLUTION.md, research templates, decision templates.
2. Add GitHub labels/templates for proposals and disputes.
3. Extend STATE.template.md with heartbeat/recovery fields.
4. Extend task template with checkpoints and evidence fields.
5. Add dispatch ACK contract.
6. Add model routing policy document.
7. Add worktree isolation design, then implement after agreement.
8. Add micro-agent prompt loading.
9. Add Socratic planning phase.

Open questions

1. Should EVOLUTION.md be mandatory read-order material in AGENTS.md?
2. Should accepted decisions live in adrs/ or decisions/?
3. Should worktree isolation be mandatory for all executor tasks or only parallel tasks?
4. Should model routing live in runtime config or agent policy docs?
5. Should GitHub Discussions be enabled only for informal idea intake, while Issues remain canonical?

Acceptance criteria

This proposal is ready for implementation when:

• the layer model is accepted or corrected;
• the evolution mechanism is accepted or corrected;
• canonical artifact rules are clarified;
• implementation order is approved;
• any conceptual conflicts are split into type:dispute issues.

Next artifact after agreement

Open a PR that adds:

• EVOLUTION.md;
• research/README.md;
• research/SOURCE_REVIEW_TEMPLATE.md;
• decisions/DECISION_TEMPLATE.md or adrs/ADR_TEMPLATE.md;
• updates to AGENTS.md, OPERATIONS.md, PRINCIPLES.md, STATE.template.md, and task templates.