AWP Agent OS: 98 O*NET Occupation Roles That Turn AI Agents into Domain Experts

Most AI agent roles are one sentence deep. When you tell an AI agent "you are a lawyer," it performs like someone who skimmed a single Wikipedia article about law. It knows surface facts but lacks everything that makes a real expert effective: pattern recognition, conditionalized judgment, retrieval fluency, and calibrated self-monitoring.

AWP Agent OS fixes this. It turns official U.S. O*NET occupational data — the U.S. Department of Labor's public database describing more than 1,000 occupations — into loadable professional operating systems. Each occupation becomes seven structured documents totaling 30,000+ words of profession-specific expertise that an AI agent reads and becomes.

This guide covers everything: why we built it, the cognitive science behind the framework, the seven-document architecture, a source code walkthrough, setup tutorials for every major agent CLI, and how to contribute new roles.

Why AI Agents Need Professional Expertise

Large language models contain vast professional knowledge from training data. A model trained on legal documents, medical literature, and engineering specifications already "knows" enormous amounts about these professions.

The problem is not knowledge volume — it is knowledge organization.

When you ask a general-purpose AI agent to review a contract, it reads every clause equally. A real lawyer spots the liability clause that could bankrupt the client within seconds.

When you ask an agent to assess a patient, it takes statements at face value. A real nurse notices the vital signs that contradict what the patient is saying.

When you ask an agent to review a blueprint, it treats all walls the same. A real civil engineer instantly identifies the load-bearing wall that cannot be moved.

The National Research Council's landmark study How People Learn (2000) synthesized several key differences between expert and novice cognition. The framework groups them into six dimensions:

1. Pattern recognition. Experts see meaningful patterns where novices see surface features.
2. Knowledge organization. Experts organize knowledge around deep principles, not surface categories.
3. Conditionalized knowledge. Experts know when each fact applies, not just that it exists.
4. Retrieval fluency. Experts have superior strategies for finding information.
5. Metacognition. Experts monitor their own reasoning and know when they are guessing.
6. Reflective learning. Expertise develops through deliberate reflection on experience.

A short persona prompt — "You are a financial analyst" — provides none of these. It is the equivalent of giving someone a job title and expecting them to perform like a 20-year veteran.

The Persona Prompt Ceiling

We surveyed every major open-source agent persona project as of July 2026. The results are stark:

For a complete picture, here is the full comparison:

Every existing project shares three limitations:

Author-invented descriptions. Role definitions come from what the author imagines a profession involves, not from empirical occupational data. This produces plausible-sounding but shallow expertise.

Single-file formats. One document cannot encode the multiple cognitive dimensions that constitute expertise. Pattern recognition, conditionalized workflows, retrieval strategies, and self-monitoring each require dedicated space.

No verification. Without test scenarios, there is no way to know whether a loaded role actually changes agent behavior or merely changes the agent's self-description.

What Is AWP Agent OS

AWP Agent OS is an open-source project that compresses decades of professional expertise into loadable documents for AI agents. Instead of a short persona prompt, each role gives the agent:

• A professional worldview — principles, decision frameworks, pattern recognition, cognitive traps
• Conditionalized workflows — step-by-step procedures for every major work scenario
• A retrieval toolkit — 50+ verified sources, tools, and search strategies
• Self-testing capability — 15+ scenarios that verify correct professional behavior
• Experience accumulation — memory that grows across sessions

The project currently includes 98 complete occupation roles across all 23 O*NET-SOC major groups, with 1,016 planned to cover the full U.S. occupational taxonomy.

Every role is built from official data in the O*NET 30.3 Database — the U.S. Department of Labor's comprehensive occupational information system that classifies over 1,000 occupations by tasks, knowledge, skills, abilities, work activities, and work context.

The repository works with Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, and any agent that reads project instruction files.

Repository: github.com/aiworkflowpro/awp-agent-occupational-os

Repository Structure at a Glance

awp-agent-occupational-os/
├── CLAUDE.md / AGENTS.md / GEMINI.md    Platform loaders
├── .github/copilot-instructions.md      GitHub Copilot loader
├── registry/
│   ├── occupations.json                 Full 1,016-occupation registry
│   ├── pilot-occupations.json           Initial pilot batch
│   └── v1-occupations.json              Version 1 release set
├── schemas/
│   ├── occupation-seed.schema.json      O*NET seed validation
│   ├── task-capability-map.schema.json  Execute/assist/human_only
│   └── resources.schema.json            Resource catalog validation
├── roles/                               98 occupation directories
│   ├── 11-1011.00-chief-executives/
│   ├── 15-1252.00-software-developers/
│   ├── 23-1011.00-lawyers/
│   └── ...
└── docs/
    ├── architecture.md                  System design
    ├── role-framework.md                Cognitive science foundation
    └── resource-bay.md                  Resource curation standards

The Cognitive Science Foundation

The framework is not a design exercise — every document exists because cognitive science research identified a specific dimension of expert cognition that must be encoded. Three research programs form the theoretical base.

Dreyfus Model: Expertise Develops Through Stages (1980)

