azrole

azrole

Self-evolving AI infrastructure for any coding CLI.

One command. Your AI gets smarter every session.

npx azrole init

Works with every major AI coding CLI:

CLI	Status
Claude Code	Full support
Codex CLI (OpenAI)	Full support
OpenCode	Full support
Gemini CLI (Google)	Full support
Cursor	Full support

Works for any project — code, books, research, business:

/dream fitness app with React Native and Firebase       <- software
/dream fantasy novel about a time-traveling librarian    <- book
/dream market analysis for AI startup in healthcare      <- research
/setup                                                   <- existing project

Auto-detects which CLIs you have installed. One command installs for all of them.

The Problem

Every AI coding CLI is a Ferrari with no steering wheel.

Claude Code, Codex, OpenCode, Gemini CLI, Cursor — the engines are incredible. But to actually use them, you need to:

• Learn project rules syntax (CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules)
• Learn agent YAML frontmatter and how to write good agent prompts
• Learn skills structure and how triggering works
• Learn commands and argument passing
• Learn memory systems and their limits
• Learn MCP server configuration
• Learn hooks and automation
• Figure out how all of these connect to each other
• Do this separately for every CLI you use

That's not vibe coding. That's hours of reading documentation before writing a single line of your actual project.

Most people install an AI CLI, type a few prompts, and never unlock 90% of what it can do. Not because they're not smart enough — because the setup barrier is too high.

The bigger problem: Even if you set everything up perfectly, your AI forgets everything between sessions. AZROLE solves both: the setup barrier AND the persistence gap.

Without AZROLE vs With AZROLE

Without — you manually create each file, one by one, after reading docs:

You:     "How do I set up agents?"
Google:  *reads docs for 30 minutes*
You:     *creates one agent file with basic frontmatter*
You:     "Now how do skills work?"
Google:  *reads more docs*
         ... 3 hours later, you have a half-configured environment
         ... next session, the AI has forgotten everything

With — you describe your idea and everything gets built:

You:     /dream food delivery app with React Native, Node.js, and Stripe
Claude:  [Level 1] Building CLAUDE.md... done
           CLAUDE.md (94 lines) — architecture, conventions, directory structure
           .gitignore — configured for Node.js
         [Level 2] Building MCP config... done
           .mcp.json — 3 servers (github, postgres, filesystem)
         [Level 3] Building skills and commands... done
           Skills: react-native-patterns, nodejs-patterns, project-conventions
           Commands: add, test, review, new-screen, new-endpoint
         [Level 4] Building memory system... done
           MEMORY.md (138 lines) — master index
           codebase-map, patterns, antipatterns — ready
         [Level 5] Building specialized agents... done
           dev-mobile.md (sonnet) — owns app/screens/, app/components/
           dev-backend.md (sonnet) — owns server/routes/, server/services/
           dev-tester.md (sonnet, background: true) — owns __tests__/
           dev-reviewer.md (opus, read-only) — code review specialist

         Your Level: 5 / 10 — "Multi-Agent"
         [=========================.............] 5/10

         Ready! Try: /add user authentication with phone number

2 minutes. Zero documentation. Full environment. Knowledge that compounds.

Quick Start

1. Install (once)

npx azrole init          # auto-detects your CLIs
npx azrole init --all    # install for ALL supported CLIs
npx azrole init --claude # Claude Code only
npx azrole init --gemini # Gemini CLI only
npx azrole init --codex  # Codex CLI only

2a. New project — describe your idea

mkdir my-app && cd my-app
claude    # or: codex, opencode, gemini

/dream SaaS analytics dashboard with Next.js, Python FastAPI,
PostgreSQL, Stripe billing, deployed on Vercel

2b. Existing project — scan and set up

cd my-existing-app
claude    # or: codex, opencode, gemini

/setup

The orchestrator scans your codebase, detects your tech stack from actual files, and builds the environment around what already exists — in the right format for whichever CLI you're using.

3. Start building

/add user authentication with Google OAuth

4. Level up when ready

/level-up

7 Commands — All Plain English

No jargon. No dev knowledge needed. Just type what you want.

Build & Grow

