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.

Updated: July 21, 2026: Added the project naming convention — bounded projects get verb-first outcome names; ongoing projects keep noun names. See Project Naming.

Updated: July 22, 2026: Revised Tool-Native Memory Is Not a Substitute below. Real-world use surfaced structural reasons a tool’s built-in memory isn’t a durable substitute for this system, not just a stylistic preference — see the updated section, and the full worked audit that prompted the revision.

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: migrate-blog-to-astro    # bounded → verb-first outcome name
    name: Migrate Blog to Astro
    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.

Project Naming

(Added July 2026.) Project id slugs are read every day — in the index, in directory paths, in editor and window titles. After running this system across 60+ projects, a naming convention earned its place. Two rules, keyed to whether the project has a defined end state:

Bounded projects — ones that will someday reach completed — get verb-first outcome names. The name states the finish line: migrate-blog-to-astro, accept-vendor-contract-2026-03, release-kb-company-wide. When the outcome is in the name, “is this done?” answers itself, scope gets declared at creation time, and zombie projects — bounded work that sits active in the index for months because nothing in its name says what done means — become visible on sight. This is the same insight behind GTD’s outcome-defined projects and OKR objective phrasing, applied to the slug your tools show you fifty times a day.

Ongoing projects — operations seats and product stewardships with ongoing status — keep noun names. They name the thing being stewarded (payments-platform, workspace-operations) because there is no finish line to state. Time-boxed instances of a standing role (platform-2026-q3) already carry their end in the date suffix; wrapping them in a generic verb (do-platform-2026-q3-work) adds ceremony, not information. Software teams already live this split: branches — bounded change — get verb-ish names (fix-login-timeout), while repositories — ongoing things — get noun names. Nobody names a department “do-operations-work.”

Generic verbs are banned. do-, work-on-, handle-, manage-, run-, support- say nothing — every project is doing work. The verb must name the specific outcome. That constraint makes the rule double as a classification diagnostic: if you cannot find a specific verb for a project, it probably is not bounded — model it as ongoing, or split it until concrete outcomes emerge.

Existing projects keep their names. Renames churn paths, cross-references, and history for no behavioral gain. The convention applies to projects created after adoption; a mixed index is expected and harmless, since status — not the name — remains the machine-readable lifecycle field.

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.

Tool-Native Memory Is Not a Substitute

Some AI tools have their own memory and instruction surfaces. Claude Code has auto-memory (a MEMORY.md index plus topic files, separate from CLAUDE.md) and ChatGPT has persistent memory; Codex uses AGENTS.md as an instruction surface, and Gemini has conversation history. These are genuinely useful within a single tool, on a single machine, for a single session’s worth of context.

They are not a substitute for this system, for three structural reasons: single-tool (a memory file your tool writes for itself is invisible to every other agent you use), single-machine (these features are typically scoped to the machine they run on, with no built-in sync — work on a second machine and the memory starts over from zero), and not version-controlled (without git, there’s no history, no diff, and no recovery from a bad write). CLAUDE.md and AGENTS.md tell an assistant how to work — that instruction layer is genuinely separate from project memory and both this section and the rest of this article treat it as such. Tool-native memory — the notes a tool writes about what it learned, not the instructions you wrote — is the part that isn’t durable.

Note on this section (revised July 22, 2026): an earlier version described tool-native memory and synthesis project management as coexisting, serving different purposes, with neither replacing the other. That framing undersold the gap. A real audit of one Claude Code auto-memory directory turned up dozens of files scattered across every project scope the machine had touched — genuinely useful in the moment, invisible to any other tool, gone if the machine changed, unrecoverable if a bad write happened, since there’s no version history. The full audit walks through what was found and what to do about it. If your tool’s native memory can be disabled or redirected, doing so and routing that content into CONTEXT.md, REFERENCE.md, and lessons/ instead avoids maintaining two parallel, drifting records of the same work.

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