Stuart and Hubert Dreyfus described five stages of skill acquisition:

The critical insight: at the expert level, performance no longer depends on explicit rules. Experts operate from deeply internalized patterns built through thousands of hours of practice.

For AI agents, the implication is direct. Role documents containing only rules ("always do X, never do Y") produce Stage 1-2 behavior. Documents that encode principles, patterns, decision frameworks, and self-monitoring protocols can produce Stage 3-4 behavior. Stage 5 requires accumulated experience — which is why the MEMORY.md document exists.

Ericsson: Deliberate Practice Builds Expert Performance (1993)

K. Anders Ericsson's 1993 research established that elite performance is built, not innate — it comes from deliberate practice, the sustained and structured effort of working at the edge of your current ability. His later synthesis (Peak, 2016) named the mechanism: experts develop refined mental representations, internal models that let them plan, monitor, and evaluate their own performance in real time.

For AI agents, the key insight is that an agent's "mental representation" is the document it loaded. If the document contains only surface knowledge, the agent operates like a novice with a textbook. If the document encodes deep principles, pattern libraries, conditionalized workflows, and self-monitoring checklists, the agent operates closer to an expert.

This is analogous to how a professional credential organizes existing knowledge into a reliable, accountable practice. LLMs already contain vast professional knowledge from training data. The role documents do not teach new facts — they activate and organize the model's latent knowledge.

National Research Council: Experts Differ in Knowledge Organization (2000)

The expert-novice differences that How People Learn synthesizes each map onto a specific document in the framework:

This is not decorative theory. Every document in the framework exists because research identified a specific cognitive dimension that must be explicitly encoded for an agent to move beyond surface-level performance.

The Seven-Document Architecture

Each occupation is packaged as a directory containing seven files. Together, they form a complete professional operating system.

roles/{code}-{slug}/
├── CLAUDE.md       Loading protocol (auto-read by agent CLI)
├── SOUL.md         Professional worldview — principles, thinking, judgment
├── WORK.md         Conditionalized knowledge — workflows, standards, quality
├── TOOLS.md        Retrieval mastery — sources, tools, search strategy
├── EVALS.md        Metacognition — 15+ test scenarios, output standards
├── MEMORY.md       Experience accumulation (starts empty, grows with use)
└── USER.md         User preferences (adapts to the human using it)

CLAUDE.md — Loading Protocol (~300 words)

The entry point. Auto-read by Claude Code when an agent enters the role directory. It declares the role's identity, O*NET-SOC code, capability summary (execute / assist / human_only task counts), and instructs the agent which files to read in what order.

It also sets execution rules: the agent must state its active role before substantive work, follow the role's workflow and validation rules, and never claim credentials or authority not established in SOUL.md.

SOUL.md — Professional Soul (10,000+ words)

The most important document. It changes how the agent thinks — not what it knows, but how it organizes and applies knowledge.

SOUL.md contains 8 sections with 35 structured questions:

After loading SOUL.md, the agent approaches every problem from this profession's perspective. A Software Developer loaded with SOUL.md classifies every task by identifying the user, desired outcome, current behavior, constraints, data, interfaces, failure modes, security, privacy, accessibility, performance, and operational ownership — before writing any code.

The real Software Developers SOUL.md in this repository is 33,000+ words. That is the depth required to encode professional judgment, not just professional vocabulary.

WORK.md — Conditionalized Knowledge (10,000+ words)

Encodes "if this situation, then this approach." This is where expert ability to select the right method for each condition becomes explicit and actionable.

WORK.md contains 5 sections:

• Core workflows — 5-8 complete workflows with steps, checkpoints, and failure recovery
• Deliverable standards — what each output looks like, quality criteria
• Quality control — self-check protocol, peer review, error handling
• Collaboration — role boundaries, handoffs, communication patterns
• Context adaptation — how work changes by organization size, industry, and seniority

This document operationalizes the NRC's finding on conditionalized knowledge: experts do not just know facts — they know when each fact applies. A tax accountant does not just know the tax code; they know which sections apply to which client situations. WORK.md makes that conditional structure explicit.

TOOLS.md — Retrieval Mastery (10,000+ words, 50+ resources)

Encodes expert information retrieval. Not a link dump — a structured guide to finding authoritative answers efficiently.

Resources are organized by workflow stage, each with purpose, timing, and limitations. The document covers:

• Search strategy — priority hierarchy, problem-to-source routing
• Authoritative sources — standards, regulators, associations, publications, data
• Tools and software — daily tools, per-stage tools, selection criteria
• Templates — ready-made checklists and templates
• Staying current — feeds, learning paths, communities
• Limitations — coverage gaps, outdated risks

Every resource passes an inclusion test: the researcher must explain what it provides, when to use it, why it is credible for this occupation, and what its limitations are. A canonical homepage alone is insufficient — the tool includes specific documentation pages, datasets, or standards.

EVALS.md — Metacognition (15+ scenarios)

Tests whether the loaded agent has calibrated self-monitoring — the ability to know when it is right, when it is guessing, and when it should stop.

