Planning, Validation & Review Agents
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Planning, Validation, and Review systems in Continuous Claude v2 constitute a rigorous lifecycle for software development tasks. This system is designed to overcome the lossy nature of context compaction in long AI sessions by externalizing state into structured "thoughts" and "ledgers" that are then processed by specialized agents and scripts. The primary goal is to ensure that implementation plans are high-quality, implementations match their original intent, and outcomes are captured for future session context.
These agents rely on a Context Graph—a local SQLite database that indexes markdown artifacts like handoffs, plans, and session ledgers. By utilizing LLM-as-judge patterns and RAG-enhanced (Retrieval-Augmented Generation) analysis, the system provides automated critiques of plans and verifies code changes against established requirements.
Sources: CLAUDE_ONBOARDING.md:16-25, scripts/braintrust_analyze.py:465-475
The Lifecycle Workflow
The development workflow is structured as a series of commands (Skills) that invoke specific logic for planning, execution, and verification.
This diagram shows the iterative cycle where plans must pass judging before implementation, and implementations are reviewed before final handoff.
Sources: CLAUDE_ONBOARDING.md:120-143, scripts/braintrust_analyze.py:1020-1040
Planning System
The planning phase is the first gate in the development process. It involves creating a structured markdown document that outlines the implementation approach.
Plan Artifact Structure
Plans are stored in thoughts/shared/plans/ and typically contain the following sections:
- Overview: High-level goal of the plan.
- Approach: Implementation strategy.
- Phases: Concrete steps or stages.
- Constraints: Identified limitations or "what we're not doing."
Sources: scripts/artifact_index.py:183-205, tests/test_artifact_index.py:53-73
RAG-Enhanced Plan Judging
The system uses the braintrust_analyze.py script to perform "RAG-enhanced" judging. It searches the Context Graph for similar past work that either succeeded or failed to provide a contextual critique.
| Element | Description |
|---|---|
| Succeeded Precedent | Patterns from past successes that should be applied to the current plan. |
| Failed Precedent | Anti-patterns or mistakes from past failures that the plan must avoid. |
| Verdict | A binary PASS/FAIL result based on whether the plan addresses known risks. |
Sources: scripts/braintrust_analyze.py:560-610, scripts/braintrust_analyze.py:615-650
Validation & Review Agents
Once a plan is implemented, the Review Agent verifies the work. Unlike simple testing, this agent compares the original intent (the Plan) against the actual changes (Git Diff).
Implementation Review Logic
The review process follows a "Critique-focused" approach. The REVIEW_JUDGE_PROMPT instructs the LLM to identify gaps specifically, rather than listing successful items.
The Review Agent acts as a bridge between the planned intent and the resulting code changes.
Sources: scripts/braintrust_analyze.py:510-545, scripts/braintrust_analyze.py:990-1015
Severity Levels for Gaps
When a review is performed, identified issues are categorized by severity:
- P0: Critical missing requirements; results in a FAIL verdict and blocks proceeding.
- P1/P2: Minor issues or suggestions that may not block a session handoff but are noted for follow-up.
Sources: scripts/braintrust_analyze.py:1005-1018
Context Graph & Artifact Indexing
The Context Graph serves as the persistent memory for all agents. It is initialized during project setup and updated whenever artifacts are created or modified.
Database Schema
The database uses SQLite with FTS5 (Full-Text Search) to allow agents to query past reasoning.
| Table | Purpose | Key Fields |
|---|---|---|
handoffs | Completed task history | what_worked, what_failed, outcome, files_modified |
plans | Implementation history | overview, approach, phases, constraints |
continuity | Session state snapshots | goal, state_now, key_learnings, key_decisions |
Sources: scripts/artifact_schema.sql:15-75
Indexing Process
Artifacts are parsed from Markdown into structured rows. For example, the parse_handoff function extracts metadata from YAML frontmatter and content from specific Markdown headers (H2/H3).
def parse_handoff(file_path: Path) -> dict:
# Extracts what_was_done, what_worked, what_failed
# Maps status (e.g., 'SUCCESS') to canonical outcomes ('SUCCEEDED')
# extracts modified files from backticks or **File**: format
Sources: scripts/artifact_index.py:51-122, tests/test_artifact_index.py:245-265
Conclusion
The Planning, Validation, and Review agents provide a structured framework that transforms Claude Code from a stateless chat interface into a durable engineering system. By enforcing a "Plan -> Implement -> Review" cycle and backing it with a searchable Context Graph, the project ensures that reasoning is preserved across session clears and that implementation quality is verified against original architectural intent.
Sources: CLAUDE_ONBOARDING.md:12-25, scripts/braintrust_analyze.py:1030-1045