> ## Documentation Index
> Fetch the complete documentation index at: https://lab.pollack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipeline

> Three-phase orchestration: analyze a project, generate a plan, then execute with enriched context

## What the Pipeline Does

`PipelineAgentInvoker` wraps any `AgentInvoker` with two optional upstream phases — project analysis and plan generation — before delegating to the actual agent. Each phase enriches the execution context so the agent starts with a better understanding of the project.

```
Phase 1: Analyze          Phase 2: Plan            Phase 3: Execute
┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│  ProjectAnalyzer │───▶│   PlanGenerator  │───▶│  AgentInvoker    │
│  (deterministic) │    │  (may use LLM)   │    │  (delegate)      │
└──────────────────┘    └──────────────────┘    └──────────────────┘
     optional                optional               required
```

All phases are optional except execution. If analysis or planning fails, the pipeline logs a warning and continues — the agent runs with whatever context is available.

## PipelineConfig

```java theme={null}
PipelineConfig config = PipelineConfig.builder()
    .enableAnalysis(true)                              // Toggle analysis phase
    .enablePlanning(true)                              // Toggle planning phase
    .knowledgeDir(Path.of("kb"))                       // KB root for planning
    .toolPaths(Map.of("pom-upgrader", toolJar))        // Available tools
    .targetBootVersion("3.4.1")                        // Migration target
    .targetJavaVersion("21")                           // Java target
    .planningModel("sonnet")                           // Model for planning
    .planningTimeout(Duration.ofMinutes(5))             // Planning timeout
    .build();
```

| Field | Required | Default | Description |
| - | - | - | - |
| `enableAnalysis` | No | `true` | Run the analysis phase |
| `enablePlanning` | No | `true` | Run the planning phase |
| `knowledgeDir` | No | — | KB root for plan generation |
| `toolPaths` | No | — | Map of tool name to JAR path |
| `targetBootVersion` | No | — | Target Spring Boot version |
| `targetJavaVersion` | No | — | Target Java version |
| `planningModel` | No | — | Model for plan generation |
| `planningTimeout` | No | 5 min | Timeout for planning phase |

## Phase 1: Project Analysis

`ProjectAnalyzer` performs deterministic, read-only analysis of the workspace. No AI calls, no side effects.

```java theme={null}
public interface ProjectAnalyzer {
    AnalysisEnvelope analyze(Path workspace, AnalysisConfig config);
}
```

### PomAnalyzer

The default implementation scans Maven POM files and Java source:

| What it extracts | Source |
| - | - |
| Project identity | POM `<name>` or `<artifactId>` |
| Spring Boot version | Parent POM or dependency management |
| Java version | `java.version` or `maven.compiler.source` property |
| Dependencies | Direct `<dependencies>` (groupId:artifactId → version) |
| Modules | `<modules>` for multi-module projects |
| Import patterns | `javax.*` imports grouped by namespace |
| Annotations | Tracked Spring/JPA annotations with file locations |
| Config files | `application.properties`, `application.yml` in resources |

```java theme={null}
AnalysisConfig config = AnalysisConfig.pomOnly("3.4.1", "21");
AnalysisEnvelope envelope = new PomAnalyzer().analyze(workspace, config);

envelope.projectName();     // "my-service"
envelope.bootVersion();     // "2.7.18"
envelope.importPatterns();  // {javax.persistence → [Entity.java, Repository.java]}
envelope.annotations();     // [AnnotationUsage(Entity, Entity.java, MyEntity), ...]
```

### AnalysisEnvelope

The analysis output is an immutable record:

| Field | Type | Description |
| - | - | - |
| `projectName` | `String` | Project name |
| `buildTool` | `String` | Build tool identifier (e.g., "maven") |
| `bootVersion` | `String` | Current Spring Boot version |
| `javaVersion` | `String` | Current Java version |
| `dependencies` | `Map<String, String>` | groupId:artifactId → version |
| `importPatterns` | `Map<String, List<String>>` | Namespace → files using it |
| `annotations` | `List<AnnotationUsage>` | Annotation, file, class name |
| `configFiles` | `List<String>` | Config files found in resources |
| `modules` | `List<String>` | Module names for multi-module projects |
| `metadata` | `Map<String, String>` | Includes `analysisDurationMs` |

