SMAG

Package: smag-ia

Current public version: 0.1.4

SMAG (Supervised Machine Agent Governance) is a governance/control-plane for AI coding executors. SMAG is not the coding agent: executors such as Codex perform the coding work while SMAG governs staging, policy, audit, acceptance, approval and promotion.

End-user requirements

• Node.js 24 or newer;
• npm/npx;
• at least one supported coding executor reported as READY by SMAG.

Bun is not an end-user requirement. Bun is used to develop the SMAG monorepo itself.

Zero-install execution

[email protected] currently exposes more than one npm binary. Therefore the package-name shorthand npx [email protected] ... is ambiguous in npm and is not the validated current path.

Use explicit package + CLI binary selection:

npx --yes [email protected] smag --version
npx --yes [email protected] smag init
npx --yes [email protected] smag agents
npx --yes [email protected] smag doctor

Run a governed task from the project directory you want SMAG to supervise:

npx --yes [email protected] smag --agent codex "Inspect this workspace and report one non-destructive observation. Do not modify files."

Issue #114 tracks simplification of the shorthand invocation in a future version. Do not republish 0.1.4; npm versions are immutable.

Optional global install

npm install --global [email protected]

Then:

smag --version
smag init
smag agents
smag doctor

The normal installed CLI command remains smag.

First governed write

From a disposable Git repository:

npx --yes [email protected] smag init
npx --yes [email protected] smag agents
npx --yes [email protected] smag doctor
npx --yes [email protected] smag --agent codex "Create exactly hello-smag.txt containing exactly HELLO-SMAG. Do not modify any other file."

For an accepted run, the expected final decision is PASS and the exit code is 0. Executor success alone is not final authority: SMAG independently evaluates the staged change and acceptance before promotion.

Architecture invariants

• Staging is isolated from the target workspace.
• Audit is independent.
• Acceptance is independent.
• Promotion occurs only after required validation.
• Unknown critical state fails closed.
• Rollback protects the target when post-promotion acceptance fails.
• Executor identity is preserved; there is no silent executor fallback.
• The governance core is not coupled to one executor.

Core commands

smag "<task>"                          Run task with auto executor selection
smag --agent codex "<task>"            Run task with a specific executor
smag --dry-run "<task>"                Request dry-run behavior
smag --approve-before-promote "<task>" Require approval before promotion
smag agents                            List detected executors
smag init                              Initialize .smag/config.json
smag run task.json                     Run from a task specification
smag issue 42                          Run from GitHub issue #42
smag pr 7                              Run from GitHub PR #7
smag mission create ...                Create a durable mission
smag mission show <missionId>          Inspect mission state
smag mission run <missionId>           Execute/resume a mission
smag github <action>                   Governed GitHub operator surface
smag doctor                            Check environment health

Current publication evidence

Executed Windows/PowerShell evidence for [email protected]:

npm publish = PASS
npm view [email protected] version = 0.1.4
npm view [email protected] dist-tags = { latest: '0.1.4' }
explicit-bin --version = PASS
explicit-bin agents = PASS
explicit-bin doctor = PASS

Pre-publication package validation:

npm test = 509 PASS / 0 FAIL / 1 SKIP
npm run test:distribution = 2 PASS / 0 FAIL

Historical evidence that names @igorbrito.ti/smag remains historical and should not be rewritten as if smag-ia had already been published at those revisions.

See ../../docs/release/SMAG-IA-0.1.4-CURRENT.md for the current release record.

Developing SMAG itself

This section is for contributors, not normal users.

git clone https://github.com/oigorbrito/smag.git
cd smag
bun install

Package validation:

cd packages/smag-governance
npm test
npm run test:distribution
npm run pack:check