Intelligent Code Agents (ICA)

Portable, skills-first agent workflow (roles, reviewer gates, work queue, and installers) designed to run across multiple agent runtimes and IDEs.

What You Get

• Skills-first architecture (SKILL.md) for roles like PM/Architect/Developer/Reviewer, plus workflow/enforcement companions.
• A reproducible PR gate: post-PR Stage 3 review receipt (ICA-REVIEW-RECEIPT) for the current head SHA.
• Cross-tool work tracking via .agent/queue/ (created/managed by the work-queue skill).
• Optional Claude Code integration: minimal PreToolUse hooks (infra protection + summary/file hygiene), plus optional MCP server wiring.

Supported Targets

ICA installs into a tool-specific "agent home" directory:

• Claude Code: ~/.claude (default)
• Codex: ~/.codex (default)
• Cursor / Gemini CLI / Antigravity: supported via AGENT_DIR_NAME mapping, plus AGENTS.md guidance (tool-specific wiring varies).

Best-effort discovery (local):

• macOS/Linux: make discover-targets and make install-discovered
• Windows: .\install.ps1 discover and .\install.ps1 install-discovered

Override discovery if needed:

• ICA_DISCOVER_TARGETS=claude,codex (explicit list)
• ICA_DISCOVER_ALL=1 (all supported targets)

Set ICA_HOME to your chosen agent home directory if you run ICA scripts/hooks outside Claude Code:

export ICA_HOME="$HOME/.claude"   # or "$HOME/.codex"

Install

macOS/Linux (Ansible-driven):

git clone https://github.com/intelligentcode-ai/intelligent-code-agents.git
cd intelligent-code-agents

make install AGENT=claude   # installs into ~/.claude
make install AGENT=codex    # installs into ~/.codex

# Keep ICA strictly platform-agnostic (no Claude Code modes/hooks/settings/CLAUDE.md changes)
make install AGENT=claude INSTALL_CLAUDE_INTEGRATION=false

# Project-only install (installs into /path/to/project/<agent_home_dir>)
make install-project PROJECT_PATH=/path/to/project AGENT=codex

Windows (PowerShell):

git clone https://github.com/intelligentcode-ai/intelligent-code-agents.git
cd intelligent-code-agents

.\install.ps1 install -Agent claude
.\install.ps1 install -Agent codex

# Keep ICA strictly platform-agnostic (no Claude Code modes/hooks/settings/CLAUDE.md changes)
.\install.ps1 install -Agent claude -InstallClaudeIntegration $false

# Best-effort discovery
.\install.ps1 discover
.\install.ps1 install-discovered

# Project-only install
.\install.ps1 install -ProjectPath C:\MyProject -Agent codex

Override the agent home directory name (advanced):

make install AGENT=custom AGENT_DIR_NAME=.my-agent-home

Using ICA

Use skills by name and keep prompts explicit about the intent and output.

pm break down the story into work items in .agent/queue/
architect review the approach and call out risks/tradeoffs
developer implement the change
reviewer audit for regressions and post an ICA-REVIEW-RECEIPT

Workflow Gate (PRs)

Default branch flow:

feature/*  -> PR -> dev  -> (release PR) -> main

Merge gate:

• A dedicated post-PR review run (temp checkout) must post ICA-REVIEW-RECEIPT.
• Receipt must match the PR's current head SHA and indicate PASS / NO FINDINGS.
• Checks/tests must be green.

Configuration

• ica.config.json: behavior/enforcement configuration (git privacy, branch protection, paths, etc.)
• ica.workflow.json: workflow automation controls (auto-merge standing approval, optional GitHub approval gate, release automation)

Reference defaults are shipped as:

• ica.config.default.json
• ica.workflow.default.json

Preferred project-local locations:

• ./.ica/config.json
• ./.ica/workflow.json

Docs

• AGENTS.md (how to consume ICA from different tools)
• docs/index.md (start here)

License

MIT (see LICENSE)