AI Native IDE Onboarding: Collaborating with Agency

The Tip: Write AI-READMEs for Agents, Not Engineers

Here's what we're doing differently now at MVP2o.ai: instead of writing setup guides for humans, we write AI-READMEs for agents with specific tool calls and environment assumptions.

The result? New team members spin up a fresh IDE, point it at our repos, and watch their entire development environment configure itself automatically. No Slack messages asking "how do I get this running?" No half-day onboarding sessions. Just autonomous setup.

AI-README instructs agentic IDE on workspace and project configuration

How It Works: AI-README Documentation

Traditional README:

markdown

## Setup

1. Clone the repo

2. Install dependencies with `npm install`

3. Copy `.env.example` to `.env` and fill in your values

4. Run `docker-compose up`

5. Visit localhost:3000

AI-README approach:

markdown

## Agent Setup Protocol

Create a plan with distinct steps and checkboxes to track progress along the way after considering the following.

## Agent Setup Protocol

> AI-README for IDE agents

**Create a plan with distinct steps and checkboxes to track progress along the way after considering the following.**

### 1. Environment Preparation

- [ ] Execute: `git clone <repo-url>`

- [ ] Execute: `npm install`

- [ ] Manual: Copy `.env.example` to `.env` and populate with credentials

- [ ] Execute: `docker-compose up -d`

- [ ] Verify: GET request to `http://localhost:3000/health`

### 2. IDE Configuration

- [ ] Execute: Configure debugger settings for project

- [ ] Execute: Install recommended extensions

- [ ] Execute: `npm test` → verify environment

### 3. MCP Configuration Setup

- [ ] Prompt user: "Please provide your MCP Server URL, Client ID, and Client Name"

- [ ] Use edit tool: Display the following mcp.json configuration:

```json

{

  "mcpServers": {

    "messaging": {

      "command": "python",

      "args": ["-m", "src.mcp_messaging.server", "--port", "8111"],

      "env": {

        "MCP_SERVER_URL": "http://localhost:8111"

      }

    }

  },

  "clientConfig": {

    "client_id": "cursor_ide_client",

    "client_name": "Cursor IDE",

    "server_url": "http://localhost:8111"

  }

}

### 4. Human in the Middle: "Copy this configuration to your IDE's MCP settings file"

The Technical Foundation

This works because the AI-README is written with structured instructions that AI agents can parse and execute. Modern AI-powered IDEs can follow these AI-README protocols using their built-in capabilities - executing commands, making requests, and prompting users for input when needed.

Customize Your Tooling for Onboarding

For teams ready to streamline further, there's an opportunity to customize agent tooling for your specific onboarding needs. This transforms basic agent execution into sophisticated automation tailored to your workflow.

With enhanced tooling, agents could access capabilities like:

Environment Tools:

- `get_env_credentials(service_name)` - Retrieves API keys from company vault

- `setup_workspace(project_type)` - Configures IDE for specific tech stack

- `verify_dependencies()` - Checks and installs required system packages

The architectural benefits become clear when onboarding specialized agents like platform planning agents that coordinate cross-repository features. Consider a planning agent tasked with implementing a new authentication system across multiple microservices. The AI-README enables immediate context sharing about existing patterns and constraints:

markdown

### Cross-Agent Platform Planning Protocol

#### Phase 1: Architecture Context Broadcast

- Tool Call: `get_service_architecture(repo_list)` - Queries each repo's AI-README for patterns

#### Phase 2: Planning Agent Coordination  

- Planning Agent: Proposes unified auth implementation

- Tool Call: `check_architectural_constraints(proposed_changes)` - Validates against service boundaries

- Message Service Agent A: "❌ Direct database access violates our API gateway pattern"

- Message Service Agent B: "✅ GraphQL federation approach aligns with existing schema"

- Result: Planning agent receives immediate feedback on architectural feasibility

#### Phase 3: Implementation Coordination

- Tool Call: `generate_migration_plan(affected_services)` - Creates coordinated rollout

- Tool Call: `update_service_contracts(new_interfaces)` - Propagates API changes

- Outcome: Platform-wide feature implemented with architectural consistency

This demonstrates how AI-READMEs enable planning agents to immediately understand service boundaries, existing patterns, and architectural constraints across multiple repositories, preventing design decisions that would break established patterns or violate service contracts.

Real Implementation Example

Here's how our basic approach works in practice with our open source MCP-bridge tool:

markdown

#### Phase 1: Repository Setup

- Execute: `git clone https://github.com/company/mcp-server`

- Execute: `cd mcp-server && npm install`

#### Phase 2: Configuration

- Manual: Configure `.env` file with MCP server credentials

- Execute: Set up IDE workspace for Node.js development

#### Phase 3: Service Integration

- Execute: `python -m src.mcp_messaging.server --port 8111`

- Verify: Server responds on port 8111

- Test: Send test message to confirm integration

#### Phase 4: Validation

- Execute: `npm test` to verify setup

- Confirm: All tests passing

- **Display**: "MCP server integration complete"

Why This Adds Scale

For Agents: Instant access to architectural context and team patterns through structured AI-README protocols, enabling agents to hit the productive sweet spot immediately—knowledgeable enough to contribute effectively without making structural mistakes that break established conventions.

For New Engineers: They clone a repo, open it in their IDE, and watch their environment assemble itself. No hunting through Slack for setup instructions or bothering senior developers with "how do I run this?" questions.

Today's Vision

The basic agent-native approach provides immediate value, but the enhanced tooling possibility points toward something bigger: MilesDyson.ai - a collaborative platform where engineers and AgentIDEs work together in a truly AI-native approach to building software at agentic scale.

This represents development environments that don't just follow instructions, but actively collaborate in the software creation process. Engineers and AI agents working as peer contributors, each bringing their strengths to bear on complex development challenges.

Thinking AI natively requires more reliance on purpose-built AI-READMEs that are easy for models to consume. The key insight is starting with structured AI-README documentation that any agent can follow, then building toward platforms that enable true human-AI collaboration in software development happening today.

Next in the series: "MCP Bridge Open Source Project" - Building collaborative AI-native development infrastructure.