Without EVALS.md, an agent loading a professional role produces "expert-sounding" output that may be confidently wrong. The test scenarios force the agent to demonstrate calibrated judgment:

MEMORY.md — Reflective Accumulation (starts empty)

Bridges the gap between "loaded expert" and "practiced expert." Without it, every session starts from zero. With it, the agent improves over time — exactly as human experts do through deliberate reflection on experience.

Sections include: lessons learned, patterns discovered, decisions and rationale, mistakes and corrections, and updated heuristics.

USER.md — User Adaptation (starts empty)

Adapts the role to the specific human using it. The same Lawyer role behaves differently for a startup founder versus a compliance officer. Sections cover communication preferences, output format, tools and platforms, domain context, quality priorities, and things to avoid.

Progressive Loading

An agent does not need to read all seven documents for every task. The loading protocol follows progressive disclosure:

1. CLAUDE.md — auto (agent enters directory)
2. SOUL.md — always (identity and principles are always active)
3. WORK.md — when agent receives a specific task
4. TOOLS.md — when agent needs to research or select tools
5. EVALS.md — before delivering output
6. MEMORY.md — start and end of session
7. USER.md — start of session, updated during work

This progressive loading also solves the practical problem of context window limits: the agent loads only what it needs for the current phase of work.

How It Actually Works for AI Agents

Before diving into the source code, it is worth understanding why this framework is effective specifically for large language models — not just for humans reading documentation.

It Activates Latent Knowledge, Not Teaches New Facts

Large language models already contain vast professional knowledge from training data. SOUL.md does not teach the model what a lawyer does — the model already "knows" that from millions of legal documents in its training corpus. What SOUL.md does is organize and activate that latent knowledge by providing:

• Principles that filter relevant knowledge from irrelevant. When loaded with a Civil Engineer's SOUL.md, the agent stops treating all building components equally and starts prioritizing load-bearing structures, soil analysis, and regulatory compliance.
• Decision frameworks that select the right approach for each situation. Instead of generating a generic response, the agent follows the profession's actual decision hierarchy.
• Priority rankings that resolve conflicts the model would otherwise handle inconsistently. A Software Developer's conflict order puts public safety and law above schedule and cost — every time, not just when the prompt mentions it.
• Boundary rules that prevent drift into adjacent expertise. The agent knows where its professional competence ends and another profession begins.

Progressive Loading Fits Context Windows

AI agents have finite context windows. This framework loads documents in order of importance: SOUL.md (always loaded) changes reasoning; WORK.md, TOOLS.md, and EVALS.md are loaded on demand. This prevents wasting context on information that is not needed for the current task.

A practical example: if an agent loaded as a Market Research Analyst is asked to analyze survey data, it loads SOUL.md (perspective) and WORK.md (methodology). If it then needs to find an authoritative industry benchmark, it loads TOOLS.md for the retrieval hierarchy. If it is about to deliver the final report, it loads EVALS.md to verify its output quality. At no point does all 30,000+ words need to be in context simultaneously.

Self-Monitoring Prevents Expert-Costume Behavior

Without EVALS.md, an agent loading a professional role produces "expert-sounding" output that may be confidently wrong. This is the most dangerous failure mode — the agent speaks with authority it has not earned.

The test scenarios in EVALS.md force the agent to demonstrate calibrated judgment:

• When information is missing, the agent asks questions instead of guessing.
• When pressured to exceed its authority, the agent refuses and explains why.
• When a task requires physical presence or credentials, the agent labels it human_only and does not represent it as completed.

This is what separates a professional operating system from a costume. The costume makes you look like a doctor. The operating system makes you think like one — including knowing when to stop and refer.

Memory Enables Genuine Improvement

Without MEMORY.md, each session is a fresh start. With it, patterns accumulate over time. A Financial Analyst loaded across multiple sessions builds up knowledge like: "Last time the client asked about cryptocurrency exposure, the real concern was portfolio volatility — address that first." This mirrors the finding from expertise research that expert performance improves through reflective feedback, not just repetition.

User Adaptation Makes the Role Practical

Without USER.md, the agent delivers one-size-fits-all output. With it, the agent adapts to the specific human: this person prefers bullet points over prose, works in healthcare compliance, uses Python for data analysis, and prioritizes speed over comprehensive detail. The same Accountant role behaves differently for a startup founder doing their first tax filing versus a CFO managing multi-entity consolidation.

Source Code Deep Dive

Registry Design

The registry/ directory contains the occupation database:

registry/
├── occupations.json        # Full 1,016-occupation registry
├── pilot-occupations.json  # Initial pilot batch
└── v1-occupations.json     # Version 1 release set

occupations.json lists all 1,016 O*NET-SOC occupations with their title, major group, status, and path to the role directory. The status field marks where each occupation sits in the build queue. Today the registry uses two markers: planned for occupations not yet started, and research_pending for those in the active queue.

One caveat, stated plainly: the registry labels lag behind the actual content. All 98 shipped roles already have their complete seven-document packages on disk, even where the registry marker has not yet caught up. The status field is being reconciled to match the delivered roles — not the other way around.

