cortex-ia

README

cortex-ia

AI Agent Ecosystem Configurator. One command configures any AI coding agent with persistent memory, SDD workflow, inter-agent messaging, and multi-CLI orchestration.

Quick Start

# Install
go install github.com/lleontor705/cortex-ia/cmd/cortex-ia@latest

# Interactive TUI
cortex-ia

# CLI install (auto-detect agents)
cortex-ia install

# Specific agent + preset
cortex-ia install --agent claude-code --preset minimal

# Preview without changes
cortex-ia install --dry-run

What It Does

cortex-ia detects your installed AI coding agents and configures them with a complete development ecosystem:

Component	Tools	Purpose
Cortex	19 MCP tools	Persistent cross-session memory with knowledge graph
ForgeSpec	15 MCP tools	SDD contract validation, task board, file reservation
Agent Mailbox	9 MCP tools	Inter-agent messaging, threads, broadcast
CLI Orchestrator	4 MCP tools	Multi-CLI routing (Claude/Gemini/Codex) with circuit breaker
Context7	2 MCP tools	Live framework and library documentation
SDD Workflow	19 skills	Full 9-phase Spec-Driven Development with orchestrator
Conventions	-	Shared cortex conventions and memory protocol

Supported Agents

Agent	MCP Strategy	Task Delegation	Sub-Agents	Slash Commands
Claude Code	Separate JSON files	Yes (Task tool)	-	-
OpenCode	Merge into settings	Yes (task tool)	Yes	Yes
Gemini CLI	Merge into settings	-	-	-
Cursor	MCP config file	-	Yes (agents/)	-
VS Code Copilot	MCP config file	Yes	-	-
Codex	TOML file	-	-	-
Windsurf	MCP config file	-	-	-
Antigravity	MCP config file	-	-	-

Presets

Preset	Components
full	All 8 components (default)
minimal	Cortex + ForgeSpec + Context7 + SDD (auto-pulls Mailbox via deps)
custom	Select via TUI

SDD Pipeline

init → explore → propose → spec → design → tasks → apply → verify → archive

19 specialized skills handle each phase. Agents with task delegation (Claude Code, OpenCode) get a multi-agent orchestrator that delegates to sub-agents. Other agents get a single-agent prompt that executes phases sequentially.

Modern Prompting Techniques

Skills incorporate research-backed techniques:

• Chain-of-Verification — validate skill self-verifies claims before output
• Constitutional Self-Critique — implement skill critiques code against specs before submitting
• Skeleton-of-Thought — proposal/spec skills outline before expanding
• Extended Thinking — architect/decompose skills reason through alternatives explicitly
• ReAct — debug skill follows Thought/Action/Observation loops
• Inline WHY — every rule includes its motivation for better compliance

Architecture

cortex-ia/
├── cmd/cortex-ia/         # CLI entry point
├── internal/
│   ├── app/               # CLI dispatch + TUI launch
│   ├── model/             # Type definitions (agents, components, strategies)
│   ├── agents/            # 8 agent adapters (Claude, OpenCode, Gemini, etc.)
│   ├── catalog/           # Component definitions, presets, dependency resolution
│   ├── components/
│   │   ├── mcpinject/     # Shared MCP injection engine (4 strategies)
│   │   ├── cortex/        # Cortex MCP config templates
│   │   ├── orchestrator/  # CLI Orchestrator MCP config
│   │   ├── mailbox/       # Agent Mailbox MCP config
│   │   ├── forgespec/     # ForgeSpec MCP config
│   │   ├── context7/      # Context7 MCP config
│   │   ├── sdd/           # SDD workflow injection (orchestrator + skills + commands)
│   │   ├── skills/        # Non-SDD skill injection
│   │   ├── conventions/   # Cortex convention + protocol injection
│   │   └── filemerge/     # Marker-based injection, JSON merge, TOML, atomic write
│   ├── assets/            # Embedded content (go:embed)
│   │   ├── skills/        # 19 SDD skills + shared conventions
│   │   ├── generic/       # Orchestrator prompts + cortex protocol
│   │   └── opencode/      # Slash commands
│   ├── pipeline/          # 2-stage install pipeline with rollback
│   ├── backup/            # File snapshot + manifest + restore
│   ├── state/             # Installation state persistence
│   ├── system/            # OS/platform detection
│   └── tui/               # Interactive Bubbletea installer
└── go.mod

Key Design Decisions

• Non-destructive injection: Uses <!-- cortex-ia:ID --> markers. Content outside markers is never touched.
• Backup-first: Automatic snapshot before every install with restore capability.
• Adapter pattern: Each agent implements an interface. Adding a new agent requires zero changes to component code.
• Strategy dispatch: MCP injection is template-based (ServerTemplates struct) — adding a new MCP server is trivial.
• Idempotent: Running install twice produces identical results with no file changes.

Prerequisites

• Go 1.22+ (for building cortex-ia)
• Node.js 18+ with npx (for npm-based MCP servers)
• Cortex binary (go install github.com/lleontor705/cortex/cmd/cortex@latest)
• At least one supported AI agent installed

Commands

cortex-ia                  Interactive TUI installer
cortex-ia install          Install ecosystem (auto-detect agents, full preset)
cortex-ia install --agent claude-code --preset minimal
cortex-ia install --dry-run
cortex-ia detect           Show detected agents and system info
cortex-ia version          Show version
cortex-ia help             Show usage

Related Projects

• cortex — Persistent memory MCP server
• forgespec-mcp — SDD contracts + task board
• agent-mailbox-mcp — Inter-agent messaging
• cli-orchestrator-mcp — Multi-CLI routing

License

MIT