Synthesis Project Management

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.

Updated: April 27, 2026: This article now reflects cross-agent support for Claude Code and OpenAI Codex. The system works when project memory lives in CONTEXT.md, REFERENCE.md, and session archives rather than inside a single assistant session.

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
                             # (top-level, peer to projects/ — see note below)
└── YYYY-MM-DD-*.md          # Date-prefixed for discoverability

daily-plans/                 # Person-scoped daily action plans
                             # (top-level, peer to projects/)
└── YYYY-MM-DD.md            # One file per day

Note on the folder layout (updated 2026-04-22): Earlier versions of this article placed lessons/ (underscore-prefixed) inside projects/. That underscore-prefix convention was refined in April 2026: lessons/ and daily-plans/ are now top-level peers of projects/, without the underscore. Both are cross-project by nature, not sub-components of projects, so the flat layout is more honest. The underscore served as a sort-to-top visual cue inside projects/; at top level the distinction is unnecessary.

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.
Top-level lessons/ (peer to projects/)	Cross-project meta-knowledge isn’t a sub-component of any project. Top-level layout reflects semantic equality.
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 wait.

AI Assistant Integration

Add to your CLAUDE.md, AGENTS.md, or equivalent agent instruction file:

## 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.

For Claude Code, keep this in CLAUDE.md. For Codex, keep the same operating rule in AGENTS.md. The assistant-specific file provides procedure; the project state remains in shared files any capable agent can read.

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.

The same structure now works across Claude Code and Codex. It also works across computers when the project knowledge repo is synced through private git: start work on one machine, continue on another, and let the agent reload the project state from the repo instead of from a fragile chat transcript.

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
Waiting until “session end”	Forget to update	Update immediately
Not checking lessons/	Repeat mistakes	Grep at session start

Teams: Multiple Humans, Multiple AI Assistants, Multiple Workstations

The system scales. When Alice’s AI works on auth Monday, Bob’s AI knows about it Tuesday. When one person moves from Claude Code to Codex, or from a desktop to a laptop, the project memory moves with the repo.

Shared knowledge artifacts:

• CONTEXT.md files in shared repos
• Lessons learned in central location
• Semantic indexes spanning the team
• Session archives that any agent can inspect when deeper history matters

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 and instruction surfaces. Claude Code has MEMORY.md and CLAUDE.md, ChatGPT has persistent memory, Codex uses AGENTS.md, and Gemini has conversation history. Synthesis project management is independent of and coexists with all of them.

The distinction: tool-native memory is automatic or tool-specific. Synthesis project management is deliberate, tool-agnostic, and structured. CLAUDE.md and AGENTS.md tell an assistant how to work. CONTEXT.md, REFERENCE.md, and sessions/ store what is true about the 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). If you use Codex, you’ll have AGENTS.md (Codex’s instruction surface) and CONTEXT.md (your project state). In both cases, the durable memory belongs with the project.

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, AGENTS.md, or equivalent agent instruction file.
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 Agent Skills (formerly runbooks):

• synthesis-project-management — the project management system
• synthesis-context-lifecycle — 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).