Command	What it does
/dream "your idea"	New project — describe your idea, get everything built
/setup	Existing project — scans your code, builds the environment around it
/level-up	See your current level (0-10), build the next one
/evolve	Auto-find and fix gaps in your agents, skills, and memory

Everyday Use

Command	What it does
/fix "what's broken"	Describe the bug in plain English, get it fixed
/ship	Save your work and push to GitHub (auto-generates commit message)
/explain "anything"	Explain code, errors, or concepts like you're not a developer
/status	Quick health check — what's working, what changed, what to do next

Real Workflow Example

/dream fitness tracker app with React Native and Firebase
  ... orchestrator builds your entire dev environment ...

/add user profile page with avatar upload
  ... specialist agent builds the feature ...

/fix the avatar doesn't show after upload
  ... agent finds the bug, fixes it, explains what happened ...

/explain what does useEffect do in the profile component
  ... explains in plain English, no jargon ...

/ship
  ... commits with message "Add user profile with avatar upload", pushes to GitHub ...

/status
  ... shows: 12 files changed, all tests passing, suggests adding unit tests ...

/level-up
  ... scans environment, shows Level 5, offers to build Level 6 (hooks & automation) ...

Not Just for Developers

AZROLE adapts to any project type:

You are a...	You type...	You get...
Developer	/dream SaaS app with Next.js and Stripe	Frontend agent, backend agent, tester, reviewer, coding skills
Writer	/dream mystery novel set in 1920s Paris	Writer agent, editor agent, researcher, continuity checker, style skills
Researcher	/dream PhD thesis on climate migration patterns	Researcher agent, analyst, academic writer, methodology skills
Marketer	/dream product launch campaign for AI fitness app	Strategist agent, copywriter, reviewer, brand voice skills

Same system. Same 10 levels. Different agents and skills for every domain.

The 10 Levels

Most AI CLI users are stuck at Level 0-1. The gap between levels isn't knowledge — it's setup.

Levels 1-5: Build the team. Levels 6-10: Make the team learn.

Level  0  Terminal Tourist     You type prompts and hope for the best
Level  1  Foundation           Project rules + .gitignore
Level  2  Connected            MCP servers (GitHub, databases, APIs)
Level  3  Skilled              Custom skills + slash commands
Level  4  Remembering          Memory system — project learns over time
Level  5  Multi-Agent          Specialist agents working together
------------------------------ PERSISTENCE BARRIER ------------------------------
Level  6  Learning             Hooks + agent learning protocol (knowledge survives sessions)
Level  7  Scoped               Advanced MCP + agents scoped to specific servers
Level  8  Orchestrated         Pipelines + debate engine + prompt self-optimization
Level  9  Workflow             /deploy, /sprint, /refactor, /retro — all update memory
Level 10  Self-Evolving        Loop controller + ELO ranking + topology optimization + KPI dashboard

The Persistence Barrier at Level 5 is where most setups fail. Below it, agents do brilliant work and forget everything when the session ends. Above it, every session makes the project smarter — patterns accumulate, antipatterns get documented, mistakes never repeat.

Every level creates only native files (markdown + JSON). No bash scripts. No cron jobs. Works on Windows, Mac, and Linux identically.

/dream builds you to Level 5 by default. /level-up takes you higher, one step at a time. /evolve strengthens what you already have.

The AZROLE Intelligence Architecture

What makes AZROLE different from a static setup tool:

