Agentic Workforce Framework

A reference architecture for operating autonomous AI agents as
accountable digital workers inside enterprise environments.

This framework defines how agents are assigned work, bounded by role,
governed by approval chains, evaluated over time and integrated into
enterprise structures such as divisions, workspaces, audit logs and
control planes.

Status: Production-informed reference architecture.
Current implementation: Single-workspace operating model with a five-agent reference team.
Evidence base: 50+ scored sessions in the reference implementation reporting period. Metrics are self-reported and have not been independently audited.
Enterprise scaling model: Designed extension, not yet field-proven at multi-team scale.

Where this fits

This repository is designed to be adapted, not installed.

It is not an agent runtime, SDK, hosted product, or drop-in replacement for
LangGraph, CrewAI, Claude Code, Microsoft Agent Governance Toolkit, or any
other execution framework.

Those tools help agents run.

This framework defines the operating discipline around agent work: identity,
task contracts, failure memory, behavioral trust scoring, escalation, approval
gates and auditability.

Most teams should adapt the concepts, schemas, controls and reference patterns
to their own runtime, risk model and enterprise environment.

Why this exists

Most agent frameworks focus on task execution.

Enterprises need more than execution. They need workforce controls:

• Who is the agent?
• What work is it allowed to perform?
• Who approved the work?
• What evidence exists?
• How does trust change over time?
• When does autonomy expand or contract?
• How do agent teams operate across departments?

This framework addresses that gap by defining a complete operating
model for agent identity, task assignment, behavioral trust, failure
memory, approval gates and enterprise scaling.

What this repo includes

• Four-plane enterprise architecture
• Agentic workforce operating model
• Work queues and delegation rules
• Approval gate chains
• Trust and autonomy model (D1-D4)
• Manifest-based task assignment
• OS-level hook interception examples
• Reference Postgres governance schema
• Enterprise extension schema (divisions, workspaces, agent instances)
• Reference agent instruction files (five-agent team)
• Failure memory taxonomy (17 classes)
• Calibration anchors and scoring rubric
• Installable CLI for scaffolding framework artifacts into a repo
• Modular install support for agents, trust scoring, failure memory,
  task manifests and Claude Code hooks
• Runtime-aware scaffold support for Claude Code and runtime-agnostic
  scaffold support for Cursor, Windsurf and other environments

Maturity legend

This repo uses four status labels throughout. Every major artifact
and capability is labeled.

The Implementation Status table below applies these labels to every
capability claim. The labels are deliberately conservative: a capability
moves to "Implemented" only after sustained use in the reference
implementation, not on the day it is first written.

What this framework is not

This framework is not:

• a model safety system
• a replacement for identity and access management
• a replacement for enterprise GRC tooling
• a guarantee that agent outputs are correct
• a hosted product
• a full agent runtime
• a substitute for legal, compliance or security review

What this framework is:

An operating architecture for accountable agentic work. It governs
the operational reliability of agents — not the safety of their
outputs. It tracks whether agents are becoming more or less
trustworthy over time, gates autonomy on demonstrated behavior and
maintains institutional failure memory.

How this relates to other layers:

These three layers are complementary. None replaces the other.

Install the CLI

Scaffold the Agentic Workforce Framework into any repo:

npx agentic-workforce-framework@latest init

Or install globally:

npm install -g agentic-workforce-framework
awf init
awf check

The CLI can install a five-agent reference team, trust scoring files,
failure memory templates, task manifest schemas and Claude Code hook
examples.

For Claude Code, the CLI scaffolds agent templates, hook templates and
a settings example file. For Cursor, Windsurf and other runtimes, it
installs runtime-agnostic framework artifacts only.

The CLI does not run agents directly. It scaffolds the operating model
around your chosen runtime.

Current Limitations

• Single-workspace reference implementation only. Multi-workspace
  enterprise scaling is Reference Pattern, not field-proven.
• Manual D1-D4 scoring is the current implementation. Automated
  trust scoring is Planned. At enterprise scale, D1-D4 should be computed from structured QA verdicts, policy violations, audit events and failure recurrence data.
