🤖 AgentRules Architect
<div align="center">
Multi-provider repository analysis, agent rules generation, and ExecPlan tooling.
Demo • Highlights • Features • Requirements • • • • • • •
</div>
AGENTS.md/CLAUDE.md generator and ExecPlan harness for Codex, Claude Code, Cursor, Antigravity, OpenCode, Pi and other coding agents. Use api keys or authenticate with Codex or Claude Code
Multi-provider repository analysis, agent rules generation, and ExecPlan tooling.
Demo • Highlights • Features • Requirements • • • • • • •
</div>
AgentRules Architect analyzes a repository, coordinates specialized model-backed architects, and writes durable rules artifacts such as AGENTS.md or a custom rules filename like CLAUDE.md. It is built around a six-phase pipeline, a Rich/Typer CLI, persistent TOML configuration, provider-specific request adapters, local runtime integrations, and optional planning artifacts for longer agent-led work.
python -m agentrules entry points.agentrules launches a guided main menu, while subcommands cover analysis, configuration, keys, snapshots, ExecPlans, scaffolds, and tree previews.~/.config/agentrules/config.toml (override with AGENTRULES_CONFIG_DIR).ToolManager adapts canonical JSON tool schemas for each provider; Tavily web search is available to researcher agents with one toggle.AGENTS.md, SNAPSHOT.md (enabled by default), .cursorignore, optional .agent/ scaffold templates, and per-phase markdown/json snapshots.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.
core/analysis/phase_1.py) inventories the repo tree, surfaces tech stack signals, and collects dependency metadata that later phases reuse.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).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.core/analysis/phase_4.py) stitches together Phase 3 findings, elevates cross-cutting insights, and flags follow-up prompts for the final steps.core/analysis/phase_5.py) produces a canonical report object that downstream tooling (rules generator, metrics, exporters) consumes.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.
src/agentrules/config/agents.py.pyproject.toml.pytest, Ruff, and Pyright.pip install -U agentrules
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
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
Run the interactive configurator to store credentials securely:
agentrules configure
~/.config/agentrules/config.toml (override with AGENTRULES_CONFIG_DIR).agentrules configure --provider openai for quick single-key updates.agentrules keys
AgentRules supports local runtime providers separately from API-key providers.
agentrules -> Settings -> Codex runtimecodex by default)CODEX_HOME strategy (managed or inherit)Sign in with ChatGPT to authenticate runtime-backed model access.agentrules -> Settings -> Claude Code runtimeclaude executable pathAfter runtime setup, choose Codex or Claude Code presets under Settings -> Model presets per phase.
See docs/codex-runtime.md and docs/claude-code-runtime.md for setup, auth flow, model catalog behavior, and live smoke instructions.
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 Phase 1 → Researcher entry lets you toggle the agent On/Off once a Tavily key is configured.agentrules configure --outputs – toggle .cursorignore, .agent/ scaffold generation, phases_output/, and custom rules filename.agentrules configure --logging – set verbosity (quiet, standard, verbose) or export via AGENTRULES_LOG_LEVEL.agentrules tree [path] – preview the exclusion-aware project tree and optionally save it.ExecPlans are long-horizon execution artifacts for work that is too large for a single prompt/session and too risky to run as ad hoc edits. They give humans and agents a durable plan, explicit scope, and audit trail that can survive context switching across days or weeks.
This follows the same general planning pattern used for larger Codex work: start with an implementation plan, then execute it iteratively in smaller scoped chunks (see OpenAI Codex docs and How OpenAI uses Codex).
Think of the model in three layers:
MS001, MS002, ...) and independently completable.Why this exists:
ExecPlans and milestones use canonical IDs and deterministic file locations:
EP-YYYYMMDD-NNNEP-YYYYMMDD-NNN/MS###.agent/exec_plans/active/<plan-slug>/EP-YYYYMMDD-NNN_<plan-slug>.md.agent/exec_plans/complete/YYYY/MM/DD/EP-YYYYMMDD-NNN_<plan-slug>/EP-YYYYMMDD-NNN_<plan-slug>.md.agent/exec_plans/active/<plan-slug>/milestones/active/MS###_<milestone-slug>.md.agent/exec_plans/active/<plan-slug>/milestones/complete/MS###_<milestone-slug>.mdMilestone creation is parent-first and sequence-safe:
MS### automatically, or accept --ms N to request a specific sequence.MS001, MS002, ...)..agent/templates/MILESTONE_TEMPLATE.md is a guidance scaffold for authors.
Generated milestone files come from an internal file template used by execplan milestone new.Examples:
# 1) Create an ExecPlan
agentrules execplan new "Auth Refresh" --date 20260207
# 2) Create milestones for that plan (auto-assigns MS001, then MS002, ...)
agentrules execplan milestone new EP-20260207-001 "Design callback flow"
agentrules execplan milestone new EP-20260207-001 "Implement callback flow"
# Optional: request an explicit sequence (must be unused)
agentrules execplan milestone new EP-20260207-001 "Backfill docs" --ms 5
# 3) List milestones (all or active-only)
agentrules execplan milestone list EP-20260207-001
agentrules execplan milestone list EP-20260207-001 --active-only
# Optional: compact "what's left" view for active milestones only
agentrules execplan milestone remaining EP-20260207-001
# 4) Complete a finished milestone
agentrules execplan milestone complete EP-20260207-001 --ms 1
# 5) Complete the ExecPlan directory
agentrules execplan complete EP-20260207-001 --date 20260212
# Optional: list all active plans with compact milestone progress
agentrules execplan list
~/.config/agentrules/config.toml
providers – API keys per provider.codex – local runtime settings (cli_path, home_strategy, managed_home).claude_code – Claude Code SDK runtime settings, request limits, and environment sanitization preferences.models – preset IDs applied to each phase (phase1, phase2, final, researcher, …).outputs – generate_cursorignore, generate_agent_scaffold, generate_phase_outputs, generate_snapshot, rules_filename, snapshot_filename.
generate_snapshot defaults to true and writes SNAPSHOT.md at project root after each analysis run (toggle anytime in agentrules configure --outputs).features – researcher_mode (on/off) to control Phase 1 web research (managed from the Researcher row in the models wizard).exclusions – add/remove directories, files, or extensions; choose to respect .gitignore.agentrules/core/configuration/manager.py):
ConfigManager.get_effective_exclusions() resolves overrides with defaults from config/exclusions.py.ConfigManager.should_generate_phase_outputs() and related methods toggle output writers in core/utils/file_creation.AGENTRULES_CONFIG_DIR – alternate config root.AGENTRULES_LOG_LEVEL – overrides persisted verbosity.AGENTRULES_RULES_FILENAME – runtime override for generated rules filename (for example CLAUDE.md).CODEX_HOME – used when Codex home_strategy = "inherit".CLAUDE_CODE_OAUTH_TOKEN – optional Claude Code automation token for environments that cannot use an interactive login.agentrules analyze --rules-filename <name>AGENTRULES_RULES_FILENAMEoutputs.rules_filename in config.toml (set via agentrules configure --outputs)AGENTS.md defaultPresets live in config/agents.py via the MODEL_PRESETS dictionary. Each preset bundles:
ModelProvider)The app currently exposes presets across these providers:
Choose any available preset per phase through the CLI (agentrules configure --models) or by editing config.toml / config/agents.py. At runtime the values populate MODEL_CONFIG, which the pipeline consumes while resolving phase architects (src/agentrules/core/agents/factory/factory.py).
Preset tip: Preset keys are compatibility IDs, not release markers. Static presets live in
config/agents.py, while Codex runtime selections in the settings UI are discovered from the live app-server catalog.
src/agentrules/core/types/models.py).codex app-server, with runtime-discovered model/effort variants available from the live model catalog. Claude Code presets route phases through the Claude Agent SDK while preserving Claude Code's runtime behavior.core/analysis/phase_2.py, core/analysis/phase_3.py).create_researcher_config enables Tavily-backed tool use for whichever preset you promote to the Researcher role, and the CLI’s Researcher row simply flips that on/off (core/types/models.py, config/tools.py).src/agentrules/config/prompts/—heavy modifications should stay aligned with the YAML/XML formats expected by the parser utilities.MODEL_PRESETS/MODEL_PRESET_DEFAULTS in config/agents.py; the configuration manager merges those with TOML overrides at runtime.core/agent_tools/tool_manager.py normalizes JSON tool schemas for each provider.config/tools.py exposes TOOL_SETS and a with_tools_enabled helper for models that accept function/tool calls.tavily_web_search) ships as the default researcher tool. Add TAVILY_API_KEY in the provider settings to automatically enable the Researcher agent, then pick the model (or flip it back Off) from the models wizard’s Researcher entry. When disabled—or when no key is present—documentation research is skipped; our contributor smoke tests use deterministic stubs to keep CI free of external calls. The dependency agent automatically downgrades from “knowledge gaps” mode to its legacy full catalog so downstream agents still receive usable dependency data when research is unavailable.agentrules/ – Typer CLI, interactive Questionary flows, Rich UI, configuration services, and pipeline runner (agentrules/SNAPSHOT.md).core/ – provider-specific architects (core/agents), analysis phases (core/analysis), tool adapters (core/agent_tools), streaming primitives, and filesystem utilities (core/SNAPSHOT.md).config/ – preset definitions, exclusions, prompts, and tool bindings (config/SNAPSHOT.md).tests/ – live smoke tests, deterministic offline stubs for CI, provider fixtures, and unit coverage for helpers and phases.pyproject.toml – package metadata, scripts, Ruff/Pyright config, and dependency declarations.By default the pipeline produces:
AGENTS.md (or your custom rules filename) – cleaned, standardized agent instructions.SNAPSHOT.md – full project tree snapshot (no depth limit by default) generated at the project root after the pipeline finishes..cursorignore – generated when enabled to keep editor agents focused on relevant files..agent/ scaffold – generated when enabled (.agent/PLANS.md and .agent/templates/MILESTONE_TEMPLATE.md).phases_output/ – per-phase markdown/JSON snapshots for auditing and downstream automation.docs/examples/phases_output/ for a full run’s phase artifacts.Toggle outputs with agentrules configure --outputs or via the config TOML.
pip install -e ".[dev]"ruff format . && ruff check .pyrightpython tests/phase_3_test/run_test.pyagentrules analyze --offline tests/tests_inputpytestmain update/open a release PR, and merging that PR creates the vX.Y.Z tag + GitHub release automatically..github/workflows/publish-pypi.yml (no long-lived PyPI API token).workflow_dispatch and repository = testpypi; publish to production PyPI on release-tag push or manual repository = pypi.config/agents.py, config/tools.py, core/agents/*).main using Conventional Commit-style titles/messages (for example feat: ..., fix: ...)..github/workflows/release-please.yml updates or opens a release PR with the version bump and changelog..github/workflows/publish-pypi.yml manually with repository = testpypi from the release PR head commit.vX.Y.Z tag and publishes a GitHub release..github/workflows/publish-pypi.yml to publish to production PyPI.RELEASE_PLEASE_TOKEN (PAT or GitHub App token) with permission to create/update PRs, tags, and releases. This ensures tag pushes from Release Please trigger downstream workflows.trevor-nichols/agentrules-architect, workflow .github/workflows/publish-pypi.yml, and environments testpypi/pypi.See CONTRIBUTING.md for detailed guidelines on workflows, testing, and pull request expectations. Issues and PRs are welcome—just ensure Ruff/Pyright/tests pass before submitting.
Released under the MIT License. See LICENSE for details.
Standard MoltPulse indexed agent.
Show off your Pulse Score in your GitHub README to build trust and rank higher.