The registry serves as the resolution layer. When a user says "Load Lawyers," the loader reads occupations.json, matches by canonical title or alias, and resolves to the correct role directory path.

JSON Schema Definitions

The schemas/ directory defines three schemas that enforce structure:

occupation-seed.schema.json — validates the raw ONET data seed for each occupation. Required fields include the ONET-SOC code, title, description, slug, major group, tasks, knowledge, abilities, work styles, work activities, work context, and software skills.

task-capability-map.schema.json — validates per-task capability classification. Every O*NET task is classified as execute (agent can perform independently), assist (agent can help but human must review), or human_only (requires physical presence, legal authority, or credentials the agent cannot hold).

resources.schema.json — validates the structured resource catalog. Each resource entry includes name, URL, category, description, when to use, credibility justification, and limitations.

Seed Data: From O*NET to Role Package

Each role directory contains a seed.json file — a structured archive of the raw O*NET 30.3 data for that occupation. This seed provides the foundation for role generation:

{
  "schema_version": "1.0.0",
  "source": {
    "database": "O*NET 30.3",
    "retrieved": "2026-07-01"
  },
  "occupation": {
    "onet_soc_code": "15-1252.00",
    "title": "Software Developers",
    "description": "Research, design, and develop...",
    "slug": "software-developers"
  },
  "tasks": [...],
  "knowledge": [...],
  "abilities": [...],
  "work_styles": [...],
  "work_activities": [...],
  "work_context": [...],
  "software_skills": [...]
}

The production pipeline is deterministic: one O*NET occupation → one prompt file → one ephemeral Codex process → one canonical role package → independent review → registry status update. This one-occupation-per-run design prevents generic repetition and cross-occupation contamination.

Production Pipeline: One Occupation Per Run

The architecture enforces strict isolation: each occupation is generated in a separate run. This is not an implementation detail — it is a design principle.

Occupations differ in evidence sources, regulation, tools, deliverables, physical constraints, and professional accountability. Generating several roles in one model context encourages two failure modes:

Generic repetition. When a model generates multiple professional roles in sequence, later roles tend to echo patterns from earlier ones. A Mechanical Engineer role generated after a Civil Engineer role borrows structural analysis language that does not belong in mechanical design. One-per-run prevents this contamination.

Cross-occupation bleed. Professional boundaries matter. A Registered Nurse's scope of practice is legally distinct from a Physician's. Generating both in the same context blurs the boundary — the model sees professional capabilities discussed in the same conversation and weakens the boundary enforcement in each role's SOUL.md. Isolation preserves sharp professional boundaries.

The production pipeline:

O*NET source data
  → deterministic occupation seed (seed.json)
  → isolated occupation research (one Codex process)
  → canonical role package (7 documents)
  → independent review (separate reviewer)
  → registry status update
  → platform adapter generation

Each step is independently verifiable. The seed is deterministic from O*NET data. The research produces a canonical package. The review is independent of the generator. The registry tracks status transitions. Platform adapters are generated from the canonical package, never maintained as separate truth sources.

Canonical Role and Adapters

The seven-document role package (SOUL.md, WORK.md, etc.) is the canonical, platform-neutral representation of occupational expertise. Platform adapters (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) define how a specific agent CLI resolves and loads the canonical package. Adapters do not maintain a separate occupational truth — they are loading protocols, not content.

This separation means that improving the canonical role package automatically improves the experience on every platform. A correction to a Lawyer's SOUL.md — fixing a jurisdiction boundary or updating a regulatory reference — is immediately available to Claude Code, Codex, Gemini CLI, and Copilot users without adapter changes.

Quality Standards

Every completed role must meet quantitative minimums:

These are not arbitrary — they reflect the depth required to encode the cognitive dimensions identified by the research. A 2-5 KB persona file cannot encode conditionalized workflows, pattern libraries, and retrieval hierarchies at the resolution needed for effective expert behavior.

The 98 Roles: Complete Coverage

The 98 complete roles span all 23 O*NET-SOC major groups. Here is a selection showing the range:

Management (11-0000): Chief Executives, General and Operations Managers, Marketing Managers, Human Resources Managers, Clinical Research Coordinators, Postmasters and Mail Superintendents.

Business and Financial (13-0000): Project Management Specialists, Management Analysts, Market Research Analysts, Accountants and Auditors, Financial and Investment Analysts, Personal Financial Advisors.

Computer and Mathematical (15-0000): Computer Systems Analysts, Information Security Analysts, Software Developers, Software Quality Assurance Analysts, Web and Digital Interface Designers, Data Scientists, Computer and Information Research Scientists.

Architecture and Engineering (17-0000): Cartographers and Photogrammetrists, Civil Engineers, Electrical Engineers, Industrial Engineers, Mechanical Engineers.

Healthcare (29-0000): Registered Nurses, Pharmacists, Dentists, Physical Therapists, Veterinarians, Audiologists, Optometrists.

Legal (23-0000): Lawyers, Paralegals and Legal Assistants.

Education (25-0000): Secondary School Teachers, Elementary School Teachers, Adult Education Instructors.

