workflow

workflow is an MIT-licensed template for keeping Claude Code work accurate across sessions, machines, and long-running projects. Instead of trusting a handoff note by itself, its /session-start and /handoff skills run the same ground-truth.sh script against local Git state, remotes, open pull requests, CI, and supported background jobs. The note remains useful, but it is explicitly treated as a claim that can be checked.

How the workflow works

The repository separates short-lived coordination from durable project memory. notes/handoff.md is rewritten at the end of a session, while its archive preserves prior handoffs. BACKLOG.md holds unfinished work, questions.md records decisions that require an owner, and notes/lessons.md keeps recurring mistakes visible to later sessions. A configuration file identifies the repositories and branches whose remote state matters.

• Ground-truth start: /session-start compares the latest note with Git, remotes, PR status, CI, and applicable jobs before proposing a task.
• Ground-truth handoff: /handoff runs the same check before rewriting the current handoff and trackers.
• Project and workspace modes: It supports a single repository or a documentation-only workspace that tracks several repositories.
• Safe adoption: bin/adopt.sh copies only missing template files and reports skipped files rather than overwriting project content.
• Cross-platform shell workflow: The project documents macOS, Linux, and Windows use through Git Bash or WSL.

A practical setup

Clone the repository, then run workflow/bin/adopt.sh with the project root. Fill the repository list in .claude/ground-truth.conf, run the checker until it reports complete ground truth, and add project-specific rules, backlog items, and owner decisions. Run one /handoff to create the first verified state. On the next workday, start with /session-start and review discrepancies before assigning implementation work.

Where it helps

The template is most useful for teams or solo developers who return to a repo after CI changes, background jobs fail, branches remain unpushed, or several agents touch related work. Its key distinction is not a larger prompt file; it reconciles notes with observable repository state. This makes it a complementary option to Planning with Files and Subagent-Driven Development.

Limits and alternatives

The scripts only know what you configure and what their integrations can read. GitHub CLI and systemd are optional, so unavailable checks should remain unknown rather than be treated as passing. The template also installs Claude Code-oriented skills, so other agent runtimes need adaptation. If you want a different execution style, compare Executing Plans Skill.

Getting started

Read the official README, inspect the template before copying it, and keep the generated project-specific notes under your own source-control and access rules.