Synthesis Project Management

Synthesis Project Management System

A lightweight project management system designed for human-agent collaboration. Optimized for context preservation across conversation sessions and context compaction events.

Configuration

These values are user-specific. Update them for your environment.

Design Principles

1. Discoverability over documentation — Agents can search/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 obsolete. To create something new, examine an existing example and adapt it. Agents excel at this.
6. Coordinate before concurrent writes — Separate root sessions share a session registry and message board outside the repositories they edit. Every session reads it, registers its project, claims its write areas, and records its isolated worktree before editing.
7. One context owner per project — Parallel sessions may contribute to one project, but only one session writes canonical project context. Other sessions write isolated contribution artifacts for deterministic reconciliation.

Problem This Solves

When working with AI assistants on multi-session projects:

• Context compaction (conversation summarization) loses detailed progress
• Session boundaries create information gaps
• Tool switching between Claude Code, Codex, Cursor, and other agents can strand context in tool-specific transcripts
• Multiple projects create confusion about current state
• Parallel root sessions can edit the same repository without seeing each other's in-flight state
• Lessons learned get lost instead of compounding

This system provides persistent state that survives context loss. The project files are the durable memory layer: chat history, model memory, and compaction summaries are helpful but insufficient. A user should be able to pause in one capable agent environment, open the project in another, and continue. A tool's built-in per-project memory is not a substitute — it is single-tool, single-machine, and not version-controlled (full argument: references/records-and-conventions.md).

System Architecture

All project management lives in one location within your ai-knowledge workspace:

ai-knowledge-{workspace}/
└── projects/
    ├── index.yaml               # Single index for ALL projects (status field, not folders)
    │
    ├── {project-id}/            # Project folders (flat structure)
    │   ├── CONTEXT.md           # Working memory — active state (budget: ≤150 lines)
    │   ├── REFERENCE.md         # Semantic memory — stable facts (updated in place)
    │   ├── sessions/            # Episodic memory — archived session logs
    │   │   └── YYYY-MM.md       #   Monthly files
    │   ├── README.md            # Static documentation (optional)
    │   └── resources/           # Project data and artifacts (optional)
    │       ├── in/              # Inputs
    │       ├── artifacts/       # Working data
    │       ├── out/             # Outputs
    │       └── scripts/         # One-off scripts
    │
ai-knowledge-{workspace}/
└── lessons/                    # Cross-workspace lessons (top-level, no underscore, ADR-017)
    └── YYYY-MM-DD-*.md         # Date-prefixed for discoverability

Key Structural Decisions

Project Naming

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 stating the finish line: migrate-blog-to-astro, release-kb-company-wide. With the outcome in the name, "is this done?" answers itself and zombie projects show on sight.
• Ongoing projects (ongoing status — operations seats, stewardships) keep noun names for the thing being stewarded (payments-platform); there is no finish line to state.

Generic verbs are banned (do-, work-on-, handle-, manage-, run-, support-): the verb must name the specific outcome, and when no specific verb fits, the project is probably ongoing or needs splitting. Existing projects keep their names — renames churn paths and history for no behavioral gain; status, not the name, is the machine-readable field. Full rationale: references/records-and-conventions.md.

Components

1. Project Index (index.yaml)

Discovery index for all projects. Status is a field, not a folder: active (being worked), paused, ongoing, completed, or archived.

projects:
  - id: migrate-blog-to-astro        # bounded → verb-first outcome name
    name: Migrate Blog to Astro
    status: active
    description: Brief description of what this project accomplishes
    tags: [tag1, tag2]

Full multi-status example: references/records-and-conventions.md. Update when: project status changes or a project is added. For structured projects, derive session currency; a present stale last_session is evidence, not truth. One confined resolver also binds parent plans into state hashes. Details: references/project-state-recovery.md.

2. Tiered Context Architecture

Projects use a three-tier context system that separates information by lifecycle. This prevents unbounded growth of context files and keeps AI collaborators effective across long-running projects.

Detailed documentation: See the synthesis-context-lifecycle skill for templates, migration guides, decision trees, and quality metrics.

The three tiers:

Archival protocol: At session start, if CONTEXT.md exceeds 120 lines: archive completed tasks and old session logs to sessions/, move stable facts to REFERENCE.md, verify content exists in destination, then remove from CONTEXT.md. Archive FIRST, delete second — two-phase commit.

