RoleOS

RoleOS is my pattern for turning the recurring work of a professional role into a filesystem an AI agent can navigate. Its purpose is to make the role’s context, functions, standards, and handoffs inspectable by the person responsible for the work.

The structure is deliberately ordinary: folders, Markdown, schemas, and run records. The sophistication belongs in how those pieces relate. A person should be able to find the definition of a function, see what it is allowed to do, and understand how to correct its output.

Start with a role that someone recognizes

Much of a professional’s work combines habit, institutional knowledge, relationships, and judgment. Some of it is written down. Some appears only when something goes wrong. RoleOS begins by asking the person to make that structure explicit.

A repeatable function is a unit of work performed more than once. It may begin on a schedule, after an event, or when someone asks for it. A renewal review and a customer complaint have different triggers, but both may contain recurring steps, required evidence, and recognizable outputs.

I would not force every role into the same number of functions. The useful level is the one at which each function has a coherent purpose and can be reviewed independently. The first mapping should include exceptions, reactive work, and decisions that remain with a person.

In the language of ThoughtSpace, this is a way to turn some of a role’s bounded context into working artifacts. It does not capture everything a person knows, and a folder alone does not make a role autonomous.

Five layers and three scopes

The role owns the first two layers. Layer 0 establishes identity through WHO_I_AM.md: what the role exists to produce, who it serves, what success means, and what it explicitly does not own.

Layer 1 maps the role’s functions and shared operating context. FUNCTION_MAP.md lists the functions and their triggers. INFRASTRUCTURE.md describes shared tools, access boundaries, and rules. PIPELINE.md describes how functions connect.

The next two layers belong to a function. Layer 2 uses FUNCTION.md to define its trigger, required and optional inputs, task sequence, output, success criteria, and handoff. Layer 3 contains the reference material that governs its work: standards, tools, trigger configuration, error handling, escalation, and reusable skills.

Layer 4 belongs to a run. Its workspace holds the input, working notes, output, handoff, review flags, and contextual memory. Keeping these scopes distinct prevents one execution’s temporary details from quietly becoming a role-wide rule.

role/
├── OPERATOR_INSTRUCTIONS.md
├── SESSION_INIT.md
├── WHO_I_AM.md
├── FUNCTION_MAP.md
├── PIPELINE.md
├── INFRASTRUCTURE.md
├── CHANGELOG.md
├── relationships/
├── skills/
└── functions/
    └── 01_function_name/
        ├── FUNCTION.md
        ├── STANDARDS.md
        ├── TOOLS.md
        ├── TRIGGER_CONFIG.md
        ├── ERROR_PROTOCOL.md
        ├── ESCALATION.md
        ├── METRICS.md
        ├── skills/
        └── workspace/
            ├── INPUT.md
            ├── SCRATCHPAD.md
            ├── OUTPUT.md
            ├── HANDOFF.md
            ├── REVIEW_FLAGS.md
            ├── MEMORY.md
            └── runs/

The directory is a specification and a record of work. An execution environment still has to read it, connect tools, enforce permissions, run schedules, and preserve state. Writing a trigger in a file describes what should happen; a scheduler or event listener makes it happen.

A session needs an explicit starting point

OPERATOR_INSTRUCTIONS.md is the owner’s manual. SESSION_INIT.md is the agent’s initialization sequence. They serve different readers.

The sequence begins with role identity, the function map, shared infrastructure, and the routing graph. It then loads the relationship index and the active function’s specification, standards, tools, triggers, error rules, and escalation paths. Relevant memory comes next, followed by input validation.

Before execution begins, the system should know which function is active and whether the required input is available. A missing account identifier should produce a request or a defined stop, rather than an improvised substitute that contaminates every downstream step.

This ordering also supports selective loading. A role can know that a function exists without loading every instruction and every relationship into every run.

Functions describe work; pipelines describe routing

A function needs to know what it produces and what a valid handoff contains. The pipeline decides which function receives that handoff, under what conditions, and whether a person must approve the transition.

For an onboarding example, completed intake may permit proposal preparation. An approved proposal may permit contract preparation. A signed contract may permit kickoff. A proposal above an authority threshold should create an approval request before the next stage. The threshold is a policy choice belonging to the organization.

PIPELINE.md records those transitions, merge points, early exits, and manual gates. Keeping routing outside the function helps reuse the same function in more than one process.

TRIGGER_CONFIG.md then specifies how a particular function begins: an operator request, a schedule, a detected event, or a pipeline transition. It also describes cooldowns, prerequisites, and what to do if a new trigger arrives while the function is already running.

Errors and escalations are different

