cdd

name	cdd
description	Context Driven Development pipeline for release workflows

CDD Pipeline

This project calls its release workflow Context Driven Development (CDD)

Workspace Configuration

All CDD commands and scripts require the $CDD_DIR environment variable.

export CDD_DIR=/path/to/workspace

This allows parallel workspaces without VCS conflicts. Each workspace is independent - different branches can use different workspace directories simultaneously.

Scripts will abort with a clear error if $CDD_DIR is not set.

Core Philosophy

Use user/agent interactive development time during the Research and Plan phases to prepare tightly focused work that pre-loads the exact required context to run autonomously during the Execute phase.

Pipeline Phases

• Research
• Plan
• Execute

1. Research

What: Build foundational understanding before design decisions.

Artifacts:

• $CDD_DIR/README.md - High-level description of release features
• $CDD_DIR/user-stories/ - User actions and expected system responses
• $CDD_DIR/research/ - Facts gathered from internet, docs, codebase

Why this phase exists: Decisions made without research are assumptions. Research surfaces constraints, prior art, and edge cases that would otherwise appear during execution (when fixing is expensive).

Key insight: Research artifacts become reference material for execution. Sub-agents can read $CDD_DIR/research/ without re-fetching from the internet. The research phase pays the lookup cost once.

2. Plan

What: Transform research into implementation decisions.

Artifacts:

• $CDD_DIR/plan/ - Implementation decisions, architecture choices, detailed designs

Why this phase exists: Planning is the translation layer between "what we want" (research) and "what to do". It makes architectural decisions explicit.

3. Verify (Sub-phase of Plan)

What: Iterative verification of plan alignment.

Artifacts:

• $CDD_DIR/gap.md - List of issues to investigate and resolve
• $CDD_DIR/verified.md - Log of issues that have been fixed

Verification:

/cdd:gap  # Verify README/user-stories → plan alignment, writes gap.md
fix gaps  # Address issues in gap.md, update plan documents
update verified.md  # Log what was fixed with references to gap.md
/cdd:gap  # Repeat until clean

Checks alignment down the pyramid:

• README/research/user-stories → plan
• Naming, error handling, memory management conventions
• Integration points, build changes, migrations

Why this phase exists: This is the last moment of full context visibility. Cross-cutting issues and inconsistencies can only be caught while the complete picture is visible.

Key insights:

• Specific checklists prevent vague "find issues" prompts
• gap.md contains current issues to investigate
• verified.md tracks what's been fixed, prevents re-checking completed items

Convergence pattern: Each gap-finding run identifies issues and writes gap.md. After fixing, log in verified.md and re-run. When no substantive gaps remain, verification is complete.

4. Execute

What: Unattended execution via the Ralph harness script.

Artifacts:

• $CDD_DIR/goals/*-goal.md - Goal file(s) for ralph loop execution
• $CDD_DIR/goals/*-progress.jsonl - Auto-generated progress log
• $CDD_DIR/goals/*-summary.md - Auto-generated progress summary

Ralph script:

.claude/harness/ralph/run \
  --goal=$CDD_DIR/goals/implementation-goal.md \
  --duration=4h \
  --model=sonnet \
  --reasoning=low

Process: Ralph iteratively works toward the goal until DONE or time expires:

1. Read goal + progress history
2. Make incremental progress (code changes, tests, fixes)
3. Commit progress via jj commit
4. Append progress to JSONL file
5. Repeat until objective achieved

Why Ralph: The plan phase prepared complete context. Ralph execution is mechanical - read plan, implement, test, commit. No research, no exploration, just steady progress toward the goal using the plan as a reference.

Post-execution: After Ralph completes (or during iterations), quality checks and refactoring may be needed:

ralph → /check:quality → /refactor → /check:quality

Directory Structure

$CDD_DIR/
├── README.md          # High-level release description (PRD)
├── user-stories/      # User actions and system responses
│   └── README.md      # Index/overview
├── research/          # Internet facts for reference
│   └── README.md      # Index/overview
├── plan/              # Implementation decisions
│   └── README.md      # Index/overview
├── gap.md             # Current issues to investigate and resolve
├── verified.md        # Log of issues that have been fixed
├── goals/             # Ralph goal files and execution state
│   ├── *-goal.md      # Goal definition(s)
│   ├── *-progress.jsonl   # Progress tracking (auto-generated)
│   └── *-summary.md   # Progress summary (auto-generated)
├── tmp/               # Temp files during execution
└── ...                # Other files permitted, ignored by pipeline

Abstraction Levels

Each directory serves a distinct abstraction level. Content should not leak between levels.

$CDD_DIR/plan/ - Coordination Layer

Plan documents coordinate everything shared.

The plan owns:

• Public symbols - Function names, struct names, enum names
• Function signatures - Arguments, argument order, return types
• Struct members - Field names, field order, field types
• Enums - Value names and meanings
• Allowed libraries - Which dependencies can be used, which are forbidden
• Architectural choices - Module boundaries, data flow, ownership rules

The plan is the contract.

DO NOT include: Implementation code, detailed algorithms, function bodies.

Artifact Authority

Artifacts form a hierarchy of authority:

$CDD_DIR/README.md (authoritative)
        ↓
user-stories + research (derived)
        ↓
      plan (derived)

Rules:

1. Lower-level artifacts derive from higher-level ones
2. Contradictions between levels must be resolved immediately
3. Resolution is always top-down: align lower artifacts to higher authority
4. Higher-level documents may change through iteration—but when they do, all derived artifacts must be reviewed and realigned

Why this matters: Consistency is enforced during authoring because it cannot be enforced during execution.

Writing Ralph Goal Files

After creating plan documents, write goal files in $CDD_DIR/goals/*-goal.md.

Use /load goal-authoring for detailed guidance. Key points:

• Ralph has unlimited context through iteration - reference all relevant docs
• Specify WHAT to achieve (outcomes), never HOW (steps/order)
• One cohesive objective per goal - trust Ralph to discover the path
• Complete acceptance criteria - Ralph needs to know when done

Lifecycle

Create empty $CDD_DIR/ → Research → Plan → Verify → Execute → Delete $CDD_DIR/

The workspace directory is ephemeral. It exists only for the duration of the release workflow. After successful execution, it's deleted. The work lives in the codebase; the pipeline artifacts are disposable.

Efficiency Principles

1. Load skills on-demand - Don't preload "just in case"
2. Complete authoring - Spend tokens researching during authoring so execution doesn't need to
3. Reference vs working knowledge - Large docs go in separate skills, loaded when needed

Design Tradeoffs

Decision	Tradeoff	Rationale
Full context in verify	Expensive per-run	Last chance to catch cross-cutting issues
Verification is human-terminated	Subjective	Models don't converge to "done" naturally
Research cached in files	Stale if release spans days	Avoids re-fetching during execution

When to Load This Skill

• Designing or modifying the release workflow
• Debugging why execution sub-agents are failing
• Optimizing token usage in the pipeline
• Understanding why a phase exists before changing it