┌─────────────────────────────────────────────────────┐
│                 INTELLIGENCE LOOP                    │
│                                                      │
│  Agents work ──> Learn ──> Score ──> Optimize ──>   │
│       ^                                         │    │
│       └─────────────────────────────────────────┘    │
│                                                      │
│  Memory Importance Scoring                           │
│    Every piece of knowledge gets a score.            │
│    High-impact rises. Stale fades. Memory sharpens.  │
│                                                      │
│  ELO Output Ranking                                  │
│    Agents, patterns, and debate outcomes get ranked.  │
│    Better agents get harder tasks. Weak patterns      │
│    get flagged for review.                           │
│                                                      │
│  Prompt Self-Optimization                            │
│    Underperforming agents get their prompts rewritten │
│    based on what worked for high-performing agents.   │
│    A/B tested. Winners kept. Losers archived.        │
│                                                      │
│  Topology Optimization                               │
│    Pipeline orderings are tested and measured.        │
│    Low-influence agents get pruned or merged.         │
│    Building blocks (reflect, debate, summarize)       │
│    are injected where they improve quality.           │
│                                                      │
│  Debate Engine                                       │
│    High-stakes decisions get two opposing advocates.  │
│    A synthesis phase picks the winner on evidence,    │
│    not opinion. Decisions logged with review triggers.│
│                                                      │
│  Quality KPI Dashboard (scores.json)                 │
│    Every evolution cycle is measured. Environment,    │
│    knowledge, and quality KPIs tracked over time.    │
│    Trend: improving / stable / declining.            │
└─────────────────────────────────────────────────────┘

This is not a one-time generator. It's a system that gets better every time you use it.

What Gets Generated

After running /dream, your project gets a complete AI development environment:

your-project/
  CLAUDE.md                          Project conventions (Claude reads this first)
  .gitignore                         Configured for your stack
  .mcp.json                          MCP server connections
  .devteam/
    blueprint.json                   Project analysis
    scores.json                      Quality KPI dashboard (Level 10+)
    elo-rankings.json                Agent & pattern ELO rankings (Level 8+)
    memory-scores.json               Memory importance scores (Level 10+)
    topology-map.json                Pipeline topology tracking (Level 10+)
    prompt-versions/                 A/B test archive for prompt optimization
  .claude/
    settings.json                    Hooks & permissions (Level 6+)
    agents/
      dev-frontend.md                Frontend specialist (sonnet)
      dev-backend.md                 Backend specialist (sonnet)
      dev-tester.md                  Testing specialist (sonnet, background)
      dev-reviewer.md                Code reviewer (opus, read-only)
      dev-pipeline.md                Multi-agent workflows (Level 8+)
      dev-experiment.md              Safe experiments in worktree (Level 8+)
      dev-debate.md                  Multi-perspective decision engine (Level 8+)
      dev-prompt-optimizer.md        Self-evolving prompt quality (Level 8+)
      loop-controller.md             Self-improvement engine (Level 10)
    skills/
      react-patterns/SKILL.md        Frontend patterns for YOUR stack
      fastapi-patterns/SKILL.md      Backend patterns for YOUR stack
      project-conventions/SKILL.md   Your project's rules and style
    commands/
      add.md                         Add a feature by describing it
      test.md                        Run tests, explain results
      review.md                      Code review
      deploy.md                      Deployment pipeline (Level 9+)
      sprint.md                      Plan & execute work (Level 9+)
    memory/
      MEMORY.md                      Master knowledge base (auto-loaded)
      codebase-map.md                Every module indexed
      patterns.md                    Discovered patterns (ELO-ranked)
      antipatterns.md                Known pitfalls
      decisions.md                   Architecture decisions (from debates)

Everything is tailored to YOUR project. Not templates. Not generic. Real, specific infrastructure.

Every AI CLI Feature — Configured Automatically

AZROLE doesn't reinvent anything. It configures what your AI CLI already has:

Claude Code Feature	What AZROLE does with it
CLAUDE.md	Generates project conventions, architecture, agent routing
Agents	Creates specialists with full frontmatter (model, permissions, skills, MCP, hooks)
Skills	Builds patterns with progressive disclosure (SKILL.md + references/), pushy descriptions for reliable triggering
Commands	7 global + project-specific commands generated from your stack
Memory	Persistent knowledge base — codebase map, patterns, antipatterns, decisions
MCP Servers	Auto-detects from your stack, scopes per agent via mcpServers:
Hooks	Auto-format on file saves, agent completion notifications
Model routing	opus for thinking, sonnet for building, haiku for simple tasks
Permission modes	acceptEdits for builders, plan for reviewers — no permission spam
Background agents	background: true on testers for concurrent work
Worktree isolation	isolation: worktree for safe experiments that can't break your code
Tool scoping	disallowedTools: Write, Edit on reviewers — read-only by design
Agent chaining	Pipeline agents that delegate to specialists via Agent tool

