🤖 AgentRules Architect v3

Your multi-provider AI code analysis and AGENTS.md generator 🚀

Demo • Highlights • Features • Requirements • Installation • Codex Runtime • CLI • Configuration • Architecture • Outputs • Development

🎥 CLI Demo

Why AgentRules Architect?

Version 3 rebrands the project from CursorRules Architect to AgentRules Architect to match the standardized AGENTS.md contract used across modern AI coding agents. The rename comes with a fresh Typer-powered CLI, a persistent configuration service, broader provider support across Anthropic, OpenAI, Google, DeepSeek, xAI, and the local Codex app-server runtime, and a tooling layer that keeps the six-phase analysis reliably consistent yet flexibly extensible to your project's unique needs.

🔥 v3 Highlights

• ✨ Rebrand & packaging – ships on PyPI with console-script and python -m agentrules entry points.
• 🧭 Typer CLI overhaul – agentrules launches an interactive main menu with subcommands for analyze, configure, and keys.
• 🗂️ Persistent settings – API keys, model presets, logging, and output preferences live in ~/.config/agentrules/config.toml (override with AGENTRULES_CONFIG_DIR).
• 🧠 Expanded provider matrix – the preset catalog spans Anthropic, OpenAI, Google, DeepSeek, xAI, and Codex runtime presets, with phase-by-phase model selection from the CLI or config file.
• 🧰 Codex runtime support – route phases through local codex app-server with ChatGPT auth via CODEX_HOME (no AgentRules-stored OpenAI API key required).
• 🔌 Unified tool management – the new ToolManager adapts JSON tool schemas for each provider; Tavily web search is available to researcher agents with one toggle.
• ✅ Test & quality backbone – 200+ unit/integration tests, Pyright, Ruff, and offline stubs provide confidence without hitting live APIs.

✨ Feature Overview

• 🌐 Multi-provider orchestration with consistent streaming telemetry.
• 🔍 Six-phase pipeline: discovery → planning → deep dives → synthesis → consolidation → final AGENTS.md generation.
• 🧩 Researcher tooling via Tavily search with provider-aware tool translation.
• 📊 Rich terminal UI (Rich) showing per-agent progress, duration, and failures in real time.
• 🪵 Configurable outputs: AGENTS.md, SNAPSHOT.md (enabled by default), .cursorignore, optional .agent/ scaffold templates, and per-phase markdown/json snapshots.
• 🔧 Declarative model presets plus runtime overrides via CLI or TOML.

🧮 Analysis Pipeline

All CLI entry points ultimately execute the AnalysisPipeline orchestrator (src/agentrules/core/pipeline) that wires the six analysis phases together and streams progress events to the Rich console.

1. Phase 1 – Initial Discovery (core/analysis/phase_1.py) inventories the repo tree, surfaces tech stack signals, and collects dependency metadata that later phases reuse.
2. Phase 2 – Methodical Planning (core/analysis/phase_2.py) asks the configured model to draft an XML-ish agent plan, then parses it into structured agent definitions (with a safe fallback extractor).
3. Phase 3 – Deep Analysis (core/analysis/phase_3.py) spins up specialized architects per agent definition, hydrates them with file excerpts, and runs them in parallel; if no plan exists it falls back to three default agents.
4. Phase 4 – Synthesis (core/analysis/phase_4.py) stitches together Phase 3 findings, elevates cross-cutting insights, and flags follow-up prompts for the final steps.
5. Phase 5 – Consolidation (core/analysis/phase_5.py) produces a canonical report object that downstream tooling (rules generator, metrics, exporters) consumes.
6. Final Analysis (core/analysis/final_analysis.py) produces the narrative summary that drives AGENTS.md, output toggles, and console highlights.

The pipeline captures metrics (elapsed time, agent counts) and hands them to the output writer so offline runs and full analyses share the same persistence path.

🛠 Requirements

• Python 3.11.9+ (matches Pyright target and packaged metadata).
• API key(s) for at least one provider:
  • Anthropic
  • OpenAI
  • DeepSeek
  • Google
  • xAI
  • Tavily (optional, enables live web search tooling)
