Package Exports

@jaimevalasek/aioson
@jaimevalasek/aioson/src/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@jaimevalasek/aioson) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

AIOSON

AI operating framework for hyper-personalized software.

Structure your AI sessions. Orchestrate specialized agents. Ship with confidence.

Works in any IDE with a terminal — VS Code, Google Antigravity, Cursor, Windsurf, JetBrains IDEs, Zed, and more.

AIOSON gives every AI session a role, a protocol, and a lifecycle.
Instead of one massive prompt doing everything, each agent owns a well-defined slice — from discovery to deployment — and hands off cleanly to the next.

Installation

# New project
npx @jaimevalasek/aioson init my-project

# Existing project
cd my-project
npx @jaimevalasek/aioson install

Running init or install launches an interactive wizard to configure:

Which AI tools to enable (Claude Code, Codex CLI, Gemini CLI, OpenCode)
Mode — Development or Development + Squads
Design system (optional) — Clean SaaS UI, Aurora Command UI, Cognitive Core UI, etc.
Agent language — English, Português, Español, Français

Only the relevant files are copied. No extra dependencies are installed.

Skip the wizard — install everything at once with --all:

npx @jaimevalasek/aioson init my-project --all
npx @jaimevalasek/aioson install --all

Reconfigure — add tools or activate Squads after the initial install:

npx @jaimevalasek/aioson install --reconfigure

CI / automation — install without prompts:

npx @jaimevalasek/aioson install --no-interactive

Update to a new version (respects your saved profile):

npx @jaimevalasek/aioson update

How it works

  New project                              Existing project
       │                                         │
       ▼                                         ▼
  aioson init                           aioson install .
       │                                aioson scan:project
       └──────────────┬──────────────────────────┘
                      │
                      ▼
              ┌───────────────┐
              │  /setup       │  ← Project context & onboarding
              └───────┬───────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
    /analyst     /architect    /product      ← Discovery & planning
          │           │           │
          └───────────┼───────────┘
                      ▼
              ┌───────────────┐
              │  /sheldon     │  ← PRD enrichment & deep technical reasoning
              └───────┬───────┘
                      ▼
              ┌───────────────┐
              │   /ux-ui      │  ← Design system & UI specs
              └───────┬───────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
      /deyvin       /dev        /pm          ← Implementation
          │           │           │
          └───────────┼───────────┘
                      ▼
              ┌───────────────┐
              │    /qa        │  ← Review, tests, browser QA
              └───────────────┘

Each agent runs as a tracked live session with full runtime observability — milestones, handoffs, and context snapshots recorded in the AIOSON dashboard.

Why AIOSON

Most AI sessions are conversations. AIOSON is a protocol.

Every feature goes through a defined lifecycle — spec, gate, build, verify — and every agent knows exactly where it is in that lifecycle. The result: AI that doesn't guess, doesn't drift, and doesn't lose track when the context window fills up.

Spec-Driven Development

Vague prompt → unambiguous spec → gated execution. No skipping phases, no silent assumptions.

"add a stock management feature"
         │
         ▼ @product
   prd-stock-management.md
   ┌──────────────────────────────────────┐
   │ objectives, out-of-scope, open items │
   └──────────────────────────────────────┘
         │
         ▼ @sheldon          ← PRD enrichment
   sheldon-enrichment-stock.md
   ┌──────────────────────────────────────┐
   │ gray areas decided, readiness score  │
   │ RF-GA extraction, AC hardening       │
   └──────────────────────────────────────┘
         │
         ▼ Gate A            ← requirements approved?
   requirements-stock.md     ← REQ-stock-001, AC-stock-001 …
         │
         ▼ Gate B            ← design approved?
   architecture.md + design-doc-stock.md
         │
         ▼ Gate C            ← implementation plan reviewed?
   implementation-plan-stock.md
         │
         ▼ @dev / @deyvin    ← code, commits, spec updates
         │
         ▼ Gate D            ← 4-tier verification
   @qa forensics: Exists → Substantive → Wired → Functional

Gates are blocking in MEDIUM projects, informational in SMALL. Each gate is enforced by a checklist in spec-{slug}.md — agents can't advance without explicit approval signals. No more AI that starts coding before the requirements are clear.

What you get in the spec file:

Field	What it tracks
`phase_gates`	`requirements: approved`, `design: approved`, `plan: approved`
`last_checkpoint`	Exactly where the agent stopped — resume without re-reading everything
`gray_areas_decided`	Every ambiguity that was surfaced and decided, with rationale
`must_haves`	Triplet contract: truths, artifacts, key links
`readiness` / `readiness_notes`	@sheldon's go/no-go signal before implementation starts

Context intelligence

AI sessions fail silently. Context fills up, the model forgets, the agent reinvents what was already decided. AIOSON ships a full context management layer so this never happens quietly.

5-phase context optimization system:

Session Recovery — when Claude compacts or a session crashes, one command restores the full working state:

aioson recovery:generate   # snapshot current state, < 2 000 tokens
aioson recovery:show       # paste this into the new session — agent picks up exactly where it left

Context Monitor — real-time usage bars with adaptive thresholds per project size:

aioson context:monitor     # ASCII bars, warning/critical detection

Context usage ████████████░░░░ 73%  ⚠ approaching threshold (SMALL: 65%)
Agents recommend /clear before next phase

FTS5 Search Index — find anything across all your project artifacts in milliseconds:

aioson context:search "payment webhook retry logic"
# BM25 ranking + recency reranking — surfaces the right doc, not just keyword matches

Context Cache — save and restore session snapshots without losing what the AI already knows:

aioson context:cache save --label="before-refactor"
aioson context:cache restore --label="before-refactor"

Agent Sharding — agents load only the instructions relevant to the current goal. Irrelevant sections are stripped before the context window fills:

aioson agent:load deyvin --goal="fix stock modal validation"
# 68% token reduction — agent arrives focused, not bloated

Adaptive learning — AIOSON tracks what worked and evolves agent behavior over time:

aioson learning:evolve    # distill patterns from completed sessions
aioson learning:apply     # push improvements back into the agent chain

Context budget thresholds by project size:

Classification	Warning threshold	Why
MICRO	75%	Short phases — ok to run higher
SMALL	65%	Default — balanced warning
MEDIUM	55%	Long phases — warn early, write artifacts first

When an agent approaches its threshold it writes all in-progress artifacts to disk, emits a warning, and records last_checkpoint — so the next session can start from state, not from memory.

AIOSON Squads

Squads are the part of AIOSON that most people don't expect.

You can build a specialized, multi-agent team for any domain — software development, content creation, legal review, gastronomy, YouTube, music production, marketing, or anything you can describe. A squad is a fully packaged, versioned, invocable team of AI agents that lives inside your project and gets smarter over time.

                    ┌─────────────────────────────────────────────┐
                    │              AIOSON Squad                    │
                    │                                              │
                    │  @orchestrator ─── coordinates the team      │
                    │       │                                      │
                    │  ┌────┴──────────────────────────┐          │
                    │  │         Executors              │          │
                    │  │  @scriptwriter  @copywriter    │          │
                    │  │  @analyst       @reviewer      │          │
                    │  └───────────────────────────────┘          │
                    │       │                                      │
                    │  ┌────┴──────────────────────────┐          │
                    │  │  Genome (cognitive layer)      │          │
                    │  │  "how this team thinks"        │          │
                    │  │  domain · function · persona   │          │
                    │  └───────────────────────────────┘          │
                    │       │                                      │
                    │  ┌────┴──────────────────────────┐          │
                    │  │  Skills (operational layer)    │          │
                    │  │  "what this team knows how to do"        │
                    │  └───────────────────────────────┘          │
                    └─────────────────────────────────────────────┘

Create a squad for any domain

# Software squad
@squad
> domain: SaaS product development
> goal: ship features end-to-end
> roles: product, architect, dev, qa

# YouTube content squad
@squad
> domain: YouTube content creation
> goal: scriptwriting, hooks, retention
> roles: scriptwriter, hook-analyst, thumbnail-strategist, orchestrator

# Legal review squad
@squad
> domain: contract review — Brazilian corporate law
> goal: flag risks, suggest amendments
> roles: risk-analyst, clause-reviewer, summarizer

Each squad gets its own package under .aioson/squads/{slug}/ — agents, manifest, output folder, execution logs. Every agent is directly invocable by the user: @scriptwriter, @risk-analyst, @hook-analyst.

Genome — the cognitive layer

Skills tell an agent what to do. A genome tells it how to think.