You get all of this without knowing any of it exists.

What Gets Installed

The package is tiny. 11 files per CLI, installed to the right location automatically:

~/.claude/          (Claude Code)
~/.codex/           (Codex CLI)
~/.config/opencode/ (OpenCode)
~/.gemini/          (Gemini CLI)
~/.cursor/          (Cursor)
  +-- agents/
      orchestrator.md           Coordinator (~800 lines, lean)
      intelligence-module.md    Pipelines, debate, prompt optimization (Level 8-9)
      evolution-module.md       Loop controller, topology, KPIs (Level 10)
  +-- commands/
      dream.md (.toml)      /dream — build from a project idea
      setup.md (.toml)      /setup — scan existing project
      level-up.md (.toml)   /level-up — grow to the next level
      evolve.md (.toml)     /evolve — auto-improve environment
      fix.md (.toml)        /fix — describe a bug, get it fixed
      ship.md (.toml)       /ship — commit and push changes
      explain.md (.toml)    /explain — plain English explanations
      status.md (.toml)     /status — project health check

No dependencies. No background processes. No config files. The orchestrator generates everything else dynamically based on your project. Gemini CLI uses .toml commands, all others use .md — handled automatically.

CLI Reference

npx azrole init                 # Auto-detect CLIs, install globally
npx azrole init --all           # Install for ALL supported CLIs
npx azrole init --claude        # Install for Claude Code only
npx azrole init --codex         # Install for Codex CLI only
npx azrole init --opencode      # Install for OpenCode only
npx azrole init --gemini        # Install for Gemini CLI only
npx azrole init --cursor        # Install for Cursor only
npx azrole init --force         # Reinstall, overwrite modified files
npx azrole init-local           # Install in current project only
npx azrole detect               # Show which CLIs are installed
npx azrole status               # Check installation status
npx azrole uninstall            # Remove everything
npx azrole --version            # Show version

Also works as npx ai-dreamteam and npx claude-dreamteam for backward compatibility.

Real Case Study: A Book Manuscript

Not a demo. Not a mock. This is what happened when /setup was run on an actual 150,000-word biography manuscript.

Project: A premium nonfiction biography — 24 chapters, 5 parts, ~150K words. LaTeX/LuaLaTeX production pipeline.

Starting state: 3 raw files. No CLAUDE.md. No agents. No skills. No memory. Level 0.

/setup

2 minutes later — Level 5:

Level 1: CLAUDE.md               -- 73 lines — architecture, conventions, editorial standards
Level 2: MCP Servers             -- Skipped (no external services needed)
Level 3: Skills & Commands       -- 3 skills, 4 commands
Level 4: Memory System           -- 32-line index + 3 knowledge files
Level 5: Multi-Agent             -- 4 specialized agents

What it built:

4 Agents — each with a specific role:

Agent	Model	Role
dev-writer	Sonnet	Chapter drafting, prose, narrative voice
dev-editor	Opus	Continuity, transitions, structural integrity
dev-typesetter	Sonnet	LaTeX compilation, typography, layout
dev-reviewer	Opus	Full manuscript audit, publication readiness

3 Skills — domain knowledge always available:

• latex-memoir/ — LuaLaTeX engine rules, custom commands, anti-patterns
• editorial-craft/ — Narrative voice, 5 thematic threads, cultural sensitivity guidelines
• project-conventions/ — File naming, chapter numbering, production specs

4 Commands — plain English:

Command	What it does
/build	Compile manuscript with LuaLaTeX, diagnose errors, fix, recompile
/audit-chapter 12	Full editorial audit of chapter 12 with star ratings
/new-chapter "The Riyadh Season launch"	Scaffold a new chapter in the right structure
/review	Manuscript-wide quality pass with delta comparison

Memory system — the project remembers:

• Codebase map with every file's role and dependencies
• Architecture decisions (why LuaLaTeX, why single content file)
• Discovered patterns (execution lens, thematic threading, temporal anchoring)
• Known gotchas (Part IV timeline overlaps, weakest transitions)

The person who ran this is not a developer. They write books.

Full setup log: DREAMTEAM_SETUP_LOG.md

How It Works