• Hook examples require environment-specific adaptation.
  Claude Code native hooks work out of the box. Framework-enriched
  hooks require payload enrichment before use in Claude Code.
• Runtime policy layer (AGT integration) is Experimental —
  shadow mode in the reference implementation.
• Claude Code does not provide framework-enriched context fields
  (agent_id, agent_depth, session_reads) by default. These must
  be derived from sidecar manifests or runtime state files.
• Postgres governance schema is live with schema and constraints
  in place. Data migration from file-based governance is in
  progress in the reference implementation.

The Problem

Enterprise AI agents are moving from isolated tools to autonomous digital workers.
They plan, execute, review, escalate and collaborate across increasingly complex workflows.
The question has shifted from:

"Can this model answer correctly?"

to:

"How do we operate autonomous agent teams like an accountable workforce?"

That requires persistent identity, role boundaries, task assignment, work logs, trust
history, failure memory, approval gates, policy enforcement and enterprise-scale team structures.
Most teams are still early here. Many have model APIs and prompt files, but not yet
a durable operating model for agent identity, trust, failure memory and autonomy.

The Four-Plane Architecture

╔════════════════════════════════════════════════════════════════╗
║  AGENTIC WORKFORCE PLANE  ✅                                    ║
║                                                                 ║
║  Orchestrator · Frontend Agent · Backend Agent                  ║
║  QA Agent · Fix Agent                                           ║
╠════════════════════════════════════════════════════════════════╣
║  AUTONOMY PLANE  ✅                                             ║
║                                                                 ║
║  D1-D4 Trust Scoring (manual) · Failure Memory (17 classes)     ║
║  Autonomy Gates · Promotion / Demotion                          ║
╠════════════════════════════════════════════════════════════════╣
║  CONTROL PLANE  ⚠️ partial                                      ║
║                                                                 ║
║  Pre-Spawn Protocol · HITL Gates · OS-Level Hook System         ║
║  AGT Adapter (shadow mode) · Audit Log (file-based)             ║
╠════════════════════════════════════════════════════════════════╣
║  AUTOMATION PLANE  next                                         ║
║                                                                 ║
║  PR Test Routine (R1) · Security Scan Routine (R4)              ║
╚════════════════════════════════════════════════════════════════╝

The status glyphs above mirror the four-label legend: ✅ corresponds
to Implemented, ⚠️ to Experimental, "next" to Planned. The full
breakdown is in the Implementation Status table further down.

Governance is the control plane. Not the architecture.
The workforce plane is the headline. Governance is what makes it safe to run autonomously.

The Agents-as-Employees Model

The framework maps every HR concept to an agent governance equivalent.

How the Governance Stack Fits Together

This framework sits in a three-layer stack. Each layer governs something distinct.
None replaces the other.

The reference implementation currently uses Microsoft AGT in shadow mode.
This framework is designed to sit above any runtime policy layer that provides
identity, policy enforcement and audit trail capabilities.

Start here

If you are reading this for the first time:

1. Read the four-plane model
2. Review the agentic workforce model
3. Review task manifests
4. Review approval gate chains
5. Review hook examples
6. Review the database schema
7. Read the reference implementation

For a hands-on path: Getting Started
covers a 30-minute first session.

For minimum viable adoption: examples/minimum-viable-adoption/
covers what you can run today without Postgres or hooks.

Core Concepts

Implementation Status

Honest accounting. No mixing of current state and target state. Every
row uses the four-label legend defined above.

What You Can Use Today

You can adopt the framework incrementally:

1. Scaffold the starter framework into a repo:

   npx agentic-workforce-framework@latest init
   npx agentic-workforce-framework@latest check

2. Start with the D1-D4 trust scoring rubric and score your first agent session.

3. Add FailureRecord tracking for recurring agent mistakes.

4. Introduce AgentTaskManifest before spawning agents on high-risk tasks.

5. Add hook enforcement for high-risk file and commit actions.

6. Move to Postgres-backed governance when file-based tracking becomes limiting.

Repository Layout

Top-level folders in this repository:

• agents/ — Reference agent role definitions (orchestrator, frontend, backend, QA, fix).
• calibration/ — D1-D4 rubric anchors, confidence band guide, scoring ledger and anti-patterns.
• database/ — Postgres schemas: database/governance/ (core) and database/enterprise/ (multi-workspace extension).
• docs/ — Concepts, control plane, architecture, operating model and guides.
• examples/ — Case study templates and worked examples.
• governance/ — Runtime state templates. Copy these files into your own repo and populate them. These are operational files your orchestrator reads at startup — not framework documentation.
• hooks/ — Sanitized PreToolUse / SubagentStart / PostToolUse hook examples plus Claude Code settings template.
• routines/ — Scheduled automation routine specs.
• schemas/ — JSON Schema files for AgentTaskManifest, QAVerdict, FailureRecord and TrustScore.
• packages/awf-cli/ — npm CLI for scaffolding AWF artifacts into
  a target repo.

Schemas

Five JSON schemas ship with v1.0, all AJV Draft 2020-12 compatible.
Implementations are expected to extend agent rosters, failure classes and domain-specific validation rules through versioned schema extensions rather than modifying adopted schemas silently.
Schemas are versioned under schemas/v1/. Breaking changes require a new version path.

Database

Two SQL schemas ship with this framework, both Postgres-compatible.

/database/governance/ Core governance tables for any single-workspace deployment.
Includes audit log, agent events, trust scores, failure records and routine runs.
Run this first.

/database/enterprise/ Enterprise extension for multi-workspace deployments.
Includes divisions, workspaces, persistent agent instances, work queue items,
gate records and delegation rules.
Run this only when scaling to multi-team. Requires the governance schema first.

Hooks

The /hooks/ directory contains sanitized, commented example implementations
of OS-level enforcement hooks for Claude Code. All paths are template placeholders.
No private repository references exist in any example.

All hooks follow two rules:

• exit(2) = hard block, agent cannot proceed
• Fail closed: any error defaults to block, not allow

Calibration

Trust scoring without calibration produces drift. The /calibration/ directory
provides the D1-D4 rubric with anchored examples, a confidence band guide (n=sessions to band),
a scoring ledger template and an anti-patterns document covering the most common scoring mistakes.

Getting Started

See docs/guides/getting-started.md for a 30-minute path to:

1. Defining your agent roster with the agents-as-employees model
2. Running your first scored session (D1-D4, with evidence)
3. Writing your first FailureRecord
4. Setting a trust tier for each agent

IP and scope boundary

This repository contains a generalized agentic operating architecture
and governance framework. It excludes:

• Product-specific implementation logic
• Proprietary prompts or AI persona design
• Commercial workflows and pricing logic
• Customer or session data
• Supplier integration details
• Patent-sensitive product scoring logic
• Private repository paths or internal operational identifiers

The framework is extracted from a working reference implementation
and generalized for public use. The reference implementation itself
is private and not covered by this repository's license.

Contributing

Contributions welcome in three areas:

Concepts and documentation. Corrections, clarifications and additions to the framework docs.

Case studies. If you have adopted this framework or adapted it, submit a case study
using the template.
The most useful case studies show what you adapted, not just that it worked.

Schema extensions. Propose new schemas or schema versions via GitHub issue.
Schema changes require a documented rationale and a backward-compatibility statement.

See CONTRIBUTING.md for full guidelines.

Safety

This framework was built alongside production agent systems. It includes explicit coverage for:

• Prompt injection defense at the hook layer
• Subagent spawn governance (subagents cannot spawn subagents)
• Operator override with TTL (no permanent overrides)
• Audit log entry on every override use
• Hard-stop rules for D1-D4 scoring (falsified telemetry = automatic demotion)
• Fail-closed hook design: any hook error blocks the action

See SECURITY.md for vulnerability reporting.

License

MIT. See LICENSE.

The framework, schemas, hook patterns and database schemas are freely usable under MIT.
Any reference to the reference implementation indicates a private implementation not
covered by this license.

Agentic Workforce Framework — originated by Ramesh Ayyagari (https://github.com/rayyagari2-create), 2026
First public release: 2026