3. Lessons (lessons/)

Cross-project mistakes, insights, and patterns, one folder, date-prefixed files (YYYY-MM-DD-topic-slug.md). Incidents carry type: incident front matter with What Happened / Root Cause / Impact / Lesson / Prevention; generalized insights carry type: pattern with Context / Problem / Solution / Examples. Full format blocks: references/records-and-conventions.md. Update when: immediately when you learn something reusable.

4. Agent Attribution

When multiple agents contribute materially, the session log carries provenance: one italic *Attribution — agent: … · model: … · effort: … · scope: … · verified: … · ref: …* line per contributing agent at the end of the entry. Record model/effort only when explicitly provided — otherwise the literal word unknown, never inferred; verified names only checks that actually ran; never record secrets. Attribute only when it helps future work. Full rules and the canonical convention: references/records-and-conventions.md and the synthesis-context-lifecycle skill.

The Protocol

During Work

Complete task → Update CONTEXT.md → local receipt → Next task

NOT: task → task → task → (context compaction) → lost details.

Session Start

1. Read the coordination board — If ~/.synthesis/coordination/active-sessions.md exists, read it before any write and register or refresh this session's project, worktree, branch, context role, and claims
2. Resolve before reading — Run scripts/project_state.py resolve against the Git-tracked index with --no-fetch --no-coordination-refresh and GIT_OPTIONAL_LOCKS=0; use only its causally selected state. A failed or conflicting selection stops dependent project reads/writes, including build and migration.
3. Read the selected state — Read CURRENT_STATE.json when present, CONTEXT.md, the linked plan, REFERENCE.md, and latest session; validate the available hashes and semantics. Absence of structured state does not authorize a migration.
4. Check line count — If CONTEXT.md >150 lines, archive before starting work
5. Search lessons/ — Search for relevant past experiences.
6. Check related projects — Look at related: tags in index.yaml.

Session End

1. Final CONTEXT.md update — Ensure all sections current (≤150 lines)
2. Archive if needed — Move old sessions to sessions/, stable facts to REFERENCE.md
3. Attribute if warranted — If multiple agents/models contributed materially, end the session-log entry with Attribution line(s) (see Agent Attribution)
4. Refresh adopted structured state — For a project already using CURRENT_STATE.json, regenerate it and its compiled block after each meaningful source phase. Prose-only projects retain their context protocol; checkpoint commands report non-applicability only after verifying state was never adopted.
5. Verify local continuity — Confirm this native session's attributed state is readable and its local handoff is ready. Structured projects additionally require their session- and claim-bound Stop receipt. NOT_APPLICABLE does not certify pending edits. Do not create a commit or network push solely because the user is switching clients on this machine.
6. Release coordination claims — Mark the session released or narrow its claims before pausing. Existing-row mutations require the actual claiming seat. A typed administrative reason, failed caller-ownership check, app closure or age is not operator authorization to release another or an unbound active seat.

For an explicitly requested refresh-and-report pass, use the current installed synthesis-checkpoint mode. It inspects and reports without project edits, state generation, activation or claim acquisition; normal record-owner closure above applies only to work actually written under accepted authority. An unclaimed session inspecting a discovered structured project, with valid native identity, no exact-session pending edits and a clean Git subtree, can finish with NOT_APPLICABLE; this issues no receipt and proves neither successful recovery nor execution authority. An exact-session source-only manifest may also remain after a completed local pause. Stop verifies the complete local receipt against committed files, Git identity and current attribution before accepting observer non-applicability; it preserves the manifest and grants no checkpoint or publication authority. Unresolved evidence remains explicit; see the checkpoint refresh reference for failure termination and client-specific behavior. For identity mismatches and stranded attribution, follow checkpoint closure recovery. A Stop diagnostic identifies an obligation; it does not authorize unrelated repair.

Cross-Agent Session Coordination

Durable project files solve handoff across time; they do not prevent two live root sessions from writing the same files at once. Concurrent Claude Code, Codex, Cursor, or other root sessions share the coordination board at ~/.synthesis/coordination/active-sessions.md — outside any repository a session may restructure. Schema v4 rows carry: canonical UUIDv7 plus compact and speakable aliases (and any legacy mapping), agent, machine, the client session ref (client-native delivery handle, registered automatically at claim), project, start/heartbeat, mode, isolated worktree/branch pairs, goal, claimed area globs, context role, and status; ## Messages is the append-only addressed bus, ## Protocol the human-readable rules.