### AnalysisStrategy

| Strategy | Implementation | Description |
| - | - | - |
| `POM_ONLY` | `PomAnalyzer` | POM parsing + Java file scanning (current) |
| `FULL` | — | Reserved for SCIP + ASM bytecode analysis (not yet implemented) |

## Phase 2: Plan Generation

`PlanGenerator` takes the analysis envelope and produces an execution roadmap. This phase may invoke an LLM.

```java theme={null}
public interface PlanGenerator {
    ExecutionPlan generate(AnalysisEnvelope analysis, PlanConfig config);
}
```

### ClaudePlanGenerator

The default implementation runs a two-phase Claude conversation:

1. **Explore** — Claude reads the knowledge store and summarizes applicable patterns
2. **Plan** — Claude generates a Forge-style roadmap with explicit tool commands, using the analysis envelope and explore output

The generator extracts tool recommendations from the roadmap and tracks which KB files were accessed during planning.

### ExecutionPlan

| Field | Type | Description |
| - | - | - |
| `roadmapMarkdown` | `String` | Forge-style checklist (stages, RUN/VERIFY directives) |
| `toolRecommendations` | `List<String>` | Tool names extracted from roadmap |
| `kbFilesRead` | `List<String>` | KB files accessed during planning |
| `inputTokens` | `int` | Planning input tokens |
| `outputTokens` | `int` | Planning output tokens |
| `thinkingTokens` | `int` | Planning thinking tokens |
| `costUsd` | `double` | Planning cost |
| `durationMs` | `long` | Planning wall-clock duration |
| `planningSessionId` | `String` | Claude session ID (nullable) |

## Phase 3: Context Enrichment and Execution

Before calling the delegate invoker, the pipeline enriches the prompt with analysis and planning output:

* **Execution Roadmap** — the full roadmap markdown, prepended to the prompt
* **Available Tools** — `java -jar` commands for each tool in `toolPaths`
* **Analysis Summary** — formatted project details (Boot version, Java version, key dependencies)

The delegate `AgentInvoker` receives this enriched `InvocationContext` and runs normally. The pipeline merges planning-phase metrics (tokens, cost, duration) into the final `InvocationResult`.

## Wiring a Pipeline

```java theme={null}
ProjectAnalyzer analyzer = new PomAnalyzer();
PlanGenerator planner = new ClaudePlanGenerator(claudeClient);

PipelineConfig config = PipelineConfig.builder()
    .knowledgeDir(Path.of("kb"))
    .toolPaths(Map.of("pom-upgrader", Path.of("tools/pom-upgrader.jar")))
    .targetBootVersion("3.4.1")
    .planningModel("sonnet")
    .build();

AgentInvoker pipeline = new PipelineAgentInvoker(
    analyzer, planner, config, delegateInvoker);

// Use like any AgentInvoker
ExperimentResult result = experiment.run(pipeline);
```

Because `PipelineAgentInvoker` implements `AgentInvoker`, it plugs directly into `AgentExperiment` — existing experiment code works unchanged.

## Graceful Degradation

| Failure | Behavior |
| - | - |
| Analysis throws `AnalysisException` | Logged as warning, planning and execution continue without analysis |
| Planning throws `PlanGenerationException` | Logged as warning, execution continues with original context |
| Execution fails | Propagated — this is the only phase whose failures are surfaced |

## Related

<CardGroup cols={2}>
  <Card title="Diagnostic Reasoning" icon="stethoscope" href="/docs/agent-experiment/diagnostic-reasoning">
    Diagnose why experiments fail and generate remediation actions
  </Card>

  <Card title="Sessions and Sweeps" icon="layer-group" href="/docs/agent-experiment/sessions-and-sweeps">
    Group variant results and track sweep progress
  </Card>
</CardGroup>