OSTwin is an operating system for AI agents. It takes a markdown plan, decomposes it into a dependency graph of epics, spins up isolated war-rooms, and orchestrates role-based agents to execute each epic — all without writing a single line of agent code.
The Problem
Building with AI agents today means fighting three unsolved problems:
Problem
What happens
OSTwin’s answer
Agent sprawl
Every task gets a new bespoke agent. Config drifts. Nothing is reusable.
Roles + Skills compose agents from portable building blocks
Context explosion
Agents share one massive context. Prompt pollution kills quality.
War-rooms isolate each epic’s context, memory, and tools
No isolation
One agent’s bad tool call corrupts another’s state. No blast radius control.
MCP servers are scoped per war-room. Filesystem boundaries enforced
Agile improved software delivery by shortening feedback loops, but many teams still run a waterfall-shaped decomposition pattern inside their Agile ceremonies. One person or a small group writes a large plan, the team breaks it into many isolated tasks, and the results are merged back together later with a new round of coordination effort.
Delivery flow contrast
From late merge pressure to controlled agent rooms
The old pattern waits until many local task contexts reconnect before the real system appears. In agentic delivery, that delay turns small ambiguity into fast-moving integration risk.
Old loopPlan, split, merge, repair
01Single planner effortone large plan absorbs product and system intent
Human 56%Agent 44%
mixed drafting and steering
02Team decompositionwork becomes separate implementation tasks
Human 52%Agent 48%
mixed task splitting and expansion
Task Alocal contexthidden assumptions
Human 49%Agent 51%
human prompts, agent produces
Task Blocal contextduplicated decisions
Human 46%Agent 54%
human interprets, agent expands
Task Clocal contextlate conflicts
Human 51%Agent 49%
human checks, agent patches
03Merge-and-repair effortbugs surface after separate contexts reconnect
Human 58%Agent 42%
mixed debugging, heavier human repair
context lossunclear ownershipintegration bugs
OSTwin loopSlice, isolate, verify, integrate
01Planproduct + system contract
Human 72%Agent 28%
human-led product and design judgment
02DAGdependency-aware slices
Human 18%Agent 82%
agent-heavy graph decomposition
03Roomsisolated epic teams
Human 16%Agent 84%
agents run scoped execution loops
04ReviewQA evidence per handoff
Human 32%Agent 68%
agents test, humans judge exceptions
05Artifactsmerge-ready outcomes
Human 22%Agent 78%
agents package evidence-backed output
EPIC-001Room contextrole + skill + scoped tools
QA gateEvidence before mergeacceptance criteria and regression checks
ArtifactMerge-ready outputtraceable result, not a late surprise
Each epic becomes a controlled room with its own boundary, memory, lifecycle, and review loop. Integration happens after evidence, not after guesswork.
With AI agents, that pattern becomes more fragile. Agents can produce work quickly, but if the plan is too large, the task boundaries are too thin, and the merge point is late, small misunderstandings multiply into buggy artifacts that are hard for people to control. OSTwin replaces that late-merge loop with explicit epic boundaries, dependency-aware rooms, role-scoped context, and review evidence at every handoff.
Most multi-agent systems treat agents as long-running processes with hardcoded capabilities. OSTwin inverts this: agents are ephemeral sessions assembled on demand from composable building blocks. The building blocks are portable, the sessions are disposable, and the coordination is filesystem-native.
A plan defines the outcome. Epics divide that outcome into executable promises. Each epic becomes one war-room. The war-room launches the roles named by the epic, and each role receives only the skills that make sense for that room. Downstream epics inherit useful outputs through the DAG and shared memory, but they still run with their own role instances, tools, channel, lifecycle, and skill set.
Three Axes of Agent Identity
OSTwin defines every agent through three orthogonal axes. This is the core abstraction that makes the system composable:
Identity (WHO)
│
│ role.json + ROLE.md
│ personality, constraints, style
│
├──────────── Expertise (WHAT)
│ │
│ │ SKILL.md files
│ │ domain knowledge, workflows
│ │ loaded on demand
│
└──────────── Execution (HOW)
│
│ MCP servers
│ scoped tool access
│ isolated per war-room
Identity is stable — an architect role always reasons like an architect. Expertise is swappable — the same architect can load Unity skills or web skills. Execution is isolated — each war-room gets its own filesystem boundary, lifecycle, message channel, memory view, and tool sandbox.
The Engine parses your PLAN.md into structured epics.
A DAG resolves the logical flow between epics and sorts them into execution waves.
Each epic gets a War-Room: an isolated team room with its own channel, lifecycle, artifacts, memory view, and optional Git worktree.
Agents are composed at runtime from roles, relevant skills, and scoped MCP tools, then execute inside their war-room.
A lifecycle state machine governs each room’s progress: work, review, retry, triage, and final done or failed outcome.
Flow Concepts
The DAG is the plan’s delivery map. It is not just a visual dependency chart; it tells the manager which epics can run in parallel, which epics must wait for upstream outputs, and which downstream rooms should be blocked if an upstream dependency cannot be completed. A DAG edge means “this room needs that room’s result before it can safely start.”
An epic is a team, not a single prompt. When OSTwin starts an epic, it creates a war-room where the assigned roles collaborate under the manager. The engineer may implement, QA may review, an architect or specialist may advise, and the manager coordinates the handoffs. When roles disagree or a review fails, the manager routes the conflict through retry or triage, weighs the evidence in the room channel, and decides whether to fix, revise, block descendants, or continue.
The flow also keeps code and assets inside the delivery path. In room-worktree isolation, each epic works in its own Git worktree. When a room reaches a successful terminal outcome, its code changes, generated assets, research reports, and other durable artifacts can be committed on that room branch and integrated before dependent epics begin. Downstream teams then inherit real repository state, not just a chat summary.
During epic ramp-up, OSTwin resolves the team’s expertise before work begins. Role defaults, plan-level skill references, room-level needs, and discovered task keywords are merged into a skill set for that room. The agent sees a lean skill index first, then loads full skill instructions on demand, so a backend epic, UI epic, audit epic, or deep-research epic can all use the same role identity with different runtime expertise.
Because role identity and skill expertise are separate, two epics can use the
same role differently. engineer can be a backend implementer in EPIC-002, a
frontend maintainer in EPIC-003, and a release fixer in EPIC-004 simply by
changing the skills resolved for that room.
Key Design Decisions
Filesystem coordination — JSONL channels, JSON status files, markdown plans. No database required. Git-friendly. Every agent can read/write with basic file I/O.
Scale on depth, not width — Instead of many shallow agents, OSTwin uses fewer stable roles with deeper, room-specific skill resolution.
Config over code — Agents are defined by role.json + ROLE.md + SKILL.md, not Python classes. Non-engineers can modify agent behavior.
Ephemeral agents — No persistent agent processes. Each session is composed fresh from its role, skills, and tools. No state leaks between runs.
