Quick Install

Requires: Node.js ≥ 22, Python 3.11+, Git.

Interactive Menu (recommended)

npx @joelbonito/inove-ai-framework

Opens a PT-BR installation wizard with 6 options:

● Instalação Completa       — Full install: .agents/, instruction files, symlinks, git hooks
○ Instalação Personalizada  — Choose platforms, components and squads individually
○ Atualizar                 — Update without overwriting CLAUDE.md, AGENTS.md, GEMINI.md
○ Adicionar Plataforma      — Enable Claude Code, Codex CLI or Gemini / Antigravity
○ Verificar Instalação      — Check missing files, broken symlinks and dependencies
○ Desinstalar               — Remove .agents/ and symlinks (project code untouched)

During "Instalação Completa", the wizard also asks for Gemini MCP API keys (optional — you can configure later in .gemini/mcp.json):

? Configurar chaves de API para MCPs do Gemini?
  Context7 (real-time lib docs) e Stitch (UI prototyping). Optional.
  ○ Não  ● Sim

? CONTEXT7_API_KEY (Context7): ________________
? STITCH_API_KEY (Stitch):     ________________

If you skip, placeholder env vars (${CONTEXT7_API_KEY}, ${STITCH_API_KEY}) are written to .gemini/mcp.json automatically.

Non-Interactive (CI / scripts)

npx @joelbonito/inove-ai-framework install

No prompts — installs everything with defaults. Use --force to overwrite an existing installation:

npx @joelbonito/inove-ai-framework install --force

Keep it up-to-date

npx @joelbonito/inove-ai-framework update

Updates .agents/, scripts and skills without overwriting your instruction files (CLAUDE.md, AGENTS.md, GEMINI.md).

Validate your installation

npx @joelbonito/inove-ai-framework validate

Checks core agents, core skills, core workflows and scripts (current counts: python3 .agents/scripts/validate_installation.py), symlinks and platform configs. Squad components (e.g. game) are tracked separately and only checked when the squad is active.

What's Included

• Core Agents for different domains (frontend, backend, security, database, mobile, UX, game dev, etc.) + extra agents via Squads (e.g. game-developer)
• Core Skills loaded on demand (clean-code, testing-patterns, api-patterns, tailwind, etc.) + extra skills via Squads
• Core Workflows (slash commands) for structured processes + extra workflows via Squads
• Squad System — reusable agent+skill+workflow packages for custom domains
• Recovery System — automatic retry and git checkpoint/rollback for resilient execution
• Stitch MCP Integration — visual mockups for UI projects via /spec and /ui-ux-pro-max
• Multi-Agent System with lock synchronization and ownership
• Documentation Website — Next.js site with full reference docs (web/)

Usage

Using Agents

No need to mention agents explicitly! The system automatically detects and applies the right specialist(s):

You: "Add JWT authentication"
AI: Applying @security-auditor + @backend-specialist...

You: "Fix the dark mode button"
AI: Using @frontend-specialist...

You: "Login returns 500 error"
AI: Using @debugger for systematic analysis...

You: "Design the onboarding flow"
AI: Using @ux-researcher for user journey mapping...

Available Agents

| Agent | Domain | |-------|--------| | orchestrator | Multi-agent coordination | | project-planner | Planning & discovery | | product-strategist | Discovery, PRD, backlog & MVP | | frontend-specialist | React, UI/UX, Tailwind | | backend-specialist | APIs, Node.js, server logic | | database-architect | Schemas, queries, migrations | | mobile-developer | iOS nativo, Android nativo, React Native, Flutter | | security-auditor | Auth, OWASP, compliance + red team | | debugger | Root cause analysis | | devops-engineer | VPS, CI/CD, Docker, infrastructure | | test-engineer | Test strategies | | qa-automation-engineer | E2E & automation | | performance-optimizer | Speed & optimization | | seo-specialist | SEO & visibility | | ux-researcher | User flows, wireframes, usability | | documentation-writer | Manuals & docs | | code-archaeologist | Legacy refactoring | | game-developer | Game logic & engines | | explorer-agent | Codebase analysis |

