agentic-implementation

Agentic Implementation Methodology

A structured approach to building software projects using Claude Code with phased implementation, automated validation, and PM oversight between phases.

---

Overview

The Agentic Implementation Methodology is a PowerShell-based framework for orchestrating complex software projects using Claude Code. It breaks implementation into discrete phases, with automated Project Manager (PM) validation between each phase to ensure quality and alignment.

First Used: Redbook Web Conversion Project (February 2025)

Key Benefits

Benefit	Description
Structured Progress	Clear phases with defined deliverables
Quality Gates	PM validation catches issues early
Audit Trail	Validation reports document decisions
Resumable	Can restart from any phase
Reproducible	Same methodology for future projects

---

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    AGENTIC IMPLEMENTATION FLOW                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────────┐                                                        │
│  │ ANALYSIS SCRIPT  │  (analyze-*.ps1)                                       │
│  │                  │                                                        │
│  │ • Explore codebase│                                                       │
│  │ • Document patterns│                                                      │
│  │ • Identify unknowns│                                                      │
│  │ • Create roadmap  │                                                       │
│  └────────┬─────────┘                                                        │
│           │                                                                  │
│           ▼ Produces: docs/*.md                                              │
│  ┌──────────────────┐                                                        │
│  │ HUMAN REVIEW     │  Resolve unknowns, approve approach                    │
│  └────────┬─────────┘                                                        │
│           │                                                                  │
│           ▼                                                                  │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ IMPLEMENTATION SCRIPT  (implement-*.ps1)                              │   │
│  │                                                                       │   │
│  │  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐           │   │
│  │  │ Phase 0 │───►│ PM Val  │───►│ Phase 1 │───►│ PM Val  │───► ...   │   │
│  │  │ Setup   │    │ Report  │    │ Core    │    │ Report  │           │   │
│  │  └─────────┘    └─────────┘    └─────────┘    └─────────┘           │   │
│  │       │              │              │              │                 │   │
│  │       ▼              ▼              ▼              ▼                 │   │
│  │  [Claude Code]  [Claude PM]   [Claude Code]  [Claude PM]            │   │
│  │                                                                       │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│           │                                                                  │
│           ▼ Produces: code + validation reports                              │
│  ┌──────────────────┐                                                        │
│  │ DEPLOYMENT       │                                                        │
│  └──────────────────┘                                                        │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Two-Script Approach

Script 1: Analysis (analyze-*.ps1)

The analysis script explores the problem space and generates planning documents.

Purpose: Understand existing systems, document patterns, identify unknowns

Output: Markdown documents in docs/ folder:

Document	Purpose
01_ARCHITECTURE_PATTERNS.md	Patterns from reference implementations
02_FEATURE_INVENTORY.md	Features to implement
03_API_DESIGN.md	API specifications
04_FRONTEND_ARCHITECTURE.md	UI/UX design
05_IMPLEMENTATION_ROADMAP.md	Phased plan
06_UNKNOWNS_AND_DECISIONS.md	Questions requiring human input

Example Structure:

# analyze-project.ps1
 
$AnalysisPrompt = @"
Analyze the existing system and create planning documents.
 
Reference codebases:
- $ExistingAppPath (legacy app to convert)
- $ReferenceAppPath (modern app with patterns to follow)
 
Create these documents:
1. Architecture patterns from reference app
2. Feature inventory from legacy app
3. API design specification
4. Frontend architecture
5. Implementation roadmap
6. Unknowns requiring human decisions
"@
 
claude -p $AnalysisPrompt --allowedTools "Read,Glob,Grep,Write"

Script 2: Implementation (implement-*.ps1)

The implementation script executes the plan in phases with validation.

Purpose: Build the software following the documented plan

Key Features:

• Phases numbered 0-N
• Each phase has specific deliverables
• PM validation between phases
• Embedded context from resolved unknowns

---

PM Validation Layer

How It Works

After each implementation phase, a PM agent reviews the output:

function Invoke-PMValidation {
    param(
        [int]$CompletedPhase,
        [int]$NextPhase
    )
 
    $PMPrompt = @"
    You are a Project Manager validating Phase $CompletedPhase.
 
    ## Deliverables to Verify
    $($PhaseDeliverables[$CompletedPhase])
 
    ## Reference Documents
    - docs/03_API_DESIGN.md
    - docs/04_FRONTEND_ARCHITECTURE.md
 
    ## Output
    Create validation report at: docs/validation/phase${CompletedPhase}_validation.md
 
    If PASS: Output PM_VALIDATION_PASSED
    If FAIL: Output PM_VALIDATION_FAILED
    "@
 
    claude -p $PMPrompt --allowedTools "Read,Glob,Grep,Bash,Write"
}

Validation Modes

Mode	Behavior	Use Case
blocking (default)	Halts on failure	Production builds
warning	Logs issues, continues	Development iteration
-SkipValidation	No PM checks	Quick prototyping

What PM Validates

1. File Existence: Were expected files created?
2. Compilation: Does the code build?
3. Architecture Alignment: Does code match design docs?
4. Interface Compliance: Correct API signatures, subroutine calls?
5. Completeness: All deliverables checked off?

Validation Report Format

# PM Validation Report: Phase 1
 
**Status**: PASS WITH WARNINGS
**Date**: 2025-02-04
 
## Deliverables Checklist
- [x] RedbookEntry.cs model created
- [x] RedbookService.cs implements CRUD
- [ ] Unit tests (WARNING: minimal coverage)
 
## Architecture Alignment
| Aspect | Status |
|--------|--------|
| API Design | Aligned |
| Subroutine Interfaces | Correct |
 
## Issues Found
1. **WARNING**: Unit test coverage is 40%, target is 80%
 
## Recommendation
**GO WITH FIXES** - Proceed but add tests in Phase 7

---

Phase Structure

Typical Phases

Phase	Name	Purpose
0	Setup	Repository, project structure, dependencies
1	Core Models	Data models, parsers, base services
2	API Endpoints	REST endpoints, authorization
3	Frontend Core	Auth, routing, API client
4	List/Search UI	Primary data display
5	Detail/Edit UI	CRUD forms
6	Reports	PDF/Excel export
7	Testing	Unit, integration, E2E tests
8	Deployment	CI/CD, documentation

Phase Prompt Template

$Prompt = @"
# PHASE N: [Name]
 
## Critical Context
$ResolvedContext  # Embedded decisions from analysis
 
## Reference Files
- $DocsPath\03_API_DESIGN.md
- $ReferencePath\Services\ExampleService.cs
 
## Task
[Detailed instructions for this phase]
 
## Deliverables
- [ ] File 1 created
- [ ] File 2 modified
- [ ] Tests pass
 
Output PHASE{N}_COMPLETE when done.
"@
 
claude -p $Prompt --allowedTools "Read,Write,Edit,Bash,Glob,Grep" --max-turns 50

---

Embedded Context

The $ResolvedContext Variable

Critical decisions from analysis are embedded in every phase prompt:

$ResolvedContext = @"
## CRITICAL IMPLEMENTATION CONTEXT
 
### Subroutine Interfaces (VERIFIED)
 
**VB_EXAMPLE_SUB** - Save/Delete Operations:
- Arg 1: CO (String) - Company code
- Arg 2: REQTYPE (String) - "DELETE" or empty
- Arg 3: ID (String) - Record ID
- Arg 4: RECORD (UniDynArray) - Data
- Arg 5: MESSAGE (OUT) - Result
 
IMPORTANT: Does NOT support GET operations - use direct READ.
 
### Authentication Flow
1. Azure AD JWT → API
2. UPN lookup → AD extensionAttributes
3. Decrypt credentials → UniData connection
 
### Permissions
| Action | Requirement |
|--------|-------------|
| View/Edit | Authenticated user |
| Delete | "Admin Group" membership |
"@

Why Embed Context?

• Each Claude invocation is stateless
• Prevents drift from documented decisions
• Ensures consistent implementation across phases
• Critical details (like “subroutine X doesn’t support GET”) are repeated

---

Usage

Full Implementation Run

# Run all phases with PM validation
.\implement-project.ps1
 
# Warning mode (don't stop on validation failures)
.\implement-project.ps1 -ValidationMode "warning"
 
# Skip validation for speed
.\implement-project.ps1 -SkipValidation

Partial Runs

# Run specific phase only
.\implement-project.ps1 -Phase 3
 
# Resume from phase (skips earlier phases)
.\implement-project.ps1 -StartFromPhase 5

After Validation Failure

# 1. Review the validation report
cat docs\validation\phase2_validation.md
 
# 2. Fix issues manually or re-run phase
.\implement-project.ps1 -Phase 2
 
# 3. Continue from next phase
.\implement-project.ps1 -StartFromPhase 3

---

Creating a New Project

Step 1: Create Analysis Script

# analyze-newproject.ps1
 
param([string]$MaxIterations = "30")
 
$DocsPath = "C:\GIT\newproject-analysis\docs"
$LegacyPath = "C:\GIT\LegacyApp"
$ReferencePath = "C:\GIT\ModernReference"
 
# Create docs folder
New-Item -ItemType Directory -Path $DocsPath -Force
 
$AnalysisPrompt = @"
Analyze the legacy application and create implementation planning documents.
 
## Legacy Application
Path: $LegacyPath
[Description of what to analyze]
 
## Reference Implementation
Path: $ReferencePath
[Patterns to extract]
 
## Output Documents
Create in $DocsPath:
1. 01_ARCHITECTURE_PATTERNS.md
2. 02_FEATURE_INVENTORY.md
3. 03_API_DESIGN.md
4. 04_FRONTEND_ARCHITECTURE.md
5. 05_IMPLEMENTATION_ROADMAP.md
6. 06_UNKNOWNS_AND_DECISIONS.md
"@
 
claude -p $AnalysisPrompt --allowedTools "Read,Glob,Grep,Write" --max-turns $MaxIterations

Step 2: Review and Resolve Unknowns

1. Read 06_UNKNOWNS_AND_DECISIONS.md
2. Research answers to open questions
3. Update the document with decisions
4. Mark items as RESOLVED

Step 3: Create Implementation Script

Use the template structure:

# implement-newproject.ps1
 
param(
    [string]$Phase = "all",
    [int]$StartFromPhase = 0,
    [string]$MaxIterations = "50",
    [ValidateSet("blocking", "warning")]
    [string]$ValidationMode = "blocking",
    [switch]$SkipValidation
)
 
# Path configuration
$DocsPath = "..."
$ProjectPath = "..."
 
# Resolved context from analysis
$ResolvedContext = @"
[Paste critical decisions here]
"@
 
# Phase deliverables for PM validation
$PhaseDeliverables = @{
    0 = @"
    - [ ] Project structure created
    - [ ] Dependencies installed
    "@
    1 = @"
    - [ ] Core models implemented
    - [ ] Service layer complete
    "@
    # ... more phases
}
 
# PM Validation function
function Invoke-PMValidation { ... }
 
# Phase 0
if ($Phase -eq "all" -or $Phase -eq "0") {
    $Prompt0 = @"
    # PHASE 0: Setup
    $ResolvedContext
    [Instructions]
    "@
 
    claude -p $Prompt0 --allowedTools "Read,Write,Edit,Bash,Glob,Grep"
 
    if ($Phase -eq "all") {
        Invoke-PMValidation -CompletedPhase 0 -NextPhase 1
    }
}
 
# Phase 1, 2, 3... (repeat pattern)

---

Best Practices

Do

• Embed critical context in every phase prompt
• Define specific deliverables for PM validation
• Use reference implementations for patterns
• Document unknowns during analysis
• Keep phases focused (2-4 hours of work each)

Don’t

• Skip the analysis phase - leads to rework
• Ignore validation failures - issues compound
• Make phases too large - harder to debug
• Forget to update context - when decisions change

---

Example: Redbook Web Project

Project Structure

C:\GIT\redbook-web-analysis\
├── analyze-redbook-web.ps1      # Analysis script
├── implement-redbook-web.ps1    # Implementation script
└── docs\
    ├── 01_ARCHITECTURE_PATTERNS.md
    ├── 02_REDBOOK_FEATURE_INVENTORY.md
    ├── 03_API_DESIGN.md
    ├── 04_FRONTEND_ARCHITECTURE.md
    ├── 05_IMPLEMENTATION_ROADMAP.md
    ├── 06_UNKNOWNS_AND_DECISIONS.md
    └── validation\
        ├── phase0_validation.md
        ├── phase1_validation.md
        └── ...

Key Resolved Decisions

From 06_UNKNOWNS_AND_DECISIONS.md:

1. Subroutine Interface: VB_REDBOOK.REV1 does NOT support GET - use direct READ
2. Authentication: Entra ID → AD extensionAttribute2 → UniData credentials
3. Permissions: Delete requires “Computer Group” AD membership
4. Deployment: GitHub self-hosted runner on PS-PROXY for API

Phases

Phase	Duration	Deliverables
0	Setup	Project structure, TypeScript types
1	API Core	C# models, RedbookService, RedbookParser
2	Endpoints	REST API with authorization
3	Frontend Core	MSAL auth, React Query hooks
4	List UI	AG Grid, filters, department columns
5	Detail UI	RFC form, department checkboxes
6	Reports	PDF/Excel export
7	Testing	Unit tests, lint, type check
8	Deployment	CI/CD, documentation

---

Future: Skill Template

This methodology could become a reusable Claude Code skill:

/implement-project <legacy-path> <reference-path> <output-path>

The skill would:

1. Generate analysis script from template
2. Run analysis phase
3. Prompt for unknown resolution
4. Generate implementation script
5. Execute with PM validation

---

Related Pages

• Claude Code Integration - Skills and commands
• PSI.UniData.API - API being extended
• Web App Deployment Guide - Deployment patterns

---

Last updated: February 2025