SMAG

SMAG is a modular control plane for AI agents and coding agents.

The repository now includes validated local boundaries for the runner, governance, routing, Service API, external observability, MVP CLI/package flow, and a .NET client adapter. See docs/CURRENT-STATE.md for the compact factual snapshot.

Official Direction

SMAG should build the governance and coordination capabilities that are specific to SMAG, while reusing mature open source projects for execution, orchestration, sandboxing, workflow, GitHub automation, and related capabilities when evidence shows they fit.

Directional target:

• TARGET_OSS_REUSE: about 70-80%.
• TARGET_SMAG_SPECIFIC: about 20-30%.

These numbers are guardrails against unnecessary reinvention. They are not artificial quotas.

Architecture Model

SMAG does not seek a single mandatory framework or harness. The architecture direction is composition by responsibility.

Current prioritized candidates and expected roles:

| Candidate | Expected Role | | --- | --- | | Agent Orchestrator | Coding-agent orchestration, parallel execution, worktrees, branches, PRs, CI/review loop, multi-agent lifecycle. | | Omnigent | Meta-harness, abstraction between coding agents, executor switching, policies, useful sandbox abstractions. | | OpenHands Software Agent SDK | Agent runtime, software-engineering execution, tools, sandbox/runtime, lifecycle, multi-LLM integration. | | GitHub Agentic Workflows | GitHub-native workflows, Actions, CI, events, permissions, guardrails, post-execution automation. | | Microsoft Agent Framework | Workflow, state/session, multi-agent primitives, multi-provider support, tools/MCP, approvals, telemetry, .NET/Python reference. |

No candidate is adopted definitively by this README.

SMAG-Owned Responsibilities

SMAG should concentrate on:

• Work Unit Contract;
• Policy / Authorization;
• Risk Decision;
• Budget Governance;
• Evidence Model;
• Human Approval Model;
• Supervisor State Machine;
• executor/model routing;
• adapter contracts;
• recovery policy;
• unified audit trail.

Evidence Principle

Technical claims must remain classified as DOCUMENTED, EXECUTED, MEASURED, INFERRED, or NOT VERIFIED. Do not promote documented or inferred capability into executed or measured capability without real execution and evidence.

Benchmark Status

Benchmarks have not started. The benchmark model is capability validation, not a five-way framework ranking.

The protocol is documented in docs/testing/HARNESS-BENCHMARK-PROTOCOL.md, and result recording is prepared in docs/testing/BENCHMARK-RESULTS.md.

Documentation Map

• AGENTS.md: working contract for coding agents.
• docs/architecture/ARCHITECTURE-PRINCIPLES.md: architectural principles.
• docs/architecture/HARNESS-EVALUATION.md: capability-oriented candidate evaluation.
• docs/testing/HARNESS-BENCHMARK-PROTOCOL.md: capability validation protocol.
• docs/testing/BENCHMARK-RESULTS.md: result records for real evidence only.
• docs/research/REFERENCE-MANIFEST.md: local reference repository manifest.
• docs/decisions/README.md: Architecture Decision Record format.

MVP Operability Layer

The MVP operator flow is:

1. install the package;
2. optionally create a config file with smag init;
3. validate the config with smag config validate;
4. start the service with smag serve;
5. check health with smag health;
6. run a WorkUnit with smag run.

Quickstart:

npm install
npm run smag -- init
npm run smag -- config validate
npm run smag -- serve

In another terminal:

npm run smag -- health
npm run smag -- run examples\work-units\hello.json --json

The default config is safe on loopback, free-first, and does not require paid provider credits or OTLP.

Engineering Harness

Reusable agent rules live in skills/. The harness commands reduce repeated prompt text and produce factual baseline/evidence output:

npm run smag -- harness baseline --json
npm run smag -- harness verify --manifest examples\work-units\engineering-harness.json --fast --json
npm run smag -- harness current-state

WorkUnit manifests are JSON data only. They reference allowlisted command keys and do not execute arbitrary shell strings.

.NET Client

The .NET client is a transport-only consumer of the same Service API. It does not embed the SMAG control plane.

var httpClient = new HttpClient { BaseAddress = new Uri("http://127.0.0.1:3000") };
var client = new Smag.Client.SmagClient(httpClient, new Smag.Client.SmagClientOptions
{
    BaseAddress = new Uri("http://127.0.0.1:3000"),
});

var health = await client.GetHealthAsync();
var run = await client.RunAsync(new Smag.Client.SmagWorkUnit
{
    Id = "wu-hello",
    Objective = "Return a factual hello-world execution result.",
    AllowedPaths = ["src"],
    ForbiddenPaths = ["secrets"],
});