Using Workflows

Invoke workflows with slash commands:

| Command | Description | |---------|-------------| | /spec | Full spec pipeline (--light/--full) — replaces /define + /plan + /readiness | | /run-loop | Autonomous implementation loop with verify gate | | /journeys | Document user journeys | | /context | Create Project Context | | /brainstorm | Explore options before implementation | | /create | Create new features or apps | | /debug | Systematic debugging | | /enhance | Improve existing code | | /test | Generate and run tests | | /test-book | Generate/update Test Book | | /deploy | Deploy application | | /preview | Manage dev server (start/stop/restart) | | /orchestrate | Multi-agent coordination | | /review | Post-sprint code review | | /ui-ux-pro-max | Advanced design system with data-driven palettes | | /status | Check project status | | /log | Record work sessions | | /finish | Mark tasks as complete | | /release | Finalize project and generate release | | /squad | Create and manage agent squads |

Legacy aliases (/define, /plan, /readiness, /track) still work until consolidation — prefer the canonical commands above.

Example:

/spec Task management app
/brainstorm authentication system
/create landing page with hero section
/debug why login fails
/squad create mobile-team

Multi-Platform Support

| Tool | Instruction File | How it works | |------|-----------------|--------------| | Codex CLI | AGENTS.md | Stub pointing to .agents/INSTRUCTIONS.md | | OpenCode | AGENTS.md | Stub pointing to .agents/INSTRUCTIONS.md | | Claude Code | CLAUDE.md | Stub importing AGENTS.md (requires Claude Code ≥2.x for @import) | | Gemini / Antigravity | GEMINI.md | Stub pointing to .agents/INSTRUCTIONS.md | | Cursor | .cursor/rules/inove.mdc | alwaysApply rule → .agents/INSTRUCTIONS.md; Projects: inove-projects.mdc + inove-projects-worker.mdc |

All platforms share the same canonical source: .agents/INSTRUCTIONS.md.

Cursor Projects

Inove is the contract (stories, owner_paths, verify, collision_check, finish_task). Cursor Projects is the runtime: the Project coordinator is the sole planner of the execution wave (dispatch, sequential integration, one PR). Installing or updating the framework copies .agents/rules/ and symlinks .cursor/rules → .agents/rules, so inove.mdc, inove-projects.mdc, and inove-projects-worker.mdc apply automatically.

Do not run a parallel /run-loop or /orchestrate alongside the Projects coordinator. inove-projects.mdc opens with an ÂMBITO gate (ignore the rule if you are not a Project agent) and a precedence contract: Projects execution prevails over inove.mdc / Regra Zero for owner_paths; otherwise (loose local chat, Zcode, Claude/Codex, /spec planning) inove.mdc + Regra Zero ON. The User Rule template points at .agents/ and does not duplicate the kit.

One-time setup (not written by install/update — Cursor UI):

1. User Rule (global, once): Cursor Settings → Rules → paste .agents/templates/cursor/CURSOR_USER_RULE_GLOBAL.md.
2. Project Instructions (each Cursor Project): paste .agents/templates/cursor/PROJECT_INSTRUCTIONS_TEMPLATE.md.

Atalho recomendado (install + guia):

npx @joelbonito/inove-ai-framework bootstrap-cursor
# opções: --force  --dry-run  --dir <path>  --skip-install

Isto corre o equivalente a install --cursor-native, tenta escrever a User Rule em ~/.cursor/rules/ (rules globais maquina-local), grava uma cópia de Project Instructions em .cursor/PROJECT_INSTRUCTIONS.md, copia ambos para o clipboard quando possível, e imprime um checklist PT-BR. User Rules da conta (Settings sync) e Project Instructions do Cursor Project continuam a precisar de colar na UI.

Refresh the kit with:

npx @joelbonito/inove-ai-framework update

