Synthesis project management is a lightweight system for human-AI collaboration. It solves one problem: when working with AI assistants on multi-session projects, context gets lost.

TL;DR: AI conversation context compacts (gets summarized due to length). Detailed progress disappears. Sessions end and start fresh. Lessons learned sit in folders nobody checks. This system creates persistent state that survives context loss. Your AI assistant starts every task knowing what went wrong last time.

The Problem

When working with AI assistants on projects that span multiple sessions:

• Context compaction: conversation summaries lose nuanced instructions
• Session boundaries: each session starts fresh, no persistent memory
• Multiple projects: confusion about current state across projects
• Lessons learned: valuable insights get written but never surfaced

Traditional project documentation doesn’t solve this. Work logs get written but rarely read. Lesson files sit in folders until someone remembers to check. The documentation exists, but it doesn’t work.

Design Principles

Five principles guide the system.

1. Discoverability over documentation. Agents can search and grep. Humans need quick orientation. Prefer consistent naming conventions over maintained indexes.

2. Convention over configuration. Consistent structure means less cognitive load. When everything follows the same pattern, both humans and agents know where to look.

3. Single source of truth. No duplicate indexes to maintain. Files should be self-describing through front matter and naming conventions.

4. Self-describing files. Date prefixes, status in index.yaml, front matter metadata. No separate documentation that can get stale.

5. Agents do the work. Templates are a pre-AI pattern. To create something new, examine an existing example and adapt it. Agents excel at this.

System Architecture

Everything lives in one location within your workspace:

projects/
├── index.yaml               # Single index for ALL projects
│
├── {project-id}/            # Project folders (flat structure)
│   ├── CONTEXT.md           # Working memory (budget: ≤150 lines)
│   ├── REFERENCE.md         # Stable facts (updated in place)
│   ├── sessions/            # Archived session history
│   │   └── YYYY-MM.md       #   Monthly files
│   └── resources/           # Project data and artifacts (optional)
│
└── _lessons/                # Cross-project lessons and patterns
    └── YYYY-MM-DD-*.md      # Date-prefixed for discoverability

Each project has up to three context tiers, created as needed:

Tier	File	Purpose	Budget
Working memory	CONTEXT.md	Current state, active tasks, recent sessions	≤150 lines
Semantic memory	REFERENCE.md	Stable facts (team, URLs, architecture)	≤300 lines
Episodic memory	sessions/	Archived session history, monthly files	No limit

Not every project needs all three tiers. A short-lived project may only ever have CONTEXT.md. REFERENCE.md and sessions/ are created when a project accumulates enough content to warrant them — typically when CONTEXT.md first exceeds 120 lines.

Key Decisions

Decision	Rationale
Flat project folders	Status is in index.yaml, not folder names. No moving folders when status changes.
Three context tiers	Different information types have different lifecycles. Separating them prevents unbounded growth.
_lessons/ underscore prefix	Distinguishes from project folders. Sorts to top. Visible, not hidden.
Date-prefixed lesson files	Enables time-based discovery. ls -t shows recent. No index needed.
No templates folder	Agents examine existing examples and adapt. Templates are a pre-AI pattern.

The Tiered Context Architecture

Every active project needs a CONTEXT.md file. This is the most important component — the AI’s working memory. But it has a hard budget: 150 lines maximum.

Why a budget? Because CONTEXT.md is loaded at the start of every session. A 1,000-line context file wastes tokens on information that isn’t needed today. Budget enforcement keeps the AI focused on what matters right now.

# {Project Name} — Working Context

**Phase:** [Current phase]
**Last session:** YYYY-MM-DD

For stable reference facts: see [REFERENCE.md](REFERENCE.md)
For session history: see [sessions/](sessions/)

---

## Current State