Use scripts/coordination.py for atomic, file-locked updates:

# Review claims that have gone quiet (reports only; never mutates)
python3 <synthesis-project-management-root>/scripts/coordination.py stale

# Read before writing
python3 <synthesis-project-management-root>/scripts/coordination.py status

# Claim one or more source areas
python3 <synthesis-project-management-root>/scripts/coordination.py claim \
  --agent "OpenAI Codex" --project example-project \
  --mode autonomous --context-role owner --goal "Cross-client conformance" \
  --workspace "/tmp/synthesis-skills-b @ feature/cross-client" \
  --area "synthesis-skills/**" --area "ai-knowledge-*/projects/**"

# Refresh the lease timestamp at every checkpoint
python3 <synthesis-project-management-root>/scripts/coordination.py heartbeat \
  --session s-6adk-06yc-yqb2

# Verify the current index against this session's exact board claim
python3 <synthesis-project-management-root>/scripts/coordination.py \
  check-staged --session s-6adk-06yc-yqb2 --repository /path/to/worktree

# Resolve a peer: exact address per lane + the receipt the send gate matches
python3 <synthesis-project-management-root>/scripts/coordination.py resolve \
  --to example-project --role owner

# This shell's identity, seat, and lanes; unread bus messages for its seat
python3 <synthesis-project-management-root>/scripts/coordination.py whoami
python3 <synthesis-project-management-root>/scripts/coordination.py inbox --mark-read

# Leave a handoff (--to must resolve; --free-address records exceptions; --durable for handoffs future seats must receive: references/project-durable-delivery.md)
printf '%s\n' "Source checks pass; live install awaits authorization." |
  python3 <synthesis-project-management-root>/scripts/coordination.py message \
    --from s-6adk-06yc-yqb2 --to crater-sunset-alone-okay-23907

# Release every claim at session end
python3 <synthesis-project-management-root>/scripts/coordination.py release \
  --session s-6adk-06yc-yqb2

claim allocates the identity and prints all three exact forms (UUID, compact, speakable); any form selects the session, letters like AX are migrated legacy aliases, and claims are the --area resource paths. Bit layout and lookup contract: references/session-identity.md. Check-staged selector precedence and override recording: references/parallel-agent-protocol.md ("Commit authority").

Rules:

1. Read at SessionStart and every synthesis checkpoint.
2. Claim before write. Claim the smallest coherent area currently needed before creating a branch or editing; exact files suit independent edits, directories suit coordinated multi-file work. Expand an accepted claim before extra writes; do not reserve speculative future work. Name the synthesis project across repos. See claim scope over the task lifecycle.
3. Do not write through overlap. If a claim conflicts, stop writes in that area and use the message log or the user to sequence work.
4. Share checkouts only with disjoint areas. Same worktree/branch is allowed when claimed areas are disjoint (banner names who is there); same-file work needs isolated worktrees, and sharing seats commit only their own paths.
5. One context owner. A project has one owner session for CONTEXT.md, REFERENCE.md, sessions/, its controlling plan, and projects/index.yaml. Same-project contributor sessions claim non-overlapping implementation areas and write their result to a session-specific contribution artifact. The owner verifies and reconciles those artifacts into canonical context.
6. Autonomous claim keeps priority. When an autonomous and interactive session overlap, the autonomous session keeps its existing claim; the interactive session yields unless the user explicitly reorders them. Exception: idle-holder paths narrow administratively under the receipt (request-narrow and escalation).
7. Direct sends need a receipt; addresses are resolved, never guessed. resolve issues a delivery receipt for one target; the plugin's gate admits a direct send only at that exact address, re-verified live. Names, titles, and [ref] labels are never addresses; the message carries your board id; the same text to a second peer is a refused broadcast. The bus reaches the addressed seat at its next prompt: unresolvable means bus.
8. Heartbeat, narrow and release explicitly. At checkpoints and task/phase changes, refresh the heartbeat, review scope and promptly release completed areas. Quiet past the stale threshold, a row is ADVISORY: no blocking, grants on the bus; heartbeat to re-assert, narrowing first on collision. stale reports quiet claims. Session IDs are addresses: own-seat mutations require that seat; admin release needs explicit authorization and recorded reason.
9. Advisory does not mean optional. The filesystem cannot stop every tool, so the protocol and checkpoint hooks make the shared obligation visible.