That updates .agents/ (including rules and templates) without overwriting CLAUDE.md, AGENTS.md, or GEMINI.md. Re-paste the User Rule / Project Instructions only if those templates changed.

Cursor-native export

.agents/ remains the source of truth. export-cursor generates a per-repo .cursor/ subset (it does not symlink the entire skill tree and does not create orchestrator.md):

npx @joelbonito/inove-ai-framework export-cursor
# or from a clone of this repo
node bin/commands/export-cursor.js
# during install (instead of the directory-level skills/rules symlink)
npx @joelbonito/inove-ai-framework install --cursor-native
# optional: also materialize intelligent-routing + parallel-agents
npx @joelbonito/inove-ai-framework export-cursor --with-orchestration-skills

Writes .cursor/rules/ (inove-core.mdc + Projects playbook when present), 15 specialists under .cursor/agents/, ~18 core skills plus inove-spec / inove-review / inove-finish / inove-status, and bin/inove-gates. Default export does not copy intelligent-routing or parallel-agents (those stay in the Projects playbook).

npx @joelbonito/inove-ai-framework gates --list
./bin/inove-gates collision_check
python3 .agents/scripts/finish_task.py "{id}"   # equivalent

Contract: docs/cursor-export-contract.md.

Usage Flows

| Flow | Tools | Best For | |------|-------|----------| | Flow A | Claude Code alone | Full autonomy — planning + implementation in one tool | | Flow B | Gemini (planning) + Codex (implementation) | Team separation of concerns | | Standalone | Any single tool | Each tool works independently with graceful fallbacks |

Stitch MCP (UI Projects)

For projects with visual interfaces, Stitch MCP provides high-fidelity mockup generation:

• /spec Phase 3.5 — Visual mockups are mandatory
• /ui-ux-pro-max Step 2c — Visual preview is mandatory
• /spec — Validates mockup existence

Backend-only, API, or CLI projects: Stitch is skipped automatically.

Squad System

Squads are reusable packages of agents + skills + workflows for specific domains.

/squad create mobile-team      # Create a new squad
/squad list                    # List available squads
/squad activate mobile-team    # Activate squad in framework
/squad validate mobile-team    # Validate integrity

Squads live in squads/<name>/ with a squad.yaml manifest. See squads/README.md for details.

Project Structure

.agents/
├── agents/           # Specialized agents (role-based personas)
├── skills/           # Knowledge modules (lazy-loading via frontmatter manifest)
├── workflows/        # Slash command workflows (/spec, /run-loop, ...)
├── scripts/          # Python automation
├── config/           # Per-platform configuration (models.toml, codex.toml, mcp.json)
├── rules/            # Cursor alwaysApply rules (inove.mdc, inove-projects.mdc, inove-projects-worker.mdc)
├── templates/        # /spec templates + Cursor User Rule / Project Instructions pastes
├── .shared/          # Shared data (UI/UX databases)
└── ARCHITECTURE.md   # Technical documentation

squads/               # Reusable agent+skill+workflow packages
│ └── games/          # game-developer (activate on demand)
.gemini/              # Gemini CLI config (created automatically on install)
│ ├── settings.json   # Model and system instruction
│ ├── mcp.json.example # MCP servers template (Context7, Stitch) — placeholders
│ └── mcp.json        # Your MCP servers with live keys — gitignored
tests/                # Framework tests
web/                  # Documentation website (Next.js)
docs/                 # Project docs, backlog, logs

Documentation

• Architecture: .agents/ARCHITECTURE.md
• Full Instructions: .agents/INSTRUCTIONS.md
• Skills: .agents/skills/*/SKILL.md
• Agents: .agents/agents/*.md
• Workflows: .agents/workflows/*.md
• Website: web/ (run with cd web && npm run dev)

Based on

This project is a fork of Antigravity Kit by Vudovn, extended with multi-platform support (Claude Code + Codex CLI), additional agents, skills, and workflows.

License

MIT - See LICENSE for details.