[What's deployed, what's in progress, what's blocked]

## What's Next — Prioritized

1. [ ] [Highest priority task]
2. [ ] [Next task]

## Recent Session: YYYY-MM-DD

[Summary of last session: work done, decisions made]

---

*This file follows the Tiered Context Architecture. Budget: ≤150 lines.*

When stable facts accumulate (team rosters, URLs, architecture decisions), they move to REFERENCE.md — a file that’s updated in place, not appended to. When a team member leaves, you update the roster entry. When a URL changes, you change the URL. Reference files are loaded on demand, not every session.

When session logs age past a week, they move to sessions/YYYY-MM.md — monthly archive files that are append-only and rarely read. They’re there when you need historical context, but they don’t consume working memory.

This is garbage collection for AI context. It runs at session boundaries.

Update when: After EVERY significant task or phase completion. Not at session end. Immediately. This is non-negotiable.

The Protocol

During Work

Complete task → Update CONTEXT.md → Commit → Next task

NOT:

Complete task → Complete task → Complete task → (context compaction) → Lost details

Context compaction can happen at any time during long sessions. If CONTEXT.md is stale, all detailed progress is lost.

Session Start

1. Read CONTEXT.md. Understand current state before touching code.
2. Check line count. If CONTEXT.md exceeds 150 lines, archive before starting work.
3. Read REFERENCE.md if it exists and the task needs reference details.
4. Search _lessons/. Run grep for relevant past experiences.
5. Check related projects. Look at related: tags in index.yaml.

Session End

1. Final CONTEXT.md update. Ensure all sections are current (within 150-line budget).
2. Archive if needed. Move old session logs to sessions/, stable facts to REFERENCE.md. Archive FIRST, verify content exists in destination, then remove from CONTEXT.md. Two-phase commit.
3. Update index.yaml. Set last_session date.
4. Commit all changes. Don’t leave uncommitted work.

Project Status Model

Status is a field in index.yaml, not a folder location:

projects:
  - id: my-project
    name: My Project Name
    status: active
    description: Brief description
    tags: [tag1, tag2]
    last_session: 2025-12-24

Status	CONTEXT.md	REFERENCE.md	sessions/	Budget
active	Required	When needed	When needed	≤150 lines
paused	Required	When needed	When needed	≤150 lines
ongoing	Required	When needed	When needed	≤150 lines
completed	Summary	Optional	Optional	≤80 lines
archived	Frozen	Frozen	Frozen	N/A

Active projects need lean working memory. Completed projects get a concise summary of what was accomplished.

Lessons: Cross-Project Learning

The _lessons/ folder captures mistakes, insights, and patterns that apply across projects.

File naming: YYYY-MM-DD-topic-slug.md

For incidents/mistakes:

---
type: incident
title: Brief Title
severity: minor | moderate | serious | critical
---

# {Topic}: {Brief Title}

## What Happened
## Root Cause
## Impact
## Lesson
## Prevention

For patterns (generalized insights):

---
type: pattern
title: Pattern Name
---

# {Pattern Name}

## Context
{When this pattern applies}

## Problem
{What problem it solves}

## Solution
{The pattern itself}

## Examples
{Where it's been applied}

Update when: Immediately when you learn something reusable. Don’t defer.

AI Assistant Integration

Add to your CLAUDE.md:

## Context Lifecycle

After completing ANY significant task:

1. **Update CONTEXT.md immediately.** Don't wait until session end. Budget: ≤150 lines.
2. **Move stable facts to REFERENCE.md.** Don't accumulate reference content in CONTEXT.md.
3. **Archive old sessions.** Move logs older than 1 week to sessions/YYYY-MM.md.
4. **Update index.yaml.** Set last_session date.
5. **Add to _lessons/.** If you learned something reusable.
6. **Commit to git.** At logical checkpoints.

**Location:** `{workspace}/projects/`

The user should NEVER have to remind you to do this.

Project Discovery

When a user mentions a project:

1. Read projects/index.yaml
2. Match against project name, description, id, tags
3. If match found, read the project’s CONTEXT.md
4. Summarize current state and next steps
5. Begin work from where it left off

This eliminates starter prompts. Say “working on the API project” and the AI loads context automatically.

Results in Practice

This system is operational.

Context recovery dropped from 15+ minutes to seconds. Lessons get surfaced proactively instead of sitting forgotten in folders. Pattern detection works across projects. Session handoffs are seamless because the state lives in files, not conversation memory. Starter prompts are gone; semantic project discovery replaced them.

Common Mistakes

Mistake	Consequence	Prevention
Not updating CONTEXT.md	Lost progress after compaction	Update after EVERY task
Letting CONTEXT.md grow past 150 lines	Wastes tokens, dilutes focus	Archive at session boundaries
Putting stable facts in CONTEXT.md	File bloats with unchanging content	Use REFERENCE.md for stable facts
Deferring updates to “session end”	Forget to update	Update immediately
Not checking _lessons/	Repeat mistakes	Grep at session start

Teams: Multiple Humans, Multiple AI Assistants

The system scales. When Alice’s AI works on auth Monday, Bob’s AI knows about it Tuesday.

Shared knowledge artifacts:

• CONTEXT.md files in shared repos
• Lessons learned in central location
• Semantic indexes spanning the team

The project manager’s role evolves. It shifts from tracking status to ensuring knowledge flows into the shared system.

Parallel Discoveries: OpenAI’s Codex

After publishing this article, I read OpenAI’s case study on shipping Sora with Codex. Several patterns emerged independently:

• Planning before coding. Extensive planning before implementation.
• Foundation-first. Humans design structure, AI executes.
• Conductor model. Coordinating AI agents like an orchestra.
• Review as bottleneck. Human time shifts from writing to deciding.

The convergence validates that these aren’t arbitrary choices. They’re fundamental principles.

Coexistence with Tool-Native Memory

Some AI tools have their own memory systems. Claude Code has MEMORY.md, ChatGPT has persistent memory, Gemini has conversation history. Synthesis project management is independent of and coexists with all of them.

The distinction: tool-native memory is automatic, per-tool, and unstructured. Synthesis project management is deliberate, tool-agnostic, and structured. MEMORY.md stores facts that Claude noticed during conversations. CONTEXT.md stores the curated state of a project. They serve different purposes and neither replaces the other.

If you use Claude Code, you’ll have both MEMORY.md (Claude’s auto-memory) and CONTEXT.md (your project state). They coexist without conflict. MEMORY.md may even contain a pointer to your project management system, which is fine.

Getting Started

1. Create a projects/ directory in your workspace.
2. Create index.yaml with your first project entry.
3. Add CONTEXT.md to one active project (use the template above).
4. Add the context lifecycle instructions to your CLAUDE.md (or equivalent).
5. Use it for a week. The benefits compound quickly.
6. When CONTEXT.md passes 120 lines, create REFERENCE.md and sessions/ for the first time.
7. Expand to other projects.

The complete system is available as open-source runbooks:

• synthesis-project-management.md — the project management system
• context-lifecycle.md — the tiered context architecture with templates and migration guides

Evolution

This system has evolved through three stages.

Stage 1: Flat structure. Separate active/ and completed/ folders, templates, pattern files. Over-engineered for AI collaboration.

Stage 2: Monolithic CONTEXT.md. Single context file per project, convention-based discovery, flat project folders. Worked well for short projects. Degraded over time as files grew to 500-1,000+ lines with no mechanism for information to leave.

Stage 3: Tiered context architecture (current). Working memory + reference + archive with lifecycle management. Budgeted at 150 lines. Applied to 60+ projects in production. No project exceeds budget.

Each stage was the right answer for its time. Stage 3 emerged from running Stage 2 across 60+ projects over several months and observing the degradation pattern firsthand.

---

Synthesis project management is part of synthesis engineering, an open methodology released to the public domain (CC0).

---

Rajiv Pant is President of Flatiron Software and Snapshot AI, where he leads organizational growth and AI innovation. He is former Chief Product & Technology Officer at The Wall Street Journal, The New York Times, and Hearst Magazines. Earlier in his career, he headed technology for Condé Nast’s brands including Reddit. Rajiv coined the terms “synthesis engineering” and “synthesis coding” to describe the systematic integration of human expertise with AI capabilities in professional software development. Connect with him on LinkedIn or read more at rajiv.com.