Atomism

Schema-first agent swarm orchestration framework.

Build verifiable, composable AI workflows with type-safe atoms that graduate to deterministic generators.

Install

npm install -g atomism

Quick Start

atomic init
atomic create atom hello_world
atomic register atoms/hello_world.ts
atomic run hello_world --input '{"name": "World"}' --yes

What is an Atom?

An atom is a small, testable, reusable unit of work with validated inputs and outputs:

import { z } from 'zod';
import { defineAtom, success } from 'atomism';

export default defineAtom({
  name: 'hello_world',
  description: 'Generates a greeting',
  input: z.object({
    name: z.string().describe('Name to greet'),
  }),
  output: z.object({
    greeting: z.string(),
  }),
  tests: { path: './hello_world.test.ts' },
  idempotent: true,
  handler: async ({ name }) => {
    return success({ greeting: `Hello, ${name}!` });
  },
});

Features

Schema-First Design

Every atom has Zod schemas for inputs and outputs. Type safety at compile time, validation at runtime.

Generator Evolution

When atoms produce similar outputs repeatedly, graduate them to deterministic generators:

atomic graduate hello_world    # Creates generators/hello_world.ts
atomic revert hello_world      # Reverts to handler if needed

Trust-Based Execution

Atoms earn trust through successful runs. New atoms require confirmation, trusted atoms run automatically:

atomic trust --list                        # View trust levels
atomic trust my_stack --level proven       # Promote trust

Trust levels: new → proven → trusted

Workflows

Compose atoms into dependency-resolved workflows:

atomic workflow run feature_pipeline       # Execute workflow
atomic workflow resume feature_pipeline    # Resume failed workflow
atomic plan feature_pipeline               # Preview execution plan

Generator Import

Import existing generators from other systems:

atomic scan-generators                     # Detect Plop, Hygen, Yeoman, etc.
atomic import-generator --plop component   # Import to atomic format
atomic import-generator --hygen model/new
atomic import-generator --cookiecutter ./template
atomic validate-generator --all            # Verify imports work

Skills Integration

Connect atoms to Claude Code skills:

atomic skills scan                         # Discover available skills
atomic skills suggest my_atom              # Get recommendations
atomic skills assign my_atom --skill code-review

Extraction

Create atoms from existing sources:

atomic extract --skill ./skills/refactor.md
atomic extract --code ./lib/parser.ts
atomic extract --mcp ./tools/search.json

CLI Reference

Core Commands

| Command | Description | |---------|-------------| | atomic init | Initialize .atomic/ directory | | atomic create atom <name> | Scaffold new atom | | atomic register <path> | Register atom file | | atomic run <atom> | Execute atom or generator | | atomic list | List registered atoms | | atomic status | Show system state | | atomic history [runId] | View execution history |

Testing

| Command | Description | |---------|-------------| | atomic test <atom> | Run atom tests | | atomic test-gen <path> | Generate structural tests |

Graduation

| Command | Description | |---------|-------------| | atomic graduate <atom> | Graduate to generator | | atomic revert <atom> | Revert to handler |

Trust

| Command | Description | |---------|-------------| | atomic trust --list | List all trust levels | | atomic trust <stack> --level <level> | Set trust level | | atomic trust <stack> --reset | Reset to new |

Workflows

| Command | Description | |---------|-------------| | atomic workflow run <name> | Execute workflow | | atomic workflow list | List workflows | | atomic workflow resume <name> | Resume failed workflow | | atomic plan <workflow> | Preview execution plan | | atomic escalate | Create issue for blocked work |

Generator Import

| Command | Description | |---------|-------------| | atomic scan-generators | Detect existing generators | | atomic import-generator | Import from Plop/Hygen/Yeoman/etc | | atomic validate-generator | Validate imported generators |

Skills

| Command | Description | |---------|-------------| | atomic skills scan | Discover Claude Code skills | | atomic skills suggest <atom> | Get skill recommendations | | atomic skills assign <atom> | Assign skill to atom | | atomic skills list <atom> | List assigned skills | | atomic skills remove <atom> | Remove skill from atom |

All commands support --json for structured output.

Library API

import {
  defineAtom,
  success,
  failure,
  validationError,
  executionError,
  z,
} from 'atomism';

// Result helpers
success({ data: 'value' })           // Success response
failure('Something went wrong')       // Error response
validationError('Invalid input')      // Validation error
executionError('Runtime failure')     // Execution error

Documentation

Full documentation: https://github.com/roach88/atomism

Requirements

• Node.js 20+

License

MIT