junaidahmed361 · junaidahmed361 · Jun 25, 2026 · Jun 25, 2026
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -82,3 +82,26 @@ The private `campaigns-app` repo should own hosted and commercial surfaces:
 - commercial integrations
 
 The OSS repo should remain the reusable primitive layer.
+
+## AgentOS revised platform philosophy
+
+Campaigns is the Campaign Kernel: the reusable control plane that AgentOS packages with dashboard, SDK, MCP, documentation, and provider drivers. The core abstraction is not an agent class; it is a capability contract that produces measurable artifacts and immutable receipts.
+
+```text
+Goal
+  -> Campaign Kernel
+  -> Capability
+  -> Implementation
+  -> Evaluation
+  -> Artifact
+```
+
+Three immutable laws:
+
+1. The user specifies outcomes, never implementations.
+2. Every decision made by AgentOS must be explainable and reproducible.
+3. Every artifact must be measurable before it is accepted.
+
+LangGraph owns execution/checkpointing/streaming only. Campaign Kernel owns campaign state, capability contracts, budget reservations, credentials, artifacts, evaluations, receipts, events, and routing rationale.
+
+See [`docs/agentos`](docs/agentos/README.md) and [`docs/adr`](docs/adr/README.md).
diff --git a/README.md b/README.md
@@ -6,7 +6,15 @@
 [![CI](https://github.com/junaidahmed361/campaigns/actions/workflows/ci.yml/badge.svg)](https://github.com/junaidahmed361/campaigns/actions/workflows/ci.yml)
 [![Package](https://github.com/junaidahmed361/campaigns/actions/workflows/package.yml/badge.svg)](https://github.com/junaidahmed361/campaigns/actions/workflows/package.yml)
 
-Campaigns is an open-source campaign operating-system layer above AgentRL.
+Campaigns is the open-source **Campaign Kernel** for AgentOS: a capability-driven control plane where a user expresses an outcome, execution policy, SLA, resource ceiling, and quality requirements, and the system plans, routes, executes, evaluates, repairs, and returns measurable artifacts without exposing provider complexity.
+
+The product philosophy is deliberately not `Goal -> Planner -> Agent -> Tool`. It is:
+
+```text
+Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact
+```
+
+Providers such as Claude Code, Codex, Ollama, OpenAI, or Anthropic are interchangeable driver details behind capability implementations. Hermes is the primary Phase 0 dogfooding interface, but it is only a thin client/tool consumer over the AgentOS MCP server or REST API. Campaign Kernel remains the system of record.
 
 The design is inspired by multi-agent economies such as Qi et al., "Economy of Minds: Emerging Multi-Agent Intelligence with Economic Interactions" (2026), https://arxiv.org/pdf/2606.02859, especially the idea that capable agent societies need explicit interaction protocols, resource constraints, specialization, and outcome-oriented coordination rather than a flat task list.
 
@@ -123,6 +131,19 @@ Campaign
   -> AgentRL Evolution / Promotion / Rollback
 ```
 
+
+## AgentOS architecture repository
+
+This repository is now treated as the **Campaign Kernel** seed for AgentOS, not as a monolithic `agentos` repo. The canonical architecture source lives in [`docs/agentos`](docs/agentos/README.md), with the user-amended v3 architecture package in [`docs/agentos/v3`](docs/agentos/v3/README.md) and ADRs in [`docs/adr`](docs/adr/README.md).
+
+The non-negotiable product philosophy is:
+
+```text
+Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact
+```
+
+Providers are interchangeable device drivers. LangGraph is only the execution runtime. Hermes, dashboards, SDKs, and MCP clients are clients/facades, never the system of record. Phase 0 dogfooding should happen primarily through Hermes consuming the AgentOS MCP server or REST API.
+
 ## Install
 
 From PyPI after release:
@@ -148,6 +169,61 @@ docker run --rm ghcr.io/junaidahmed361/campaigns:latest --version
 
 ## Quick start
 
+### 1. Express the outcome, not the provider
+
+```bash
+campaigns dogfood \
+  --goal "Ship an evaluated backend API for campaign receipts" \
+  --budget 25 \
+  --constraint "immutable receipts" \
+  --quality "tests pass" \
+  --quality "receipt provenance is replayable"
+```
+
+This accepts only user-facing intent — goal, budget, constraints, quality requirements, and optional SLA — then returns selected capability contracts, measurable artifacts, evaluation gates, an EUV/$ routing objective, and an immutable receipt. Provider complexity stays behind drivers.
+
+### 2. Dogfood execution with Resource Manager reservations and local CLI auth
+
+Phase 0 can dogfood without Stripe, Apple Pay, invoices, or payment-wallet plumbing. `dogfood-exec` uses the open-source Resource Manager to reserve dollars from an execution policy, then invokes a local CLI driver through existing Claude/Codex auth configuration. AgentOS does not read or modify auth files and does not receive API keys.
+
+```bash
+campaigns dogfood-exec \
+  --goal "Ship an evaluated backend API for immutable campaign receipts" \
+  --budget 25 \
+  --reserve 2.50 \
+  --constraint "no payment wallet in the open-source core" \
+  --constraint "provider choice stays hidden behind CLI drivers" \
+  --quality "provider response artifact is captured" \
+  --quality "immutable receipt is produced"
+```
+
+For developer diagnostics only, you may force a driver:
+
+```bash
+campaigns dogfood-exec --driver codex ...
+campaigns dogfood-exec --driver claude ...
+```
+
+Normal product use should omit `--driver`; routing should select a capability implementation without asking the user to think about providers.
+
+### 3. Expose AgentOS to Hermes through MCP
+
+Hermes is the primary Phase 0 dogfooding interface, but it remains a thin client. The package exposes a minimal MCP-style stdio server scaffold:
+
+```bash
+agentos-mcp
+```
+
+The server publishes the Phase 0 Hermes tools:
+
+```text
+create_campaign, list_campaigns, campaign_status, approve, reject,
+list_artifacts, open_artifact, receipt,
+execution_policy_get, execution_policy_update
+```
+
+Campaign Kernel owns the state and business logic behind those tools.
+
 Create a review dossier from an example campaign:
 
 ```bash
@@ -176,6 +252,8 @@ print(dossier.to_dict()["workflow"])
 
 ## Current primitives
 
+- `ResourceManager`, `ExecutionPolicy`, and `ResourceReservation`: open-source resource ceilings/reservations for BYOK, subscription, token API, and local providers without payment-wallet logic.
+- `HermesAdapter` and `AgentOSMCPServer`: thin Phase 0 Hermes dogfooding surface over Campaign Kernel state; Hermes remains a client, not the system of record.
 - `AgentHarnessDefinition`: campaign-side reference to a user-created targeted AgentRL harness.
 - `CampaignSpec`: user-defined goal, budget, timeline, success metrics, constraints, and employed harnesses.
 - `ArchitectureLayer`: explicit Runtime / Harness Lifecycle / Swarm Operating System boundary so Campaigns stays above AgentRL.

diff --git a/docs/adr/0001-use-campaign-kernel-name.md b/docs/adr/0001-use-campaign-kernel-name.md
@@ -0,0 +1,17 @@
+# ADR 0001: Use Campaign Kernel as the Core Repository Concept
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+The repo should not be named agentos. Campaign Kernel remains independently testable and AgentOS packages dashboard, SDK, MCP, docs, and drivers around it.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/0002-capability-routing-over-provider-routing.md b/docs/adr/0002-capability-routing-over-provider-routing.md
@@ -0,0 +1,17 @@
+# ADR 0002: Capability Routing over Provider Routing
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+Routing selects provider-independent capability implementations. Provider-specific branches must stay inside drivers.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/0003-langgraph-runtime-only.md b/docs/adr/0003-langgraph-runtime-only.md
@@ -0,0 +1,17 @@
+# ADR 0003: LangGraph as Runtime Only
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+LangGraph owns execution, checkpoints, and streaming. Campaign Kernel owns state, memory, budgets, receipts, artifacts, and decisions.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/0004-evaluator-before-execution.md b/docs/adr/0004-evaluator-before-execution.md
@@ -0,0 +1,17 @@
+# ADR 0004: Evaluator Before Execution
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+Evaluation specs are created before execution. Bounded repair loops depend on measurable artifact acceptance criteria.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/0005-immutable-receipts.md b/docs/adr/0005-immutable-receipts.md
@@ -0,0 +1,17 @@
+# ADR 0005: Immutable Receipts
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+Receipts are append-only. Repair creates a new receipt with parent/supersedes links.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/0006-byok-credential-plane.md b/docs/adr/0006-byok-credential-plane.md
@@ -0,0 +1,17 @@
+# ADR 0006: BYOK Credential Plane
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+Credentials resolve through scoped handles in the Credential Plane. Clients and chat never become secret stores.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/0007-resource-manager-not-wallet.md b/docs/adr/0007-resource-manager-not-wallet.md
@@ -0,0 +1,27 @@
+# ADR 0007: Resource Manager, not Wallet, in the Open-Source Core
+
+## Status
+Accepted
+
+## Context
+AgentOS needs hard limits before provider calls, but a payment wallet is a cloud/business concern. The open-source Campaign Kernel must support BYOK, subscription providers such as Claude Code and Codex, local providers such as Ollama/vLLM, and token API providers with monthly limits.
+
+## Decision
+Use **Resource Manager** as the open-source core primitive.
+
+The Resource Manager owns:
+
+- execution policy interpretation
+- resource reservations
+- quota/spend ceilings
+- subscription/local-provider preferences
+- repair-iteration limits
+- ledger entries
+- reconciliation
+
+Wallet, Apple Pay, Stripe, invoices, managed provider credits, and team billing are optional Cloud modules layered behind Resource Manager interfaces.
+
+## Consequences
+- No provider or coding-agent driver call can happen without a Resource Manager reservation.
+- The kernel can dogfood through existing Claude/Codex subscription CLI auth without implementing billing.
+- Hermes and dashboards display resource state returned by Campaign Kernel; they do not own budget logic.
diff --git a/docs/adr/0008-defer-world-state-simulation-rl.md b/docs/adr/0008-defer-world-state-simulation-rl.md
@@ -0,0 +1,17 @@
+# ADR 0008: Defer World State, Simulation, Learned Router, and RL
+
+Status: Accepted
+
+## Context
+
+AgentOS is evolving from a project into a platform. Future coding agents need rationale that preserves architectural boundaries.
+
+## Decision
+
+Those features require real campaign, repair, routing, evaluator, and receipt history before they can be principled.
+
+## Consequences
+
+- Implementation must prefer boundary preservation over feature breadth.
+- Tests should encode this decision when practical.
+- Future changes should create a superseding ADR rather than silently changing philosophy.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,11 @@
+# Architecture Decision Records
+
+ADRs capture why the architecture exists, not only what to implement.
+- [Use Campaign Kernel as the Core Repository Concept](0001-use-campaign-kernel-name.md)
+- [Capability Routing over Provider Routing](0002-capability-routing-over-provider-routing.md)
+- [LangGraph as Runtime Only](0003-langgraph-runtime-only.md)
+- [Evaluator Before Execution](0004-evaluator-before-execution.md)
+- [Immutable Receipts](0005-immutable-receipts.md)
+- [BYOK Credential Plane](0006-byok-credential-plane.md)
+- [Resource Manager, not Wallet](0007-resource-manager-not-wallet.md)
+- [Defer World State, Simulation, Learned Router, and RL](0008-defer-world-state-simulation-rl.md)
diff --git a/docs/agentos/01-product-vision-product-thesis.md b/docs/agentos/01-product-vision-product-thesis.md
@@ -0,0 +1,18 @@
+# Product Vision & Product Thesis
+
+AgentOS packages the Campaign Kernel into a product that turns user outcomes, budgets, SLAs, constraints, and quality requirements into evaluated artifacts. The repository remains `campaigns` / Campaign Kernel: the reusable control-plane core, not a monolithic `agentos` app.
+
+## Boundary rules
+
+- Strengthen architectural boundaries before adding functionality.
+- Keep the core flow: Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact.
+- Providers are interchangeable device drivers behind implementations.
+- LangGraph is runtime/checkpoints/streaming only; it is not the system of record.
+- Hermes, dashboards, SDKs, and MCP clients are clients, not databases.
+
+## Phase 0 implications
+
+- Define contracts and evaluators before expanding execution features.
+- Emit measurable artifacts and immutable receipts for every material decision.
+- Prefer relational state; use vectors only for semantic retrieval needs.
+- Track Expected User Value per Dollar and Cost of Quality where routing or repair decisions are made.
diff --git a/docs/agentos/02-system-philosophy.md b/docs/agentos/02-system-philosophy.md
@@ -0,0 +1,18 @@
+# System Philosophy
+
+AgentOS is an operating system for campaigns, not an agent framework. The stable flow is Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact. Agents are implementation details behind capabilities.
+
+## Boundary rules
+
+- Strengthen architectural boundaries before adding functionality.
+- Keep the core flow: Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact.
+- Providers are interchangeable device drivers behind implementations.
+- LangGraph is runtime/checkpoints/streaming only; it is not the system of record.
+- Hermes, dashboards, SDKs, and MCP clients are clients, not databases.
+
+## Phase 0 implications
+
+- Define contracts and evaluators before expanding execution features.
+- Emit measurable artifacts and immutable receipts for every material decision.
+- Prefer relational state; use vectors only for semantic retrieval needs.
+- Track Expected User Value per Dollar and Cost of Quality where routing or repair decisions are made.
diff --git a/docs/agentos/03-c4-context-diagram.md b/docs/agentos/03-c4-context-diagram.md
@@ -0,0 +1,18 @@
+# C4 Context Diagram
+
+Users, Hermes, dashboards, MCP clients, and SDKs submit outcomes to Campaign Kernel. Campaign Kernel coordinates capabilities, budgets, credentials, providers, LangGraph execution, memory, artifacts, receipts, and evaluations.
+
+## Boundary rules
+
+- Strengthen architectural boundaries before adding functionality.
+- Keep the core flow: Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact.
+- Providers are interchangeable device drivers behind implementations.
+- LangGraph is runtime/checkpoints/streaming only; it is not the system of record.
+- Hermes, dashboards, SDKs, and MCP clients are clients, not databases.
+
+## Phase 0 implications
+
+- Define contracts and evaluators before expanding execution features.
+- Emit measurable artifacts and immutable receipts for every material decision.
+- Prefer relational state; use vectors only for semantic retrieval needs.
+- Track Expected User Value per Dollar and Cost of Quality where routing or repair decisions are made.
diff --git a/docs/agentos/04-c4-container-diagram.md b/docs/agentos/04-c4-container-diagram.md
@@ -0,0 +1,18 @@
+# C4 Container Diagram
+
+Containers are campaign-kernel, agentos-dashboard, agentos-sdk, agentos-mcp, agentos-docs, and drivers/openai|anthropic|codex|claude-code|ollama. The kernel owns business state; clients are never the database.
+
+## Boundary rules
+
+- Strengthen architectural boundaries before adding functionality.
+- Keep the core flow: Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact.
+- Providers are interchangeable device drivers behind implementations.
+- LangGraph is runtime/checkpoints/streaming only; it is not the system of record.
+- Hermes, dashboards, SDKs, and MCP clients are clients, not databases.
+
+## Phase 0 implications
+
+- Define contracts and evaluators before expanding execution features.
+- Emit measurable artifacts and immutable receipts for every material decision.
+- Prefer relational state; use vectors only for semantic retrieval needs.
+- Track Expected User Value per Dollar and Cost of Quality where routing or repair decisions are made.
diff --git a/docs/agentos/05-component-diagrams.md b/docs/agentos/05-component-diagrams.md
@@ -0,0 +1,18 @@
+# Component Diagrams
+
+Core components: Campaign API, Planner, Capability Registry, Capability Router, Budget Engine, Resource Manager, Credential Plane, Evaluator, Repair Loop, Artifact Store, Receipt Store, Event Bus, Hermes Adapter, MCP Server, and LangGraph Runtime Adapter.
+
+## Boundary rules
+
+- Strengthen architectural boundaries before adding functionality.
+- Keep the core flow: Goal -> Campaign Kernel -> Capability -> Implementation -> Evaluation -> Artifact.
+- Providers are interchangeable device drivers behind implementations.
+- LangGraph is runtime/checkpoints/streaming only; it is not the system of record.
+- Hermes, dashboards, SDKs, and MCP clients are clients, not databases.
+
+## Phase 0 implications
+
+- Define contracts and evaluators before expanding execution features.
+- Emit measurable artifacts and immutable receipts for every material decision.
+- Prefer relational state; use vectors only for semantic retrieval needs.
+- Track Expected User Value per Dollar and Cost of Quality where routing or repair decisions are made.