ERROR_PROTOCOL.md describes failures and recovery. Input failures include missing or malformed fields. Tool failures include timeouts and unavailable services. Output failures include results that do not meet the function’s success criteria. Dependency failures occur when an upstream result is absent or invalid. Ambiguity can also be a reason to stop when the available evidence does not support a choice.

The response should be specific to the function. A retry may make sense for a read operation; repeating a write requires knowing whether the first attempt took effect. A partial result may be useful for review while still being unsuitable for a downstream handoff.

ESCALATION.md handles a different situation: the system is functioning, but the next decision exceeds its authority. It identifies the decision owner, the context to include, the recommendation, the urgency, and what happens when a response arrives.

An escalation should be a usable decision request. “Something went wrong” is not enough. The person needs to know what happened, what the system knows, what remains uncertain, and what they are being asked to decide. The request and response belong in the run record.

Make review specific without making it blind

OUTPUT.md contains the deliverable. REVIEW_FLAGS.md points to assumptions, ambiguous inputs, authority thresholds, uncertain claims, and substituted dependencies. Each flag should identify the relevant output location and the decision or verification needed.

For example, a budget estimate derived from a prior quarter can be marked as an inference, with its source and a request to verify it before use. This is more useful than a global confidence label attached to the entire document.

Flags help focus attention, but an empty flag file is not proof that an output is correct. The system may fail to notice its own error. The appropriate review level depends on task risk and observed performance, with sampling or fuller review where necessary. Selective review is something to earn through evidence.

SCRATCHPAD.md can hold calculations, source references, intermediate artifacts, and concise decision notes useful to the operator. The architecture should rely on inspectable evidence and outcomes, rather than assume that a saved explanation exposes a model’s complete internal reasoning.

Separate facts from standards

STANDARDS.md defines how a function should work. MEMORY.md records relevant facts about a situation. “Use this approved report format” is a standard. “This customer’s renewal date changed” is contextual memory.

Memory entries need a source or run reference, a date, and a review or expiry rule where appropriate. Candidate memories extracted from a handoff should be distinguishable from confirmed facts. Otherwise, a mistaken interpretation can become persistent context.

The relationships/ directory holds counterparty context: relevant agreements, communication preferences, active commitments, and recent interactions. Load it when the function needs it. Personalization should be based on relevant, authorized information, not an unrestricted accumulation of everything the system can find.

Four streams feed improvement

I want each run to leave evidence in four forms. EDITS.md records what the person changed and why. METRICS.md records time, edit rate, error classes, review flags, and handoff outcomes. REVIEW_FLAGS.md records uncertainty and authority gaps. MEMORY.md records confirmed context that may matter later.

An archived run preserves its input, output, handoff, flags, edits, and a metrics snapshot. A cumulative trend is easier to interpret when the underlying run records remain available.

A falling edit rate may be encouraging, but it needs interpretation alongside output quality and actual use. People may edit less because the work improved, because they stopped checking, or because they stopped using the output. Metrics should lead to investigation rather than automatically certify success.

Improvement is a deliberate promotion step

The review process looks for patterns across those streams. A recurring correction may become a standard. Repeated missing inputs may change the function schema. A recurring exception may require a new error path. Confirmed relationship context may move into the relevant counterparty record.

I deliberately separate observation from promotion. One edit may be a preference, a temporary exception, or a mistake. The proposed change needs a rationale and an evaluation before becoming the new default.

CHANGELOG.md records what changed, why, who approved it, and which version was introduced. Versioned standards make it possible to ask what governed a particular run and to roll back a harmful change.

Individual and institutional contexts

The same structure can be centered on an individual or on a role inside an institution. An individual version emphasizes that person’s working methods and preferences. An institutional version emphasizes company standards, shared relationships, and continuity when responsibilities change hands.

Portability does not mean every file can travel with a person. Company records, customer information, credentials, and proprietary procedures have their own ownership and access boundaries. The distinction is useful precisely because it forces those boundaries to be considered.

An institutional workspace can help a new colleague understand the role, but it does not replace training, judgment, or access provisioning. The objective is a more explicit starting point.

Where I would use this pattern

RoleOS is aimed at repeatable, reviewable professional workflows with a clear operator. The plain-text structure is useful when people need to inspect and improve the work directly.

A shared folder alone is not a coordination system for high-concurrency workloads or tightly coupled agents. Those cases need additional state management, isolation, scheduling, and orchestration. The architecture should be chosen for the work rather than stretched until its boundaries disappear.

That boundary is part of the appeal. RoleOS makes one level of the larger model concrete: an understandable role, defined functions, explicit handoffs, and a record from which people can learn.

Adapted for this notebook from my RoleOS Framework Specification v2.0 (Apr 2026).