sf-agent-framework/docs/18-brownfield-development/README.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Working with Existing Projects (Brownfield)

## Overview

This guide provides a comprehensive approach to using the SF-Agent Framework in existing Salesforce projects (brownfield development). Brownfield projects present unique challenges, such as understanding legacy code, respecting existing patterns, and ensuring new features integrate seamlessly.

## The Brownfield Workflow

The recommended workflow for brownfield projects involves a documentation-first approach to ensure the AI agents have a thorough understanding of the existing system.

### Phase 1: System Documentation

The first and most critical step is to document the existing system. This provides the necessary context for the AI agents to make informed decisions.

**1. Analyze the Codebase:**
Use the `sf-agent` to analyze your existing codebase and generate documentation.

```bash
# Analyze the entire codebase and generate documentation
sf-agent task document-all
```

**Expected Output:**
A series of documentation files in the `docs` folder, including:

- `docs/codebase-analysis.md`: An overview of the codebase, including key metrics and dependencies.
- `docs/object-definitions/`: A directory containing documentation for each Salesforce object.
- `docs/apex-classes/`: A directory containing documentation for each Apex class.

**2. Generate Architecture Document:**
Create a comprehensive architecture document that covers all aspects of the system.

```bash
# Generate a full-stack architecture document
sf-agent task document-architecture --type full-stack
```

This will create a detailed `project-architecture.md` file in your `docs` folder.

### Phase 2: Planning the Enhancement

Once the existing system is documented, you can begin planning your enhancements.

**1. Create a Brownfield PRD:**
Use the `sf-product-manager` agent to create a Product Requirements Document (PRD) specifically for your enhancement.

```bash
# Start the brownfield PRD creation workflow
sf-agent workflow create-brownfield-prd
```

The agent will ask for details about your enhancement and use the existing documentation to identify affected areas and potential risks.

**2. Create a Brownfield Architecture:**
Use the `sf-architect` agent to create an architecture document for the new features, focusing on integration with the existing system.

```bash
# Start the brownfield architecture creation workflow
sf-agent workflow create-brownfield-architecture
```

### Phase 3: Development and Implementation

Once the planning is complete, you can move to the development phase.

**1. Shard the Documents:**
Shard the PRD and architecture documents to create focused context for the development agents.

```bash
# Shard the brownfield PRD
sf-agent shard docs/brownfield-prd.md

# Shard the brownfield architecture
sf-agent shard docs/brownfield-architecture.md
```

**2. Implement Stories:**
Follow the standard development workflow to implement the user stories.

```bash
# Get the next story
sf-agent story next

# Implement the story
sf-agent story implement STORY-ID
```

## Best Practices for Brownfield Development

- **Document First:** Always start by documenting the existing system. This is the most critical step for success.
- **Respect Existing Patterns:** The AI agents will try to follow existing coding conventions and architectural patterns. Make sure these are well-documented.
- **Plan for Gradual Rollout:** Use feature flags and other strategies to minimize the risk of introducing new features.
- **Focus on Integration Testing:** Thoroughly test the integration points between new and existing code.
- **Communicate Changes:** Clearly document what has changed and why.
- **Analyze Technical Debt:** Use the `identify-technical-debt` task to identify areas of your codebase that could be improved.
- **Get Refactoring Recommendations:** Use the `recommend-refactoring` task to get specific recommendations for how to improve your code.

## Common Brownfield Scenarios

- **Adding a New Feature:** Follow the full brownfield workflow to ensure the new feature is well-integrated.
- **Modernizing Legacy Code:** Use the framework to document the legacy code, then create a plan for modernization.
- **Bug Fixes in Complex Systems:** Document the relevant subsystems, then use the `create-brownfield-story` task to create a focused fix.
- **Analyzing Technical Debt:**
  ```bash
  # Identify technical debt in the codebase
  sf-agent task identify-technical-debt
  ```
- **Getting Refactoring Recommendations:**
  ```bash
  # Get refactoring recommendations for a specific Apex class
  sf-agent task recommend-refactoring --class "MyLegacyClass"
  ```