• Optional local runtime provider:
  • Codex CLI (codex) for codex app-server integration
• Current preset IDs live in src/agentrules/config/agents.py.
• Core dependencies: anthropic, openai, google-genai>=1.51.0, tavily-python, tiktoken, rich, typer, questionary, platformdirs, pathspec, python-dotenv, protobuf.
• Dev tooling: pytest, pytest-asyncio, pytest-mock, flask, ruff, pyright.

📦 Installation

Install from PyPI

pip install -U agentrules

• Package page: https://pypi.org/project/agentrules/
• Test index page: https://test.pypi.org/project/agentrules/

Install from source

git clone https://github.com/trevor-nichols/agentrules-architect.git
cd agentrules-architect
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Need a one-liner? Use the helper script:

./scripts/bootstrap_env.sh           # set PYTHON_BIN=/abs/path/to/python to override interpreter

Quick smoke test

agentrules --version
agentrules analyze /path/to/project

Prefer module execution during development? Invoke the CLI with Python’s module flag—the package ships a __main__ entry point:

python -m agentrules analyze /path/to/project

Need to install directly from GitHub instead of PyPI?

pip install "git+https://github.com/trevor-nichols/agentrules-architect.git#egg=agentrules"

Need to validate against TestPyPI specifically?

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple agentrules==3.4.1

🔐 Configure API Keys

Run the interactive configurator to store credentials securely:

agentrules configure

• Keys are saved to ~/.config/agentrules/config.toml (override with AGENTRULES_CONFIG_DIR).
• Values are mirrored into environment variables on the next launch.
• Use agentrules configure --provider openai for quick single-key updates.
• Show current status with:

agentrules keys

🧰 Configure Codex Runtime (Optional)

AgentRules supports Codex as a local runtime provider via codex app-server, separate from API-key providers.

• Open agentrules -> Settings -> Codex runtime
• Configure:
  • executable path (codex by default)
  • CODEX_HOME strategy (managed or inherit)
  • optional managed home override
• Use Sign in with ChatGPT to authenticate runtime-backed model access.

After runtime setup, choose Codex presets under Settings -> Model presets per phase.

See docs/codex-runtime.md for complete setup, auth flow, model catalog behavior, and live smoke instructions.

🧭 CLI At A Glance

• agentrules – interactive main menu (analyze, configure models/outputs, check keys).
• agentrules analyze /path/to/project – full six-phase analysis.
• agentrules analyze /path/to/project --rules-filename CLAUDE.md – one-run override for output rules filename.
• agentrules snapshot generate [path] – create (or refresh) SNAPSHOT.md in the current directory by default.
• agentrules snapshot sync [path] – sync an existing snapshot as project files evolve (also creates if missing).
• agentrules execplan new \"Title\" – create a new ExecPlan markdown file under .agent/exec_plans/active/<slug>/.
• agentrules execplan complete EP-YYYYMMDD-NNN [--date YYYYMMDD] – move a full ExecPlan directory under .agent/exec_plans/complete/YYYY/MM/DD/EP-YYYYMMDD-NNN_<slug>/.
• agentrules execplan list [--path] – list active ExecPlans with compact milestone progress (completed/total).
• agentrules execplan milestone new EP-YYYYMMDD-NNN \"Title\" [--ms N] – create a milestone under a specific ExecPlan (auto sequence by default, or explicit MS### when provided).
• agentrules execplan milestone list EP-YYYYMMDD-NNN [--active-only] – list milestones for one ExecPlan.
• agentrules execplan milestone complete EP-YYYYMMDD-NNN --ms <N> – move an active milestone sequence into the milestones/complete/ directory.
• agentrules execplan milestone remaining EP-YYYYMMDD-NNN [--path] – show active milestones left for one ExecPlan.
• agentrules execplan-registry [build|check|update] – manage .agent/exec_plans/registry.json from ExecPlan front matter.
• agentrules scaffold sync [--check|--force] – sync .agent/PLANS.md and .agent/templates/MILESTONE_TEMPLATE.md with packaged defaults.
• agentrules configure --models – assign presets per phase with guided prompts; the Ph