Throughline for long-running AI projects.
Seven files that establish a structured workflow for long-running, AI-assisted projects. The patterns here were developed over an extended production build with Claude.ai and Claude Code, then extracted into structured workflow templates for those tools.
This is scaffolding, not a product. Every template is meant to be adapted: filled in with your project's specifics, trimmed where sections don't apply, extended where your domain demands more. The inline guidance comments (in <!-- GUIDANCE: --> blocks) explain what each section does and what failure mode it prevents. Delete the comments as you fill in your content.
- Not a tutorial on using Claude.ai or Claude Code. It assumes you have a working project and basic familiarity with your tools.
- Not prescriptive. The templates reflect patterns that worked for one project. Your project may need different session types, different staleness rules, different skill boundaries. The structure transfers; the specifics are yours to define.
- Not free of overhead. This system has maintenance costs, project state updates, brief writing, periodic audits of memory edits and skills. The guide is honest about when those costs are worth it and when they aren't.
This system requires active maintenance. Project state files, memory edits, skills, and staleness tracking all need periodic review and updating. If you are not willing to invest that ongoing effort, the system will degrade and may create more problems than it prevents.
A note on what this guide can and cannot promise. Sessioncraft contains two types of guidance. The first is workflow discipline: session lifecycle, anti-staleness, handoff briefs, state packaging, governance friction diagnosis, the agreeableness problem. These patterns are tool-agnostic and durable. They apply regardless of how the underlying platform behaves and will survive model upgrades and feature changes. The second is platform-behavior assumptions: how memory edits interact with project instructions and skills, how skill trigger evaluation works, when context pressure degrades rule adherence, what precedence layers apply when rules conflict. These are derived from extensive observed behavior, not from Anthropic's documented specifications. They have held reliably across hundreds of sessions, but they are not guaranteed by the platform and may shift as Claude.ai and Claude Code evolve. Where this guide makes claims about tool behavior, verify them against Anthropic's current documentation. Where it makes claims about operator discipline, it stands on its own.
Sessioncraft is for solo operators building data-heavy or content-heavy products with Claude.ai and Claude Code, the kind of project where accuracy has real-world consequences, state accumulates across dozens or hundreds of sessions, and no one else is maintaining the system while you sleep.
- A project with enough complexity and longevity to benefit. If your project will last fewer than 20 sessions or so, involves a single file, and has no accuracy sensitivity, a lighter approach will serve you better.
- Access to Claude.ai with project knowledge, memory edits, and skills enabled.
- Optionally, Claude Code for file edits, builds, deploys, and git operations. The CLAUDE.md template is designed for the Claude.ai + Claude Code workflow, but the rest of Sessioncraft works for Claude.ai-only projects.
- Well-structured project foundations. This guide assumes your Claude.ai project instructions, project description, and project knowledge files are already well-structured and actively maintained. The governance system described here layers on top of those foundations; it does not replace them.
The Problem, Context Economy, Session Typing, The Session Lifecycle, Handoff Briefs, Anti-Staleness, When the Record Is Wrong, Governance Friction, The Agreeableness Problem, Breaking Protocol, Adopting Mid-Project, Growing the Project State, Multi-Tool Coordination, When This System Is Worth It, When to Simplify
Template sections: Project Summary, Context Economy Rules, Tooling, Custom Skills, On the Horizon, Session Log, Session Protocol. Includes Example A (session 10), Example B (session 25), and Example C (recovery from state drift, session 30).
Template sections: Project Summary, Architecture, Coding Conventions, Prohibited Patterns, Dynamic Over Hardcoded, Build Pipeline, Deploy Workflow, Context Management, Opportunistic Improvements, Git Workflow, Project Knowledge Sync. Includes Example A (session 10) and Example B (session 25).
Blank template with standard sections (Objective, Affected Files, Scope, Acceptance Criteria, Do Not, Cross-Section Dependencies, Stale PK Files, Risks). Includes a filled-in example using the RateRef project.
Categories: Identity and Role, Response Style, Workflow Rules, Tool Boundaries, Domain Constraints, Environment and Testing, Standing Deferrals, Volatile State. Slot Management.
Skill Anatomy, Blank Template, Example Skill (Source Verification for RegWatch), When to Create a Skill (decision narrative), Skill Lifecycle, Adapting This Example.
Read in this order for understanding. Note that the action order differs: most people will get the fastest return by creating a few memory edits (file 5) before filling in the full project state template (file 2), since memory edits are lower effort and higher immediate impact.
The conceptual foundation. Explains why the system is structured this way: context economy, session typing, the session lifecycle, anti-staleness, handoff discipline, and when the system is worth its overhead. Without this, the other files are forms without rationale.
The core artifact. This is the first file you create for your project, the living document that every session starts from. Sections cover project summary, context economy rules, tooling boundaries, horizon tracking, session logging, and session protocol. Fill in the sections that apply immediately; leave the rest as placeholders for when you need them.
Includes three filled-in examples for a fictional project: one at session 10 (sparse, early-stage), one at session 25 (mature, fully populated), and one at session 30 (recovery from a five-session gap in the project state). Together they show what growth, drift, and recovery look like in practice.
The context file for Claude Code. Everything it needs to operate without access to Claude.ai's project knowledge. Architecture, coding conventions, prohibited patterns, deploy workflow, context management thresholds. Skip this file entirely if you use a single tool.
Includes two filled-in examples matching the same fictional project: one at session 10 (sparse) and one at session 25 (mature), showing how the file grows as the project discovers its own constraints.
The brief template for transferring planning context into execution sessions. Includes the blank template with all standard sections and a filled-in example using the RateRef project (a data edit session re-verifying stale provider URLs). Use this alongside the Handoff Briefs section in SESSION-PROTOCOL-GUIDE.md, which explains the reasoning; this file provides the format.
Categories of memory edits with examples, guidance on when each category is worth a slot, and slot management practices. A reasonable starting point is three to five edits covering identity, response style, and your most important domain constraint. Add more as recurring problems demand them.
Skill anatomy, a blank template, a fully written example skill, a concrete decision narrative showing when and why to create a skill, and lifecycle guidance. Don't create skills on day one. Wait until you've repeated the same workflow rules in three or more sessions, that's the signal that a skill will pay for itself.
The most common mistake is building the full system on day one. Start with:
- A project state file with three sections: project summary, session log, and one or two session types
- Three to five memory edits: your role, your response style preferences, and your most important domain constraint
- No skills, no CLAUDE.md, no staleness tracking
This is enough for the first couple of weeks. Add structure only when a specific, recurring problem demands it.
Each piece of the system exists to prevent a specific failure mode. Add a piece when you experience the failure:
| Failure | Add |
|---|---|
| AI makes wrong assumptions about your role or project stakes | Identity memory edits |
| AI produces responses in the wrong format or tone after you've corrected it before | Response style memory edits |
| AI re-raises work you've intentionally deferred | Standing deferral memory edits |
| You re-explain the same workflow rules across multiple sessions | A skill encoding those rules |
| Execution tool misunderstands scope or reintroduces a known-bad pattern | CLAUDE.md with prohibited patterns |
| Data goes stale and you don't notice until a user reports it | Staleness tracking in project state |
| You lose track of which files are in project knowledge vs. on disk | PK inventory in project state |
| Handoff briefs are ambiguous and execution sessions waste time clarifying | Brief discipline rules in session protocol |
If you haven't experienced the failure, you don't need the fix yet.
If you're picking up Sessioncraft after experiencing the failures it prevents, see the "Adopting Mid-Project" section in SESSION-PROTOCOL-GUIDE.md for a cold-start checklist. The short version: start the governance system from your current session, write a few memory edits covering what you've been re-explaining, and resist the urge to backfill the entire session history.
First week. Project state file with summary, log, and basic session types. A few memory edits. You're learning your project's rhythms and what the AI needs to be told explicitly.
After your first context-loading mistake. You loaded a large file into a session that didn't need it and noticed degraded response quality, or the AI started conflating unrelated details. This is the trigger for context economy rules: documenting which files to load for which session types, and which files are too large for casual loading.
After your first state drift. You skipped a project state update, then spent a session debugging a problem caused by the AI acting on stale information. First skill created, probably for your most common editing or verification workflow. Staleness tracking added because something went stale and you caught it late. Session log has been archived once. Twelve to fifteen memory edits, audited once for redundancy.
At steady state. The system is mostly self-sustaining. New sessions start fast because the project state is accurate and context loading is disciplined. Skills cover the major recurring workflows. Memory edits are stable with occasional additions for new deferrals or volatile state. Most maintenance is routine: updating the session log, cycling the staleness registry, syncing project knowledge after deploys. Around this stage, your project state file may have grown large enough to warrant splitting. The session log archives to a separate file first, then domain-specific governance (source verification rules, deploy checklists, staleness registries) migrates into its own documents as sections become self-contained. The signal to split is when the project state file takes more than a few seconds to read at session start and contains sections irrelevant to most session types.
If your project state falls behind (the session log is five or more sessions stale, the horizon section references completed work, or the file inventory lists renamed files) dedicate one session entirely to recovery before resuming productive work. Read the git log or conversation history for the missed sessions, reconstruct the session log entries, update the horizon section, verify the file inventory, and confirm the deployed version. This session costs an hour but prevents compounding errors in every subsequent session. The longer you defer recovery, the harder it becomes, state reconstruction from memory degrades fast.
| File | Role | Words | Reading time |
|---|---|---|---|
| SESSION-PROTOCOL-GUIDE.md | Conceptual foundation (read first) | ~5,400 | ~36 min |
| PROJECT-STATE-TEMPLATE.md | Living document template with examples | ~4,300 | ~29 min |
| CLAUDE-MD-TEMPLATE.md | Claude Code context file with examples | ~2,900 | ~19 min |
| HANDOFF-BRIEF-TEMPLATE.md | Brief format with filled-in example | ~1,000 | ~7 min |
| MEMORY-EDIT-TAXONOMY.md | Memory edit categories and slot management | ~2,600 | ~17 min |
| SKILL-TEMPLATE-SET.md | Skill anatomy, template, example, and lifecycle | ~3,700 | ~25 min |
| README.md | This file | — | — |
First-read time and implementation time are very different. Expect to spend two to four hours adapting the templates for your project on the first pass, with refinements over subsequent sessions.
Terms used in this guide with specific meaning that may differ from common usage in the broader AI and developer ecosystem.
Context economy. The discipline of loading only what the current session requires into the AI's context window, and being deliberate about the choice. Related to but distinct from "context engineering," which focuses on what to put in the window. Context economy frames attention as a finite resource with a cost for every token loaded, including tokens that are merely irrelevant rather than wrong.
Session typing. The practice of defining a small number of recurring session patterns, each with explicit rules about what context to load and what the session is expected to produce. Not an established term; most practitioners do this informally without naming the practice.
Anti-staleness. A proactive discipline of tracking what data is current, what has exceeded its verification window, and what external triggers should prompt re-verification. The broader community uses "context rot" and "context drift" to describe the passive failure. Anti-staleness is the active prevention.
Governance friction. When the AI resists, loosely interprets, or ignores a rule you've established. The guide identifies three distinct causes (a poorly written rule, an overloaded context, or a genuine disagreement) each with a different fix. Treating all three as the same problem leads to the wrong remedy.
Standing deferrals. Items intentionally postponed that the AI should not re-raise unless asked. Without explicit deferrals, the AI will repeatedly suggest work you've already considered and decided to postpone, creating recurring friction across sessions.
Volatile state. Session-to-session facts (session count, deployed version, active cycle phase) maintained as memory edits because the AI's memory regeneration can't keep pace with how frequently they change. This category exists as a workaround for a current tool limitation and is expected to become unnecessary as memory systems improve.
Packaging. The third phase of the session lifecycle (orient, execute, package, handoff). Recording what happened (updating the session log, tracking fields, and output files) in the same session as the work, not in a future session. The guide treats deferred packaging as the single fastest path to state drift.
Context loading rules. Per-session-type definitions of which files to read into context and which to leave unloaded. A file that's essential for a data edit session may be irrelevant noise during a planning session. Loading rules make this explicit rather than leaving it to habit or guesswork.
Prohibited patterns. In the CLAUDE.md template, a section that documents specific approaches that were tried, broke something, and were reverted. The section only grows; entries are never removed unless the underlying architecture changes. Without it, Claude Code will rediscover the same failures.
Opportunistic improvements. A three-tier model for what to do when the AI encounters issues outside the current task's scope. Tier 1: fix and report (trivially correct, low-risk, adjacent to current work). Tier 2: flag only (real but requires its own scope). Tier 3: ignore (stylistic or unrelated). The tier boundaries are calibrated to the project's risk tolerance.
These patterns were developed during the construction of Emigrate.app, a free emigration research tool for U.S. citizens. The project's characteristics (legal-domain sensitivity, 167 programs across 79 countries, multi-tool workflow, quarterly data audit cycles, and a sole operator) drove the need for structured governance. Sessioncraft extracts the structural patterns without the domain specifics.
Sessioncraft is licensed under CC BY 4.0 (Creative Commons Attribution 4.0 International). You are free to share and adapt this material for any purpose, including commercial, as long as you give appropriate credit.
See LICENSE for the full legal text.
© 2026 Emigrate.app LLC · CC BY 4.0