Agent Boost — Core Analyzer, Plugin System, Reasoning Agent, and MCP Server

[joshmanders]

Vision

Agent Boost is a CLI that analyzes a repository and produces a high-signal AGENTS.md file that captures how the project is designed, how dependencies are used, and how new features should be built. This document acts as a durable knowledge base for future AI coding agents, enabling them to work as if they were written by the original author of the codebase.

Separately, Agent Boost can run as an MCP server, exposing tools registered by the core system and plugins so external agent systems can interact with the repository using the information described in AGENTS.md.

---

Problem Statement

AI coding agents lack project-specific context and default to generic assumptions. Existing documentation is often incomplete, outdated, or not structured in a way that agents can reliably consume.

Agent Boost solves this by:

• Performing core repository analysis (structure, dependencies, patterns, git history)
• Allowing plugins to enrich that understanding for specific dependencies or frameworks
• Organizing all gathered context into well-defined conceptual sections
• Building structured instructions from that context
• Using a dedicated Reasoning Agent to generate a complete, authoritative AGENTS.md

The MCP server is not part of the reasoning loop; it is a runtime surface for other agent systems.

---

Primary Outcomes

• Users can generate or update an AGENTS.md file that accurately reflects the real design of their project.
• AGENTS.md clearly documents what tools and capabilities are available via the Agent Boost MCP server.
• External agent systems that understand MCP can interact with the repository in a structured way.
• The system is extensible via plugins without requiring core changes.
• Destructive actions are explicit, predictable, and safe.

---

CLI Commands & Routing Rules

Root Command

• npx agentboost
  • If AGENTS.md does not exist → behaves like init
  • If AGENTS.md exists → behaves like update

Explicit Commands

• npx agentboost init

  • Generates AGENTS.md
  • If AGENTS.md already exists:
    • Prompt user for overwrite confirmation (Y/n)
    • Abort if declined

• npx agentboost update

  • Uses the existing AGENTS.md as contextual input
  • Fully rewrites AGENTS.md
  • Clearly informs the user that overwrite will occur

• npx agentboost auth

  • Stores OpenAI API credentials
  • Optional; init / update prompt if missing

• npx agentboost mcp

  • Loads core and all plugins
  • Exposes core tools and plugin-registered tools via an MCP server
  • Intended for use by external agent systems that understand MCP

---

Core System Responsibilities (Heavy Lifting)

The core system is responsible for:

• Repository scanning and structure discovery
• Dependency inventory (Node.js root dependencies only in v1)
• Git history analysis when present
• Normalizing and deduplicating all discovered signals
• Assembling a canonical context package
• Organizing context into conceptual section buckets
• Building structured instructions for the Reasoning Agent
• Enforcing overwrite semantics and safety checks
• Writing AGENTS.md to disk after successful Agent finalization
• Plugin discovery, loading, registration, and lifecycle orchestration
• MCP server lifecycle and tool exposure
• LLM provider abstraction (OpenAI only in v1)

Core must be able to produce a valuable AGENTS.md even with zero third-party plugins installed.

---

Foundational Requirement: Sections & Plugin Context APIs (First Step)

Before downstream implementation can proceed, the system must define:

1) Conceptual Section Model

A stable, internal model of conceptual sections that represent the types of knowledge AGENTS.md may contain.

Key properties:

• Sections are conceptual, not hard-coded markdown headings.
• They represent kinds of knowledge (e.g., architecture, dependencies, conventions, tooling).
• The Reasoning Agent decides how these sections are rendered, merged, split, or ordered in the final document.
• Core and plugins both target this model when contributing context.

This section model is foundational and must be defined before:

• Plugin APIs are finalized
• Instruction building is implemented
• Agent prompting is designed

2) Plugin Context Contribution APIs

A clear, explicit API surface that plugins use to:

• Contribute structured context fragments
• Declare what conceptual section(s) that context belongs to
• Optionally augment or refine context discovered by core
• Avoid writing prose or final markdown directly

These APIs define:

• What plugins are allowed to contribute
• How contributions are categorized
• How core safely aggregates, normalizes, and deduplicates plugin input

This API is the primary extension point for Agent Boost and must be:

• Stable
• Composable
• Testable
• Independent of the Reasoning Agent’s implementation details

---

Plugin System

Plugin Purpose

Plugins exist to enrich the core understanding of a repository and/or to register tools for use via the MCP server.

Examples:

• Framework-specific context (e.g., Tailwind usage patterns)
• Dependency-specific best practices as applied in this repo
• Domain-specific tools exposed via MCP

Plugins do not write files and do not generate final prose.

Plugin Discovery (v1 Scope)

• Only root / top-level Node dependencies are considered.
• Discovery starts from the project’s root package.json.
• A dependency is treated as an Agent Boost plugin if it declares an Agent Boost plugin entry.
• Transitive dependencies are not scanned.
• Built-in/core plugins shipped with Agent Boost are also loaded.

Plugin Loading & Registration

• Agent Boost has a loading phase that produces the final plugin set.
• During loading, plugins may register additional plugins using a core-provided API.
• Registered plugins are treated the same as discovered plugins.
• There is no special “preset” concept; presets are simply plugins that register other plugins.
• Plugins identify themselves by a name (e.g., tailwind).
• Where or how a plugin was registered is irrelevant after loading.

Deterministic behavior must exist for:

• Duplicate plugin names
• Registration chains (plugin A registers B, B registers C)
• Multiple registrations of the same plugin

Plugin Capabilities

Plugins may:

• Contribute structured context fragments via the defined APIs
• Register MCP tools
• Register additional plugins during the loading phase

Plugins use only helpers and capabilities exposed by core and do not replicate core scanning logic.

---

Context Assembly & Instruction Building

• Core and plugins emit structured context fragments.
• Core aggregates fragments into conceptual section buckets.
• Core builds structured instructions for the Reasoning Agent from those buckets.
• Instructions encode:
  • The “textbook author” framing
  • Rewrite rules
  • Update semantics
  • Available MCP tools (for documentation only)

---

The Reasoning Agent (AGENTS.md Composer)

Role

The Reasoning Agent composes the AGENTS.md document. It consumes structured instructions built from core and plugin context and produces a complete Markdown document intended to teach future agents how this repository works and how it should be extended.

The Reasoning Agent:

• Does not interact with the MCP server
• Does not write files
• Does not perform repository analysis

Mental Model

The Agent acts like a textbook author:

• Prioritizes what matters
• Explains how things work and why
• Is declarative and instructional
• Is allowed to be opinionated when evidence exists

---

Agent Output & Finalization

The Agent produces the complete AGENTS.md as Markdown and signals completion by calling a single tool named finalize.

finalize Tool Contract

• Accepts a single argument: the full Markdown contents
• Does not accept filenames or options
• May be called only once per run
• In v1, finalize is the only tool available to the Reasoning Agent

Core Validation on Finalize

Core must validate:

• Contents are non-empty
• Contents include at least one Markdown header
• Contents are entirely Markdown

If validation fails:

• Abort the run
• Do not write anything
• Explain the failure
• Instruct the user to retry

If validation succeeds:

• Apply overwrite rules
• Perform a full rewrite of AGENTS.md
• Report success

---

MCP Server

• npx agentboost mcp runs a local MCP server.
• Core and plugins register tools exposed via MCP.
• The set of exposed tools is described in AGENTS.md.
• External agent systems that understand MCP can use these tools.
• The Reasoning Agent itself does not call MCP tools.

---

Testing Posture

Automated tests assert only that:

• The Reasoning Agent was invoked
• The finalize tool was called
• AGENTS.md was written successfully (or not written on failure)

Tests do not assert:

• Document structure
• Content correctness
• Specific sections or wording

---

Out of Scope (for this Epic)

• IDE/editor integrations
• Non-OpenAI provider implementations
• Non-Node plugin discovery implementations

---

Success Criteria

• Running agentboost reliably generates or updates a high-quality AGENTS.md.
• Output is stable and coherent for a given repo state.
• Core works without plugins.
• Plugins can safely enrich context or MCP tooling without core changes.
• MCP server exposes meaningful, repo-aware tools.
• Future AI agents can build features using AGENTS.md with minimal guesswork.