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:

1. Which AI tools to enable (Claude Code, Codex CLI, Gemini CLI, OpenCode)
2. Mode — Development or Development + Squads
3. Design system (optional) — Clean SaaS UI, Aurora Command UI, Cognitive Core UI, etc.
4. 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 the AIOSON files in your project (respects your saved profile):

npx @jaimevalasek/aioson update

Updating an existing project to a new release? See Upgrading — aioson update alone is not enough if the CLI itself is out of date.

Upgrading

Two things can be on different versions: the CLI you run (aioson) and the AIOSON files inside your project (.aioson/). Both need to move together.

⚠ The #1 reason aioson update "doesn't bring in the new version": aioson update copies the templates bundled with the CLI currently on disk. If your global CLI is on an older release, running aioson update from a project will copy that older version's files — no matter how many times you run it. You have to upgrade the CLI itself first.

Step 1 — upgrade the CLI.

If you installed globally:

npm install -g @jaimevalasek/aioson@latest
aioson --version

If aioson --version still shows the old version, the binary is being shadowed (older Node on PATH, nvm switch, leftover global install). Reinstall cleanly:

npm uninstall -g @jaimevalasek/aioson
npm install -g @jaimevalasek/aioson@latest
aioson --version

Prefer not to install globally at all? Use npx pinned to @latest — it always fetches the latest published version and ignores anything installed globally:

npx @jaimevalasek/aioson@latest <command>

Step 2 — refresh the AIOSON files in each project.

From inside the project directory:

aioson update

This copies the latest agents, skills, and templates into .aioson/, respecting your saved profile. Repeat in every project you want to bring up to date.

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
          │           │           │
          └───────────┼───────────┘
                      ▼
              ┌───────────────┐
              │ /pentester    │  ← Adversarial security review (MEDIUM)
              └───────┬───────┘
                      ▼
              ┌───────────────┐
              │    /qa        │  ← Review, tests, browser QA
              └───────┬───────┘
                      ▼
              ┌───────────────┐
              │   /tester     │  ← Systematic test engineering (when needed)
              └───────────────┘

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:

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:

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:

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:

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:

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

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

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

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

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

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

Optional — by feature

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"

AIOSON Store

Package, publish, and distribute squads, genomes, skills, and full systems through the AIOSON Store.

# Package and publish your system/boilerplate
aioson system:package .
aioson system:publish . --name=my-stack

# Build mode: compile TS/JSX, obfuscate JS (terser), package as ZIP
aioson system:publish . --name=my-stack --build

# Publish squads, genomes, and skills
aioson squad:publish . --squad=marketing --version=1.0.0
aioson genome:publish . --slug=fintech --version=1.0.0
aioson skill:publish . --slug=vue-spa --version=1.0.0

# Install from the Store
aioson squad:install . --slug=marketing --version=1.0.0
aioson genome:install . --slug=fintech
aioson system:install . --slug=laravel-saas

Authentication via auth:login and workspace management via workspace:* commands are supported for cloud features.

Commands

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] [--all]
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] [--folder=src] [--with-llm] [--provider=<name>] [--dry-run] [--json]

aioson agents
aioson agent:prompt <agent> [--tool=codex|claude|gemini|opencode]
aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json]
aioson workflow:next [path] [--complete] [--auto-heal] [--force]
aioson workflow:heal [path] --stage=<agent>
aioson workflow:harden [path] [--dry-run]
aioson workflow:execute [path] [--dry-run] [--start-from=<agent>]
aioson intake:ask [path] --agent=<agent> --schema=<questions.json> [--out=<answers.json>] [--json]

aioson preflight [path] [--json]
aioson classify [path] [--json]
aioson gate:check [path] --gate=A|B|C|D [--json]
aioson artifact:validate [path] --feature=<slug> [--json]
aioson detect:test-runner [path] [--json]
aioson agent:audit [path] [--json]
aioson brief:gen [path] --feature=<slug> [--json]
aioson verify:gate [path] --feature=<slug> [--json]

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]

aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<agent> [--plan=<file>] [--no-launch]
aioson live:handoff [path] --agent=<agent> --to=<next-agent> --reason="..."
aioson live:status [path] [--watch=<seconds>]
aioson live:close [path] --agent=<agent> --summary="..."
aioson runtime:emit [path] --agent=<agent> --type=<event> --summary="..."

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

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]

aioson squad:status [path]
aioson squad:doctor [path] --squad=<slug>
aioson squad:validate [path] --squad=<slug>
aioson squad:export [path] --squad=<slug>
aioson squad:bus [path] --squad=<slug> --sub=post|read|watch|summary|list|clear
aioson squad:autorun [path] --squad=<slug> --goal="..."
aioson squad:daemon [path] --squad=<slug> --sub=start|stop|status
aioson squad:worker [path] --squad=<slug> --sub=list|run
aioson squad:dashboard [--port=4180] [--squad=<slug>]

aioson auth:login --token ...
aioson auth:status
aioson workspace:init [path] --name=<slug>
aioson system:package [path]
aioson system:publish [path] --name=<slug>
aioson squad:publish [path] --squad=<slug> [--paid]
aioson squad:install [path] --slug=<slug>
aioson genome:publish [path] --slug=<slug>
aioson genome:install [path] --slug=<slug>
aioson skill:publish [path] --slug=<slug>

aioson context:pack [path] [--agent=<agent>] [--goal="..."] [--module=<folder>]
aioson context:health [path]
aioson feature:archive [path] --feature=<slug> [--dry-run] [--restore] [--force]
aioson context:monitor [path] [--budget=<n>] [--tokens=<n>]
aioson context:search:index [path]
aioson context:search [path] --query="..."
aioson context:cache:save --label=<name>
aioson context:cache:restore --label=<name>
aioson compress:agents [path] [--agent=<name>] [--rules] [--dry-run] [--restore]

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

aioson commit:prepare [path] [--json]
aioson git:guard [path] [--install-hook] [--json]

aioson test:agents [path]
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

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

• Parallel orchestration
• MCP guide
• Browser QA guide
• Web3 guide
• i18n guide
• Squad Dashboard

Portuguese guides

Entender

• O que é AIOSON
• Por que existe
• Mapa do ecossistema
• Glossário

Começar

• Primeiro projeto
• Projeto existente
• Decisões iniciais

Receitas

• App SaaS do zero
• Feature completa com Sheldon
• Da ideia ao PRD via briefing
• Landing page
• Continuidade entre sessões
• Integração em codebase grande
• Refatoração grande
• Auditoria de segurança
• Clonar design de site
• Publicar no AIOSON Store

Agentes

• Guia de agentes
• Referência por agente

Referência

• Clientes AI
• SDD framework
• Motor hardening
• Runtime observability
• Live sessions
• Memória e contexto
• Feature dossier
• Agent sharding
• Skills
• Sandbox executor
• Squad Dashboard (PT)
• Design-docs governance
• Runner system
• Secure by default

Living Memory

• Memória viva
• Autonomy contract

Research Inspirations

AIOSON may study external agent-workflow patterns as product research. These links are inspiration references only: they are not runtime dependencies, endorsements, or citations inside generated AIOSON artifacts.

• Interview-style clarification and lightweight decision records
  • https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me
  • https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs
  • https://github.com/mattpocock/skills/tree/main/README.md

License

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