@genome
> type: domain
> domain: viral content strategy
> depth: expert

→ generates: .aioson/genomes/viral-content-strategy.md
  - mental models and decision frameworks
  - quality lenses and judgment heuristics
  - anti-patterns and known failure modes
  - vocabulary and reference benchmarks

Four genome types:

Type	What it encodes
`domain`	Deep knowledge of a field — editorial, legal, financial, technical
`function`	Operational expertise — retention analysis, risk review, architecture
`persona`	Cognitive profile of a real person — their mental models, blindspots, style
`hybrid`	Combination of domain + persona with weighted influence

Apply a genome to any squad executor and the agent thinks with those lenses — not just follows instructions.

Persona genomes and the Profiler pipeline

When a squad revolves around a specific person's methodology — a creator, strategist, or thought leader — AIOSON can profile them and inject their cognitive fingerprint into the squad.

@genome --type=persona --person="Alex Hormozi"
         │
         ▼ @profiler-researcher
   Web research, books, interviews, frameworks collected
         │
         ▼ @profiler-enricher
   Cognitive analysis, psychometric profiling
   DISC profile, Enneagram, Big Five, MBTI mapped
         │
         ▼ @profiler-forge
   .aioson/profiler-reports/alex-hormozi/enriched-profile.md
   genome-alex-hormozi.md (Genome 3.0)
         │
         ▼ applied to @copywriter in your squad
   @copywriter now reasons with Hormozi's offer-framing mental models

Genome 3.0 fields include disc, enneagram, big_five, mbti, confidence, and hybrid_mode — so you know exactly how confident the profiling is and where it was inferred vs. evidence-based.

DISC behavioral profiles

Every squad executor can be assigned a behavioral profile so its communication style, decision speed, and conflict resolution match the squad's dynamics:

Profile	Traits	Best for
`dominant-driver`	Direct, fast, results-first	Execution agents, sprint leads
`influential-expressive`	Persuasive, creative, high energy	Content creators, copywriters
`steady-amiable`	Patient, empathetic, consensus-driven	Reviewers, QA, support agents
`compliant-analytical`	Precise, systematic, risk-aware	Analysts, architects, legal review
+ 4 hybrid combinations	—	—

Ephemeral squads

Need a quick throwaway team for a one-off task?

@squad --ephemeral
> domain: competitive analysis for this pitch
> ttl: 24h

Ephemeral squads skip the full design-doc flow, use a timestamped slug, and self-expire after the TTL. They never pollute CLAUDE.md or AGENTS.md. Use them for research sessions, quick drafts, or exploratory tasks.

Cross-squad orchestration

Multiple squads can run in parallel in the same project. When an executor from one squad encounters a task outside its domain, it routes to the right sibling squad automatically — no manual handoff needed.

project/
  .aioson/squads/
    content-squad/      @scriptwriter, @hook-analyst, @orchestrator
    dev-squad/          @architect, @dev, @qa, @orchestrator
    legal-squad/        @risk-analyst, @clause-reviewer, @orchestrator

# @scriptwriter receives a question about the privacy policy clause in a script
→ cross-squad router detects: legal domain
→ hands off to @clause-reviewer in legal-squad
→ returns answer to content-squad session

The orchestrator of each squad knows its siblings, reads their manifests, and routes out-of-domain requests rather than silently absorbing them or hallucinating an answer.

Webhook integration — trigger squads from anywhere

AIOSON ships a built-in HTTP webhook server. External systems — WhatsApp, Telegram, Slack, ERPs — can trigger any squad and receive async responses via callback.

aioson squad:webhook start --squad=content-squad --port=3100

[WhatsApp message]  →  POST /trigger  →  squad executes
                                              ↓
[user receives reply]  ←  POST callback_url  ←  async response

Endpoints:

Method	Path	Description
`POST`	`/trigger`	Async execution with callback URL + exponential backoff retry
`GET`	`/status/:run_id`	Poll run status
`POST`	`/query`	Sync execution (10s timeout)
`GET`	`/health`	Server health check

Bearer token auth and rate limiting (60 req/min/IP) ship out of the box. No extra dependencies — pure node:http.

Squad Dashboard

Real-time web panel for monitoring all your squads. Ships with AIOSON, zero extra install.