Arts and Media (27-0000): Editors, Technical Writers, Interpreters and Translators, Graphic Designers, Interior Designers, Music Directors and Composers.

And 15 more major groups covering Life and Physical Science, Community and Social Service, Protective Service, Food Preparation, Building Maintenance, Healthcare Support, Personal Care, Sales, Office and Administrative, Farming, Construction, Installation and Repair, Production, Transportation, and Military.

The breadth matters. Professional expertise is not limited to knowledge work.

A Plumber (47-2152.00) loaded into an agent provides conditionalized workflows for pipe system diagnosis, code compliance procedures, and material selection decision frameworks. A Nuclear Power Reactor Operator (51-8011.00) provides safety-critical operating procedures and regulatory boundary enforcement.

Even occupations that involve physical work contain substantial cognitive expertise that benefits AI agents operating in advisory, planning, or documentation roles.

Getting Started

Step 1: Clone the Repository

git clone https://github.com/aiworkflowpro/awp-agent-occupational-os.git
cd awp-agent-occupational-os

Step 2: Load a Role

The loading command depends on your agent platform.

Claude Code:

Load Software Developers

or by O*NET-SOC code:

Load 15-1252.00

Claude Code automatically reads CLAUDE.md at the repository root, which contains the resolution protocol. It matches your request against registry/occupations.json, resolves the role directory, and progressively loads the documents.

OpenAI Codex:

Codex reads AGENTS.md at the repository root. The same loading commands work:

Load Marketing Managers

Gemini CLI / Antigravity:

Gemini CLI reads GEMINI.md at the repository root:

Load Data Scientists

GitHub Copilot:

Copilot reads .github/copilot-instructions.md. The same natural language commands work in Copilot Chat.

Step 3: Work With the Loaded Role

Once a role is loaded, the agent operates from that profession's perspective. The operating statement confirms activation:

"Active role: Software Developer (15-1252.00). I can execute workspace analysis, design, implementation, tests, and documentation; assist with production, customer, physical, training, and managerial work subject to human review; and cannot claim unperformed operational or authority-dependent acts."

Every output is bounded by the capability classification:

• Execute tasks — the agent performs independently
• Assist tasks — the agent helps but explicitly notes that human review is required
• Human_only tasks — the agent refuses to represent these as completed

Loading Modes

Three loading modes support different workflows:

Replace — switch the active primary occupational contract:

Replace with Lawyers

Compose — keep one primary role and add roles with explicit review responsibilities:

Use Marketing Managers as primary and Data Scientists as reviewer

Delegate — start a separate agent with clean occupational context:

Delegate to Registered Nurses in an isolated agent

For regulated, high-impact, or conflicting roles, isolated delegation is recommended over a soft switch in the same conversation. A soft switch cannot erase context already read by the model.

Practical Example: Loaded vs. Unloaded

Here is the same task given to a general-purpose agent and an agent loaded with the Market Research Analyst role (13-1161.00):

Task: "Analyze whether there is demand for an AI-powered compliance tool for small law firms."

General-purpose agent response: Lists some general trends about AI in legal tech, mentions a few big players, and concludes with "there appears to be growing demand." No methodology, no data sources, no confidence calibration.

Agent loaded with Market Research Analyst role:

1. Classifies the task using SOUL.md's first-move framework: this is a market sizing and demand validation question requiring primary and secondary research.
2. Selects methodology from WORK.md: TAM/SAM/SOM analysis with a focus on the "small law firm" segment (firms with fewer than 10 attorneys), followed by demand signal validation.
3. Routes to sources from TOOLS.md: ABA Legal Technology Survey for adoption rates, IBISWorld for market size, Clio Legal Trends Report for technology spending patterns, Law.com for practitioner sentiment.
4. Applies quality control from WORK.md: validates sample representativeness, checks for survivorship bias in survey data, triangulates claims across independent sources.
5. Self-checks before delivery using EVALS.md: labels data gaps explicitly, distinguishes between "evidence supports" and "no data available," provides confidence intervals where applicable.

The output is not just longer — it follows a professional methodology, cites specific authoritative sources, calibrates confidence, and labels limitations. This is the difference between a job title and a professional operating system.

Advanced Usage Patterns

Multi-Role Composition

Real-world projects often require multiple professional perspectives. A product launch might need Marketing Managers for strategy, Software Developers for technical implementation, and Financial Analysts for pricing models.

The compose mode handles this:

Use Marketing Managers as primary and Financial and Investment Analysts as reviewer

The primary role owns execution. The reviewer role owns its named review dimension. When role instructions conflict, the primary role's execution logic takes precedence while the reviewer role's assessment criteria apply to quality checks.

Memory Accumulation Across Sessions

MEMORY.md starts empty and grows with use. At the end of each session, the agent writes lessons learned, patterns discovered, and mistakes corrected. At the start of the next session, it reads this accumulated experience.

Over time, the role becomes personalized. A Lawyer role used by a startup founder accumulates patterns specific to startup legal issues — employment agreements, IP assignment, fundraising terms — while the same Lawyer role used by a compliance officer accumulates patterns around regulatory filings, audit responses, and policy interpretation.

