Pipeline Phases

The Edsger CLI executes features through a series of phases — discrete steps in the software development lifecycle. Each phase uses AI (Claude Agent SDK) to analyze context, generate output, and verify quality. Phases are connected by a pipeline that manages dependencies, error handling, and status transitions.

Why Phases

Breaking the development lifecycle into discrete phases provides several advantages:

• Incremental verification — Each phase's output can be verified before moving to the next, catching issues early
• Targeted re-runs — If a phase produces poor output, only that phase needs to be re-run (with feedback), not the entire pipeline
• Human control — Teams can configure approval gates at specific phases, allowing humans to review and redirect AI work
• Feedback loops — The platform's feedback system injects human guidance directly into phase prompts when re-running
• Resumability — If the CLI crashes or is stopped, it can resume from the last completed phase

Phase Overview

Phase Structure

Every phase implementation follows the same structure:

src/phases/{phase-name}/
├── index.ts      # Main execution function
├── prompts.ts    # AI prompt templates
├── context.ts    # Context gathering (reads platform data, repo state)
├── outcome.ts    # Result parsing and validation
└── __tests__/    # Unit tests

Each phase:

1. Gathers context — Reads feature data, product info, existing artifacts (user stories, test cases, technical design), repository state, checklists, and any feedback from previous runs
2. Constructs a prompt — Combines context with phase-specific instructions
3. Executes via Claude Agent SDK — Sends the prompt to Claude, which can read files, run commands, and make changes in the repository
4. Parses the outcome — Validates the AI's response and extracts structured data
5. Updates the platform — Saves results (user stories, test cases, etc.) via MCP and updates the feature status

Phase Details

Feature Analysis

Status: feature_analysis → feature_analysis_verification

The entry point for the full pipeline. Analyzes the feature description and produces the foundational requirements that all subsequent phases build on.

What it does:

1. Reads the feature description, product context, and any existing project documentation (.edsger/ files)
2. Generates user stories that capture the feature's requirements from the user's perspective
3. Generates test cases that define how to verify the feature works correctly
4. Evaluates checklist items if a checklist is configured for this phase
5. Can delete and recreate user stories/test cases if feedback indicates they need rework

Outputs:

• Created user stories (saved to platform via MCP)
• Created test cases with criticality flags (saved to platform via MCP)
• Checklist item results
• A summary of the analysis

Verification: After analysis, the output enters feature_analysis_verification where the quality is checked. If verification fails, the phase re-runs with feedback about what needs to change. The maxVerificationIterations config (default: 10) caps re-run loops.

User Stories Analysis

Status: user_stories_analysis → user_stories_analysis_verification

A focused phase that generates only user stories (without test cases). Used when you want more control over the requirements process.

What it does:

1. Reads the feature description, product context, and any existing user stories
2. Generates detailed user stories with acceptance criteria
3. Each story follows the "As a [role], I want [action], so that [benefit]" format
4. Evaluates relevant checklist items

Outputs:

• User stories saved to the platform
• Checklist results

Test Cases Analysis

Status: test_cases_analysis → test_cases_analysis_verification

Generates test cases based on the feature requirements and user stories.

What it does:

1. Reads feature details, existing user stories, and product context
2. Generates test cases that cover the feature's functionality
3. Marks critical test cases (those testing core functionality or security)
4. Evaluates relevant checklist items

Outputs:

• Test cases with is_critical flags saved to the platform
• Checklist results

Technical Design

Status: technical_design → technical_design_verification

Creates a detailed technical specification that guides the code implementation phase.

What it does:

1. Reads the feature description, user stories, test cases, product context, and project documentation
2. Analyzes the existing codebase structure and architecture
3. Generates a technical design document covering:
   • Architecture decisions and rationale
   • Component structure and dependencies
   • Data models and API contracts
   • Implementation approach and sequence
   • Edge cases and error handling strategy
4. Evaluates relevant checklist items

Outputs:

• Technical design document (saved to the platform)
• Checklist results

Branch Planning

Status: branch_planning → branch_planning_verification

Plans how to split the feature implementation into logical git branches for manageable pull requests.

What it does:

1. Reads the technical design, user stories, and codebase structure
2. Determines the optimal branching strategy
3. Plans branch names, order of implementation, and dependencies between branches

Outputs:

• Branch plan with named branches and their descriptions
• Implementation order and dependencies

Code Implementation

Status: code_implementation → code_implementation_verification

The core phase where AI writes the actual code. Uses the Claude Agent SDK to interact with the repository.

What it does:

1. Reads the technical design, user stories, test cases, and project documentation
2. Sets up the repository (branch creation, dependency installation)
3. Uses Claude Agent SDK with a claude_code system preset to:
   • Read existing code files for context
   • Write new files and modify existing ones
   • Run commands (build, lint, type-check)
   • Iterate on errors until the code compiles and passes checks
4. Commits changes to the feature branch

Outputs:

• Source code changes committed to the repository
• Checklist results

After successful implementation: If running in only_code_implementation mode, a pull request is automatically created. In pipeline mode, the PR is created after functional testing passes.

PR Splitting

Status: pr_splitting → pr_splitting_verification

For large features, this phase plans how to split the implementation across multiple pull requests for easier review.

What it does:

1. Analyzes the committed changes from code implementation
2. Groups files into logical PR units (e.g., database changes, API layer, UI components)
3. Determines the order PRs should be created and merged
4. Plans PR titles, descriptions, and file assignments