aioson squad:dashboard              # → http://localhost:4180
aioson squad:dashboard --squad=content-squad   # jump to a specific squad
aioson squad:dashboard --port=4200  # custom port

What the dashboard shows:

Active agents and their current task
Context usage per agent with warning indicators
Token consumption over time
Execution logs and milestone history
Squad health score and ROI metrics
Cross-squad pipeline status

Run multiple projects simultaneously on different ports — one dashboard per project.

Squad commands reference

Lifecycle — create, validate, maintain

aioson squad:create <slug>          # create a new squad
aioson squad:validate <slug>        # validate manifest, agents, and output config
aioson squad:analyze <slug>         # deep analysis of squad health and coverage
aioson squad:extend <slug>          # add executors or skills to existing squad
aioson squad:repair <slug>          # fix broken genomes, missing agents, schema drift
aioson squad:export <slug>          # export squad as portable package
aioson squad:deploy <slug>          # deploy squad to target environment

Execution — run, plan, orchestrate

aioson squad:plan <slug>            # generate execution plan before running
aioson squad:worker <slug>          # start a squad worker process
aioson squad:daemon <slug>          # run squad as background daemon
aioson squad:processes <slug>       # list running squad processes
aioson squad:worktrees <slug>       # parallel git worktrees per worker
aioson squad:merge <slug>           # merge worktree branches back

Intelligence — genome, learning, profiling

aioson squad:mcp <slug>             # MCP connector registry for squad
aioson squad:learning <slug>        # review and apply learning from past sessions
aioson squad:score <slug>           # quality and coverage score
aioson squad:roi <slug>             # ROI metrics from session history
aioson squad:investigate <domain>   # domain investigation before squad design
aioson squad:agent-create <slug>    # create a custom agent inside a squad

Integration — pipelines, webhooks, recovery

aioson squad:pipeline <slug>        # inter-squad DAG pipeline with ports
aioson squad:webhook start          # HTTP webhook server for external triggers
aioson squad:recovery <slug>        # recover interrupted squad session
aioson squad:dashboard              # real-time web monitoring panel

Agents

Agent	Role	Best for
`/setup`	Project onboarding & context	First step on any project
`/analyst`	Domain discovery & entity mapping	Understanding the problem space
`/architect`	Project structure & technical decisions	Architecture, stack choices
`/product`	Product decisions & PRD	Feature scope, user stories
`/ux-ui`	UI/UX design system & component specs	Dashboards, flows, components
`/pm`	Backlog & user stories	Sprint planning, task breakdown
`/deyvin` / `/pair`	Feature implementation	Coding — greenfield or brownfield
`/dev`	Feature implementation (any stack)	Focused dev tasks
`/qa`	Risk-first review & test generation	Quality gates before ship
`/orchestrator`	Session protocol & parallel execution	Multi-agent coordination
`/squad`	Parallel agent squads	Large feature sets in parallel
`/genome`	Agent knowledge & learning	Adaptive squad intelligence
`/sheldon`	Deep technical reasoning	Hard engineering problems
`/orache`	Orchestration & routing	Complex multi-step pipelines
`/profiler-researcher`	Research & profiling	External data gathering
`/profiler-enricher`	Profile enrichment	Data augmentation
`/profiler-forge`	Profile generation	Structured output creation
`/site-forge`	Site cloning & design extraction	Clone, harvest, blend, or forge skills from any URL

Quick start

# Install globally
npm install -g @jaimevalasek/aioson

# New project
aioson init my-project

# Existing project
cd my-project
aioson install .

# One-off (no global install)
npx @jaimevalasek/aioson init my-project

Then open your AI client and activate an agent:

# See all agents and their activation prompts
aioson agents

# Get the activation prompt for any agent
aioson agent:prompt setup --tool=claude

# See the recommended agent sequence for your project size
aioson workflow:plan --classification=SMALL

Requirements

Core

Requirement	Version	Notes
Node.js	≥ 18.0.0	Required by the CLI
An AI CLI tool	—	Claude Code, Codex CLI, Gemini CLI, or OpenCode

Optional — by feature