The script uses an OS file lock, verified backups, and atomic replacement, and refuses overlapping areas, duplicate context owners, and contributor claims on canonical context. Sharing one checkout with disjoint areas is granted with a banner. Cross-machine simultaneity requires the git-backed lease (compare-and-swap on a shared remote, fail-closed when unreachable); retire merged worktrees with scripts/retire_worktree.py, never by hand. Board file shape: references/active-sessions-template.md. Lease bootstrap and retirement, worktree-retirement mechanics, peer addressing, digests, administrative release, and canonical landing: references/parallel-agent-protocol.md, references/canonical-landing.md.

Cross-Agent Handoff

Before pausing work that may continue in another tool, the outgoing agent runs this protocol automatically. The principal does not invoke lifecycle commands or save state by hand:

1. Update CONTEXT.md with current state, decisions, and next actions
2. Move stable facts into REFERENCE.md
3. Append chronological detail to sessions/YYYY-MM.md
4. End the session-log entry with an Attribution line for the departing agent (see Agent Attribution) — the receiving agent should know who did what, with what verification
5. Save substantial plans, audits, or checklists under resources/artifacts/
6. Verify LOCAL_READY or LOCAL_RECOVERABLE; a same-machine client switch does not require a commit, push, or manual lifecycle command
7. If synthesis-agent-conformance is installed, run its activate, pointer, and continuity --readiness local commands for the project
8. When changing computers, run synthesis-mac-sync remote-handoff mode, then verify continuity --readiness remote. Day-end performs the same transition.
9. Release or transfer this session's coordination claims. Normal release recoverably archives its session's active-project pointer; another session's pointer is untouched. Normal release is caller-bound; administrative release is distinct and audited.

A cross-session merge or fast-forward request names the target head it was tested against (fast-forward clean as of main=<sha>); the receiver re-runs git merge-base --is-ancestor <current-target-head> <source-head> against the target's current head, not the named sha, before acting, and any advance of the target since the named head invalidates the claim.

Resuming from another agent: run scripts/project_state.py resolve against the Git-tracked index before reading prose. Divergence is CONFLICT; unreadable or unreachable evidence is UNKNOWN. Full evidence, ordering, safe-fast-forward, and receipt contract: references/project-state-recovery.md. Pointer semantics and cross-computer recovery preconditions: references/parallel-agent-protocol.md ("Resuming and the active-project pointer").

The Handoff Queue — Work Transfer Between Agents

The protocol above hands a project's state between tools. When two root sessions collaborate on one project, the work item itself also needs a transport that is not the principal's clipboard. scripts/handoff.py is that transport:

handoff.py write --to codex --from claude --file prompt.md [--round N]
handoff.py read  --as codex          # oldest pending addressed to me
handoff.py list                      # full queue, both directions
handoff.py done  --id h-XXXXXXXXXX   # close a claimed handoff

Two rules keep this supervised:

• Nothing self-triggers. An agent reads the queue when the principal, or a coordination-board message the principal's protocol allows, says the other side is done. Announce every write with coordination.py message (the script prints the exact command). Supervision by exception is the point; unattended is not uncontrolled.
• The queue is one of two directions. It moves work between agents. Decisions between agent and principal travel as a decision packet (synthesis-decision-packet). Together they remove the principal as the transport layer while leaving every crossing visible in the project.

Payload integrity (sha256-pinned files, atomic queue writes, refuse-to-guess reader identity): references/parallel-agent-protocol.md ("Handoff queue mechanics").

Parallel Sub-Agent Dispatch

Fan-out to multiple sub-agents working the same project concurrently — a batch of parallel repo migrations, a multi-agent reorganization run, several research tasks feeding one project — is now a common pattern, not an edge case. Two risks are specific to concurrent writers and aren't covered by the sequential protocols above.

