azrole 3.0.0

package/README.md

@@ -0,0 +1,548 @@
+# azrole
+
+**Self-evolving AI infrastructure for any coding CLI.**
+
+One command. Your AI gets smarter every session.
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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. 9 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       The brain — adapted for each CLI
+  +-- 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
+
+```bash
+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](docs/case-studies/book-manuscript.md)
+
+---
+
+## How It Works
+
+The orchestrator is a single AI agent (~1900 lines) that carries the knowledge of 10 mastery levels plus a self-evolving intelligence layer. It adapts to whichever CLI you're using.
+
+**`/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](https://github.com/haytamAroui)