Feature	Requirement
`scan:project` — brownfield scanner	`aioson-models.json` with a cheap LLM API key (DeepSeek, OpenAI, Gemini, Groq, Together, Mistral, or Anthropic)
`qa:run` / `qa:scan` — browser QA	`npm install -g playwright && npx playwright install chromium`
`mcp:init` / `mcp:doctor`	MCP-compatible tool (Claude Code, Gemini CLI, OpenCode, or Codex CLI)
Web3 support	Hardhat, Foundry, Anchor, or other supported chain toolchain

Tracked live sessions

AIOSON can track every AI session with full runtime observability — useful when working from external clients like Claude Code, Codex CLI, or Gemini CLI.

# Open a tracked session before the AI client starts
aioson live:start . --tool=claude --agent=deyvin --plan=plan.md --no-launch

# Emit milestones as work progresses
aioson runtime:emit . --agent=deyvin --type=task_started --title="Fix stock modal"
aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Stock modal fixed" --refs="src/app.js"

# Hand off the session to another agent (keeps the same session envelope)
aioson live:handoff . --agent=deyvin --to=qa --reason="Ready for review"

# Monitor in real-time
aioson live:status . --watch=2

# Close and generate summary.md
aioson live:close . --agent=qa --summary="QA complete, shipped"

Commands

Setup & install

aioson init <project-name> [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]
aioson install [path] [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]
aioson update [path] [--lang=en|pt-BR|es|fr]
aioson info [path] [--json]
aioson doctor [path] [--fix] [--dry-run] [--json]
aioson setup:context [path] [--defaults] [--framework=<name>] [--lang=en|pt-BR|es|fr]
aioson context:validate [path] [--json]
aioson scan:project [path] [--provider=<name>] [--dry-run] [--json]

Agents & workflow

aioson agents
aioson agent:prompt <agent> [--tool=codex|claude|gemini|opencode]
aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json]

Parallel orchestration

aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json]
aioson parallel:assign [path] [--source=auto|prd|architecture|discovery|<file>] [--workers=2..6]
aioson parallel:status [path] [--json]
aioson parallel:doctor [path] [--workers=2..6] [--fix] [--force] [--dry-run] [--json]

MCP

aioson mcp:init [path] [--tool=claude|codex|gemini|opencode] [--dry-run] [--json]
aioson mcp:doctor [path] [--strict-env] [--json]

mcp:init generates .aioson/mcp/servers.local.json and tool-specific preset templates. Supports Context7 and Database MCP in remote-endpoint mode.

Browser QA (Playwright)

aioson qa:init [path] [--url=<app-url>] [--dry-run] [--json]
aioson qa:run [path] [--url=<app-url>] [--persona=naive|hacker|power|mobile] [--headed] [--html] [--json]
aioson qa:scan [path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json]
aioson qa:report [path] [--html] [--json]
aioson qa:doctor [path] [--json]

i18n & locale

aioson i18n:add <locale>
aioson locale:apply [path] [--lang=en|pt-BR|es|fr]

Built-in locales: en, pt-BR, es, fr. Use --lang or AIOS_LITE_LOCALE env var.

Testing & CI

aioson test:smoke [workspace-path] [--lang=en|pt-BR|es|fr] [--web3=ethereum|solana|cardano] [--profile=standard|mixed|parallel] [--keep] [--json]
aioson test:package [source-path] [--keep] [--dry-run] [--json]

Multi-IDE support

IDE / Client	Config file
Claude Code	`CLAUDE.md`
Codex CLI	`AGENTS.md`
Gemini CLI	`.gemini/GEMINI.md`
OpenCode	`OPENCODE.md`

Web3 support

Supports project_type=dapp with detection for Ethereum (Hardhat, Foundry, Truffle), Solana (Anchor, Solana Web3), and Cardano (Aiken/Cardano SDK).

aioson setup:context . \
  --web3-enabled=true \
  --web3-networks=ethereum,solana \
  --contract-framework=Hardhat \
  --wallet-provider=wagmi \
  --indexer="The Graph" \
  --rpc-provider=Alchemy

See the Web3 guide for full details.

JSON output for CI

Most commands support --json for structured output. See JSON schemas for contracts.

aioson info --json
aioson doctor --json
aioson agents --json
aioson parallel:status --json
aioson qa:run --json
aioson scan:project --json

Documentation

CLI & commands

CLI reference — full docs for every command
JSON schemas — --json output contracts

Feature guides

Portuguese guides

License

AGPL-3.0-only — GNU Affero General Public License v3.0