Git-index collisions. When more than one agent (or background process) can commit to the same repo in the same window, git add <your files> followed by a bare git commit does not commit only what you just added — it commits everything currently staged, including anything another agent staged first. git add extends the index; it does not replace it. Before every commit in a repo where concurrent writers are plausible, run git status --short and git diff --cached --name-only first, and commit only the paths this invocation intends (git commit -o <paths>, or unstage what isn't yours). Treat this as a mechanical prefix to the commit step, not a judgment call reserved for commits that "feel risky" — the risk lives in what might already be staged, which by definition isn't visible without looking first. (General git-mechanics and repo-scoping rules live in synthesis-context-lifecycle's Commit Protocol; this is the one addition specific to concurrent writers in the same repo.)

Tracking-doc aggregation. A sub-agent dispatched against its own slice of a project — its own repo, its own batch — correctly leaves its siblings' in-flight work alone. That discipline has a side effect: no single agent sees the combined result. A shared tracking doc (CONTEXT.md, index.yaml) updated only by whichever agent happened to touch it last will under- or overstate what the batch actually accomplished. After any parallel dispatch, the orchestrator — not an individual sub-agent — reads every report as a set, reconciles them, and updates CONTEXT.md/index.yaml to reflect the true combined state.

Sub-agents spawned by one orchestrator remain governed by that orchestrator. Independent root sessions use the cross-agent coordination board above; do not mistake a shared git worktree or shared chat history for coordination.

Dispatching to Codex — use the wrapper, never bare codex exec

scripts/codex_dispatch.py is the supported path for sending a prompt to Codex non-interactively:

python3 scripts/codex_dispatch.py --doctor
python3 scripts/codex_dispatch.py --prompt-file brief.md --out review.txt --report-only

It removes three production-observed failures: the silent stdin hang (stdin=DEVNULL always), stalls indistinguishable from work (it watches output growth, not elapsed time), and the false "Codex is unavailable" (--doctor resolves the binary and proves authentication — never report Codex unreachable without running it). Incident detail: references/codex-dispatch.md.

File Requirements by Project Status

Resuming a paused project carries the highest scope-drift risk of any status — see the scope re-verification step in Project Discovery below before dispatching work against one.

Project Discovery

When a user mentions a project:

1. Read projects/index.yaml
2. Match user's phrase against project name, description, id, tags
3. Check the match against the session's own context before switching. A session usually carries project evidence of its own: the conversation's established project, the session name, the active-project pointer, the working directory. When the named project contradicts that evidence, surface the contradiction and ask ("This session has been working project Y — did you mean X, or should this stay in Y?"); never silently resolve to the name. Names are typed by humans navigating many similarly-named projects, so a name is one signal, not an override; a silent wrong resolution sends a full session's work to the wrong project's records (this happened on 2026-08-20). Resolve without asking only when name and session evidence agree, or when the session carries no project evidence at all.
4. If matched (and confirmed where step 3 required it), resolve through the Git-tracked registry with scripts/project_state.py resolve --no-fetch --no-coordination-refresh and GIT_OPTIONAL_LOCKS=0 before reading project prose. Do not request automatic fast-forward for a local checkpoint. CONFLICT/FAIL/UNKNOWN stops dependent reads and writes; preserve the candidate evidence instead of running build or migration to silence the result. For a selected project, run the context-lifecycle Session Start Protocol.
5. Summarize current state and next steps
6. Re-verify scope before dispatching work, especially for a paused project. CONTEXT.md's "N items remaining" (or any count a plan document asserts is current) is a claim made at write time, not a live query — it goes stale the moment anything else touches the same corpus, even a workstream that has nothing to do with this project and doesn't know it exists. Before batch-dispatching agents against a stated scope, re-derive it from live state with a cheap direct check (find, grep, wc -l against the actual files or repos) rather than trusting the document's count. This is cheapest immediately before dispatch — the highest-leverage moment to catch drift, before agent-hours are spent at the wrong scope — and it applies even within a single session, since a count computed early in a long run can go stale by the time a later phase acts on it. If the recount disagrees with the document, update the document in the same pass rather than silently working around the discrepancy. (Distinct from context-lifecycle's Session Start Protocol, which verifies CONTEXT.md's own freshness against this project's git log — that catches a stale file; this catches a stale scope claim that can drift even when the file itself looks current.)
7. Begin work from where it left off

Common Mistakes