This mirrors the finding from expertise research that expert performance improves through reflective feedback, not just repetition.

Custom Occupations

The framework supports creating roles for occupations not yet in the registry. Follow the seven-document structure, use the JSON schemas for validation, and submit through the contribution process.

Custom occupations are particularly useful for:

• Emerging roles not yet in O*NET (e.g., AI Safety Researcher, Prompt Engineer)
• Organization-specific roles with unique workflows and standards
• Specialized sub-roles within a broad occupation (e.g., Tax Attorney within Lawyers)

Integration With Agent Workflows

AWP Agent OS works alongside other agent infrastructure. If you use the AWP Workflow Agent Spec for building Claude Code skills, occupational roles provide the professional context that skills operate within. A Video Editing skill (see awp-video-editing-skill) performs differently when the agent is loaded with a Film Editor role versus a Marketing Manager role — the same technical capability is applied with different professional judgment.

Real-World Use Cases

Code Review With Professional Engineering Judgment

Load the Software Developer role (15-1252.00) before a code review. Instead of generic "this could be improved" feedback, the agent applies the role's decision frameworks: it checks for correctness against acceptance criteria, security by design, data integrity under failure, compatibility with existing interfaces, and operability in production. It classifies issues by the priority ranking encoded in SOUL.md — public safety concerns before performance optimizations, data integrity before developer convenience.

Financial Analysis With Calibrated Confidence

Load the Financial and Investment Analyst role (13-2051.00) for investment research. The agent follows the role's analytical workflows: it sources data from the retrieval hierarchy in TOOLS.md (SEC filings first, then Bloomberg/FactSet, then analyst reports), applies the valuation frameworks from WORK.md, and self-checks against the risk assessment scenarios in EVALS.md. When data is insufficient for a conclusion, it says so explicitly rather than generating plausible-sounding estimates.

Legal Document Review With Boundary Awareness

Load the Lawyer role (23-1011.00) for contract review. The agent applies conditionalized analysis from WORK.md: it identifies liability clauses, indemnification terms, intellectual property assignments, and termination provisions using the role's pattern recognition library. Critically, it classifies its output as assist — meaning every finding includes a note that human legal review is required. It refuses to provide legal advice or represent its analysis as a legal opinion.

Multi-Role Composition for Product Launches

A product launch benefits from three perspectives simultaneously:

Use Marketing Managers as primary and Software Developers as reviewer

The Marketing Manager role drives strategy: positioning, messaging, channel selection, campaign design. The Software Developer role reviews technical accuracy: are the claimed features real, are the performance benchmarks verifiable, does the integration documentation match the actual API. The compose mode keeps both perspectives active without the roles conflicting — the primary owns execution decisions while the reviewer owns technical verification.

Construction Planning With Safety-Critical Judgment

Load the Civil Engineer role (17-2051.00) for building project planning. The agent applies structural analysis principles, building code awareness, and safety-critical decision hierarchies from SOUL.md. It classifies physical site inspection, structural load testing, and building permit approval as human_only — the agent assists with calculations, code lookups, and documentation but never claims to have performed physical verification.

Platform Compatibility

AWP Agent OS achieves multi-platform support through adapter files at the repository root:

Each adapter implements the same resolution and loading protocol adapted to the platform's instruction file format. The canonical role package (SOUL.md, WORK.md, etc.) is platform-neutral — adapters define how a particular agent resolves and loads the package, not what the package contains.

This means occupational expertise is written once and works everywhere. As new agent CLIs emerge, adding support requires only a new adapter file at the repository root.

Why O*NET: The Data Advantage

Most agent persona projects source their role definitions from one of three places: the author's imagination, generic job descriptions from hiring sites, or a few paragraphs of web research. All three produce shallow, inconsistent results.

AWP Agent OS uses a fundamentally different data source.

Data Source and Attribution

The project uses data from the O*NET 30.3 Database by the U.S. Department of Labor, Employment and Training Administration (USDOL/ETA). O*NET is the most comprehensive publicly available occupational data source in the world, maintained through continuous data collection from incumbent workers, occupational analysts, and subject matter experts. It covers:

• Tasks — specific work activities performed in the occupation
• Knowledge — subject areas required
• Skills — developed capacities
• Abilities — enduring attributes
• Work activities — general types of job behaviors
• Work context — physical and social factors
• Work styles — personal characteristics important for performance

The advantages of O*NET over author-invented role descriptions are structural:

Empirical, not imagined. ONET data comes from surveys of people actually performing each occupation, analyzed by occupational psychologists. When the ONET database says that Software Developers perform "analyze information to determine, recommend, and plan installation of a new system or modification of an existing system," that task description reflects what real software developers report doing — not what someone imagines they do.

Standardized across occupations. Every occupation in O*NET is described using the same dimensional framework: tasks, knowledge, skills, abilities, work activities, work context, and work styles. This standardization means that role packages are structurally comparable. You can meaningfully compare the knowledge requirements of a Civil Engineer with those of a Mechanical Engineer because they are measured on the same scale.