The system is split into three agents to keep context lean:

• Orchestrator (~800 lines) — Levels 0-7, coordinator for higher levels
• Intelligence Module (~400 lines) — Levels 8-9: pipelines, debate, prompt optimization
• Evolution Module (~500 lines) — Level 10: loop controller, topology, KPI dashboard

The orchestrator handles Levels 0-7 directly. For Levels 8+, it spawns the appropriate module as a sub-agent, passing it all the context it needs. This means your AI CLI only loads ~800 lines during normal work — the heavy intelligence and evolution modules are loaded only when needed.

/dream analyzes your project idea, creates a blueprint, then builds each level sequentially. It delegates to sub-agents for each level, runs quality checks, and presents everything created.

/level-up scans your environment file by file, calculates your current level, shows what the next level unlocks, and builds it.

/evolve runs a gap analysis across agents, skills, commands, memory, AND knowledge health. Scores each area 1-10. Fixes the top 5 weaknesses. Consolidates scattered learnings into structured knowledge. Reports the improvement with quality KPIs.

The intelligence layer (Levels 8-10):

• Debate engine spawns opposing advocates for high-stakes decisions, synthesizes on evidence quality, logs outcomes with review triggers
• ELO ranking tracks agent quality, pattern effectiveness, and debate outcomes over time — higher-ELO agents get harder tasks
• Memory importance scoring evaluates every piece of knowledge on frequency, recency, and impact — high-value knowledge rises, stale knowledge auto-archives
• Prompt self-optimization analyzes which agent prompts produce the best outputs, rewrites underperformers, A/B tests changes
• Topology optimization measures agent influence in pipeline chains, reorders for higher quality, prunes low-influence agents, injects building blocks (reflect, debate, summarize) where they help
• Quality KPI dashboard (scores.json) tracks environment, knowledge, topology, and quality metrics across evolution cycles with trend analysis

Your project doesn't just remember. It gets smarter.

FAQ

Does this only work for coding projects? No. AZROLE works for any project — software, books, research papers, marketing campaigns, legal documents. The orchestrator detects whether you're building code, writing content, doing research, or running a business project and adapts agents, skills, and commands accordingly.

Does this work with any tech stack? Yes. React, Vue, Angular, Svelte, Next.js, FastAPI, Django, Express, Rails, Go, Rust, Flutter, React Native, and anything else. The orchestrator analyzes whatever you describe.

Does it generate actual code for my app? No. It generates the AI infrastructure (agents, skills, commands, memory) that helps you build your app faster. Think of it as hiring an AI dev team, not building your app.

Can I customize what it generates? Everything is plain markdown files. Edit any agent, skill, or command after generation. The orchestrator creates the starting point — you own it from there.

What model does it use? The orchestrator uses Opus for deep analysis. Generated agents use smart routing: Opus for architecture and review, Sonnet for implementation, Haiku for simple tasks. You can change any agent's model.

Will it overwrite my existing files? The CLI protects modified files. If you edited a file, init skips it unless you pass --force. The orchestrator never deletes user-created files.

Does it work on Windows? Yes. Every level uses only native files (markdown + JSON). No bash scripts, no cron, no OS-specific tools. Windows, Mac, Linux — identical.

Does this work with Codex CLI / OpenCode / Gemini CLI / Cursor? Yes. AZROLE auto-detects which CLIs you have installed and sets up for all of them. Same commands, same levels, adapted file formats. Use --all to install for every supported CLI.

How is this different from the built-in /init command? Most AI CLIs have a basic /init that generates a simple rules file. That's Level 1. AZROLE builds Levels 1-10: agents, skills, commands, memory, MCP, hooks, pipelines, debate engine, ELO ranking, prompt optimization, topology optimization, and a self-improving loop.

What's the difference between AZROLE and ai-dreamteam? AZROLE is the evolution of ai-dreamteam. Same creator, same architecture, now with self-evolving intelligence (ELO ranking, prompt optimization, memory importance scoring). npx ai-dreamteam still works for backward compatibility.

Is this free? The package is free. You need a subscription to your AI CLI of choice (which uses your own API credits).

License

MIT

Built by @haytamAroui