Outputs:

• PR plan saved to the platform
• File-to-PR mapping

PR Execution

Status: pr_execution

Takes the PR plan from the splitting phase and creates actual GitHub pull requests.

What it does:

1. Reads the PR plan
2. For each planned PR:
   • Creates a git branch
   • Cherry-picks or moves relevant changes
   • Pushes the branch to GitHub
   • Creates a GitHub pull request with title and description
3. Links PRs together (e.g., noting dependencies in PR descriptions)

Outputs:

• GitHub pull requests created
• Branch references saved to the platform

Functional Testing

Status: functional_testing → testing_passed / testing_failed

Runs tests to verify the implementation works correctly.

What it does:

1. Detects the project's test framework (Jest, Vitest, Playwright, pytest, etc.)
2. Runs the test suite
3. Analyzes test results for failures
4. If tests fail, the test retry handler kicks in:
   • Creates a bug-fixing phase to address failures
   • Re-runs tests after fixes
   • Repeats up to the configured retry limit

Outputs:

• Test results (pass/fail counts)
• Feature status updated to testing_passed or testing_failed

After testing passes: A pull request is created (if not already created), and the pipeline continues to code review.

Code Testing

Writes automated tests for the implemented code. This phase runs after code review and refinement.

What it does:

1. Reads the implementation, technical design, and existing test patterns
2. Generates unit and integration tests
3. Ensures tests follow the project's testing conventions
4. Commits test files to the repository

Outputs:

• Test files committed to the repository

Code Review

Status: code_review

Performs AI-powered code review on the pull request.

What it does:

1. Reads the pull request diff from GitHub
2. Analyzes the changes against:
   • The technical design
   • Coding guidelines (from .edsger/coding-guidelines.md)
   • Common code quality patterns
3. Creates review comments directly on the GitHub pull request
4. Identifies issues ranging from bugs to style violations

Outputs:

• GitHub PR review comments

Code Refine

Status: code_refine → code_refine_verification

Refines the implementation based on code review feedback.

What it does:

1. Reads the code review comments and PR feedback
2. Reads any human feedback from the platform
3. Makes changes to address review comments
4. Runs a retry handler that:
   • Refines code
   • Verifies the refinement meets quality criteria
   • Re-refines if verification fails
   • Caps iterations per maxVerificationIterations

Outputs:

• Updated source code committed to the repository
• Resolved review comments

Bug Fixing

Status: bug_fixing

Automatically fixes bugs found during functional testing.

What it does:

1. Reads the test failure output
2. Analyzes the error messages and stack traces
3. Identifies the root cause in the implementation
4. Applies fixes and verifies they resolve the failures

Outputs:

• Bug fixes committed to the repository

Autonomous Mode

Status: N/A (special mode)

A free-form mode where the AI independently discovers improvements and implements them.

What it does:

1. Analyzes the codebase for potential improvements
2. Identifies: bugs, performance issues, missing error handling, code quality issues
3. Implements fixes in a time-limited loop
4. Creates a pull request with all changes

This mode is useful for ongoing code health maintenance without specific feature requirements.

Verification Gates

Most phases have a corresponding *_verification status. At this gate:

1. The phase output is evaluated against quality criteria
2. If the output passes, the pipeline advances to the next phase
3. If the output fails, feedback is generated explaining what needs to change
4. The phase re-runs with the feedback injected into the AI prompt
5. This loop continues up to maxVerificationIterations times

Verification can be performed by:

• AI — Automatic quality evaluation based on configurable criteria
• Human — Manual review via the Edsger web UI (configured per-product, per-phase in approval settings)

When a phase reaches its verification iteration limit, the feature is escalated for human review.

Checklists in Phases

Each phase can have an associated checklist configured in the Edsger platform. Checklists define specific quality criteria that must be satisfied.

During phase execution:

1. The CLI fetches the checklist for the current phase
2. Checklist items are included in the AI prompt as evaluation criteria
3. The AI evaluates each item and reports: passed/failed with notes
4. Results are saved to the platform
5. Unsatisfied checklist items can trigger verification failure

See Checklists for details on configuring phase checklists.

Feedback Integration

When a phase is re-run (due to verification failure or human rejection), all feedback from the platform is injected into the AI prompt. This includes:

• Phase feedback — Comments attached to a specific phase run
• Line feedback — Comments targeting specific lines or ranges in the output
• General feedback — Product or feature-level guidance

This feedback mechanism allows humans to steer the AI's output without needing to write code themselves. For example, after reviewing a technical design, a developer might add feedback like "Use Redis instead of Memcached for the caching layer" — the next run of the technical design phase will incorporate this direction.

See Approvals & Feedback for details on the feedback system.

Pipeline Composition

The phase orchestrator composes phases based on the execution mode. In pipeline modes (full_pipeline, from_*), phases are run sequentially with a "should continue" check between each:

Phase 1 → check result → Phase 2 → check result → Phase 3 → ...

If any phase returns an error or blocked status, the pipeline stops. A success status advances to the next phase.

The full pipeline includes automatic handling of:

• Test failure retry — If functional testing fails, the CLI enters a bug-fix loop (fix → re-test → repeat)
• Code refine retry — If code refinement verification fails, the CLI re-refines with feedback
• PR creation — Pull requests are created after tests pass
• Post-PR workflow — Code review → code refine → code testing runs automatically after PR creation
• Final status — On completion, the feature is moved to ready_for_review