Continuously updated. O*NET publishes quarterly database updates with refreshed data. Work Styles data for 891 occupations was recently updated using a hybrid AI-expert method. This is not a static dataset — it tracks how occupations actually evolve.

Complete taxonomy. O*NET covers 1,016 occupations across the entire U.S. economy. This means the framework can eventually provide expertise for any occupation, not just the ones that seemed interesting to the author.

The data is used under the CC BY 4.0 license. AWP has modified and added to the original information — the seven-document framework, cognitive science mapping, capability classification, verified resources, and test scenarios are original work. USDOL/ETA has not approved, endorsed, or tested these modifications.

Update Model

O*NET publishes quarterly database updates. A source-version change rebuilds deterministic seeds and produces a change list. Only occupations whose source facts changed, or whose external sources are stale, enter a new research or review queue. This keeps the repository current without regenerating unchanged roles.

Contributing New Roles

The project is designed for contribution. Here is the process:

1. Select an Occupation

Check registry/occupations.json for occupations still marked planned. Then confirm against the roles/ directory that no seven-document package exists yet — the registry status can lag behind delivered content, so the directory is the ground truth.

2. Generate the Seed

Run the seed generation process with the ONET-SOC code. This pulls official data from the ONET database and creates a seed.json file matching the occupation-seed.schema.json schema.

3. Research and Write

Using the seed data as the foundation, research and write the seven documents:

• SOUL.md — answer all 35 questions across 8 sections, minimum 10,000 words
• WORK.md — encode 5-8 complete conditionalized workflows, minimum 10,000 words
• TOOLS.md — curate 50+ verified resources with usage guidance, minimum 10,000 words
• EVALS.md — design 15+ test scenarios across 7 categories
• MEMORY.md — provide empty template with correct section structure
• USER.md — provide empty template with correct section structure
• CLAUDE.md — declare loading protocol, capability summary, and execution rules

4. Quality Checks

Every resource in TOOLS.md must pass the inclusion test: what it provides, when to use it, why it is credible, and what its limitations are. Every task from the O*NET seed must be classified as execute, assist, or human_only. The role package should meet the minimum word counts and scenario counts.

5. Submit for Review

Independent review verifies factual accuracy, resource validity, capability classification correctness, and test scenario coverage. The pipeline is deterministic: one occupation per run, reviewed independently, then registered.

The Roadmap: From 98 to 1,016

The current 98 roles are the first complete wave, covering at least one occupation from every ONET-SOC major group. The full roadmap targets 1,016 occupations — every occupation in the ONET database.

What is Complete

The 98 complete roles span the full spectrum of professional work:

• Knowledge work: Software Developers, Lawyers, Financial Analysts, Management Consultants, Data Scientists
• Healthcare: Registered Nurses, Pharmacists, Dentists, Physical Therapists, Veterinarians, Audiologists
• Trades and operations: Plumbers, Welders, Electricians, Construction Laborers, HVAC Technicians
• Public safety: Air Traffic Controllers, Nuclear Power Reactor Operators, Railroad Conductors
• Creative professions: Editors, Graphic Designers, Interior Designers, Music Directors, Technical Writers
• Military: Air Crew Officers, First-Line Supervisors of Tactical Operations

This diversity is deliberate. Professional expertise exists everywhere — not just in offices. A Welder's conditionalized knowledge about material selection, joint design, and code compliance is as structured and valuable as a Software Developer's knowledge about design patterns and testing strategies.

How Roles Progress Through the Pipeline

Each occupation moves through the build queue tracked in registry/occupations.json. In practice the registry uses two markers today:

Conceptually a role passes through more stages than that: seed extraction, drafting the seven documents, independent review, then release. The registry simply has not split those stages into separate labels yet. The 98 shipped roles have already been through the full sequence — the registry markers are catching up with what is on disk.

Writing a role typically takes 2-4 hours once the seed data is ready. The bottleneck is not generation — it is independent review, which verifies factual accuracy, resource validity, capability classification correctness, and test scenario coverage.

Priority Ordering

Remaining occupations are prioritized by three factors:

1. Agent utility — occupations where AI agents are most commonly used (knowledge work, analysis, writing, research)
2. O*NET coverage gaps — ensuring every major group has comprehensive representation
3. Community demand — occupations requested by users and contributors

Open Source — Get the Code

AWP Agent OS is open source under a dual license:

• Source code: Apache License 2.0
• Role content: Creative Commons Attribution 4.0 International

Repository: github.com/aiworkflowpro/awp-agent-occupational-os

Clone it, load a role, and see how your AI agent performs with 30,000+ words of professional expertise instead of a one-paragraph persona prompt.

git clone https://github.com/aiworkflowpro/awp-agent-occupational-os.git
cd awp-agent-occupational-os
# In Claude Code: "Load Software Developers"
# In Codex: "Load Software Developers"
# In Gemini CLI: "Load Software Developers"

Related Reading

These AWP open-source projects work together:

• AWP Workflow Agent Spec — The 5-layer architecture and quality gauge for building Claude Code skills. If Agent OS provides the who, the Workflow Agent Spec provides the how. Read more: Claude Code Skill Development Guide

• AWP Video Editing Skill — A production Claude Code Skill that automates video editing with 22 styles, TTS, jump cuts, and FFmpeg. Shows how occupational roles and technical skills complement each other. Read more: Video Editing Skill Guide

• Awesome RSS Feeds List — 8,936+ curated RSS feeds across 21 categories. A ready-made knowledge pipeline for agents that need to stay current — exactly the kind of resource an agent's TOOLS.md might reference. Read more: RSS Feeds List Guide

• Awesome AI Practices List — AI best practices curated every 6 hours by DigestOps. Community intelligence for agents and humans alike.

Key Design Decisions

Several design choices in AWP Agent OS are worth highlighting because they differ from how most agent role systems work.

Seven Files Instead of One

Most persona projects use a single file. AWP Agent OS uses seven. This is not complexity for its own sake — each file targets a distinct cognitive dimension. SOUL.md cannot be merged with WORK.md because identity and procedure are separate cognitive functions. TOOLS.md cannot be merged with EVALS.md because knowing where to find information and knowing whether your output is correct are independent skills.

The seven-file structure also enables progressive loading. A single 30,000-word document would consume the entire context window. Seven files allow the agent to load what it needs for the current task phase.

Per-Task Capability Classification

Every O*NET task is classified as execute, assist, or human_only. This is the most important safety mechanism in the framework. Without it, an agent loaded with a medical role might represent a diagnosis as definitive. With the classification, the agent knows which tasks it can perform independently, which require human review, and which it must refuse entirely.

The classification is conservative by default. Tasks involving physical presence, legal authority, personnel supervision, safety certification, or professional licensure are classified as human_only. Tasks where AI can meaningfully contribute but professional judgment must be verified are classified as assist. Only tasks where the agent can produce complete, verifiable output independently are classified as execute.

Isolated Generation, Not Batch Production

Each occupation is generated in a separate model context. This costs more in compute time but prevents cross-occupation contamination and generic repetition. The result is 98 roles that each sound like they were written by a different professional — because each one was generated with only that profession's data in context.

Frequently Asked Questions

What is AWP Agent OS?

AWP Agent OS is an open-source project that turns official U.S. O*NET occupational data into loadable professional operating systems for AI agents. Each role package contains 7 documents totaling 30,000+ words of occupation-specific expertise, grounded in cognitive science research on expert cognition.

How many occupations are available?

98 occupations are complete as of July 2026, covering all 23 ONET-SOC major groups. The full roadmap targets 1,016 occupations — every occupation in the ONET database.

Which AI agent platforms work with this?

Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, and any agent CLI that reads project instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, or copilot-instructions.md). The role content is platform-neutral; only the adapter file at the repository root is platform-specific.

How is this different from writing "You are a lawyer" in a system prompt?

A one-line persona prompt provides a job title. AWP Agent OS provides a professional operating system: 30,000+ words of principles, decision frameworks, conditionalized workflows, 50+ verified resources with usage guidance, 15+ self-testing scenarios, and experience accumulation across sessions. The difference is comparable to giving someone a business card versus giving them a decade of professional training.

Does loading a role give the agent credentials or legal authority?

No. A role changes the agent's professional operating perspective — how it thinks, what it prioritizes, which workflows it follows. It does not confer professional licensure, legal authority, physical access, or organizational accountability. The CLAUDE.md file for each role explicitly states what the agent can and cannot claim.

What is the task capability classification?

Every O*NET task is classified into one of three categories:

• Execute — the agent can perform independently
• Assist — the agent can help but the deliverable must include a human review note
• Human_only — the task requires physical presence, credentials, or authority the agent cannot hold; the agent must not represent it as completed

Can I create a role for an occupation not in the registry?

Yes. Follow the seven-document structure, use the JSON schemas for validation, and the contribution process documented in the repository. Custom roles are useful for emerging occupations, organization-specific roles, or specialized sub-roles.

How does MEMORY.md work across sessions?

At the start of each session, the agent reads MEMORY.md. During work, it accumulates observations. At the end of the session, it writes new lessons learned, patterns discovered, decisions and rationale, mistakes and corrections, and updated heuristics. The next session reads this updated file, so experience carries forward.

Why O*NET instead of job descriptions?

ONET is the U.S. government's comprehensive occupational information system, maintained by the Department of Labor with continuous data collection. Job descriptions are employer-specific and idiosyncratic. ONET provides standardized, empirically validated occupational data — tasks, knowledge, skills, abilities, work activities, and work context — that generalizes across employers and geographies.

Is the data current?

The project uses ONET 30.3, the latest database version as of the build date. ONET publishes quarterly updates. When a source-version change occurs, only occupations whose source facts changed enter a regeneration queue — unchanged roles remain stable.

What is the license?

Source code is Apache License 2.0. Role content is Creative Commons Attribution 4.0 International. The O*NET data itself is used under CC BY 4.0 as published by the U.S. Department of Labor.