Claude Code Workflow Starter

A clone-and-fill starter kit for running Claude Code using the 'control plane': a private
context repo that sits beside your projects and holds behavioural policy, per-project
state, and reusable runbooks — so every session starts with the same rules and the same
knowledge, instead of starting from zero.

Why

Claude Code is stateless. Every session starts fresh with no memory of previous work, no
knowledge of your systems and no awareness of what phase a project is in. Left unmanaged
it's a fast worker that guesses at context and makes confident mistakes and often makes the
same mistakes repeatedly because corrections don't persist between sessions.

These are infrastructure problems that can be helped (but not entirely solved) with infrastructure, not memory: policy files that load automatically, state files that survive between sessions, runbooks for repeatable procedures and hooks that enforce checks mechanically. That layer between you and the executor is the control plane.

System Pattern

• A global CLAUDE.md encodes how you want Claude to behave everywhere
  (global policy)
• A per-project PROJECT_CONTEXT.md records where each project actually is
  (state)
• A per-project CLAUDE.md records how to work in that repo (local policy),
• slash commands capture repeatable procedures like deploys and context updates
  (runbooks)
• hooks enforce checks automatically (validation).

All of it lives in one private git repo — project-context/ — beside your project directories, so it's
versioned, backed up and portable.

Directory Layout You're Building

~/Projects/
├── project-context/          # Private repo — the control plane
│   ├── global-claude.md      # Master copy of your global policy
│   ├── manifest.md           # Index of all projects
│   ├── <project>/            # One shard per project:
│   │   ├── CLAUDE.md         #   how Claude works in that repo
│   │   ├── PROJECT_CONTEXT.md#   current state of the project
│   │   └── specs/            #   planning docs (optional)
│   ├── commands/             # Slash commands (symlinked into projects)
│   └── hooks/                # Hook scripts + settings profiles
├── my-first-project/         # Your actual code repos
└── another-project/

Setup

1. Install Claude Code and download these files, put them where Claude Code can read them. Ask Claude to read the content and set everything up for you.

Or...

1. Create your private context repo. Copy this kit's contents into
   ~/Projects/project-context/, git init, create a private GitHub repo, push.
   Everything in here is your working notes — it should never be public.

2. Install the global policy. Fill in templates/global-CLAUDE.md (sections marked
   <!-- FILL IN -->), save it as project-context/global-claude.md, then copy or
   symlink it to ~/.claude/CLAUDE.md. Claude Code reads that file at the start of
   every session, in every directory.

3. Install the commands. Symlink the commands so they're available everywhere:

   mkdir -p ~/.claude/commands
   ln -s ~/Projects/project-context/commands/*.md ~/.claude/commands/
   

   You now have /new-project and /update-context in any session.

4. Onboard each project — new or existing — by running /new-project <name> in a
   Claude Code session. It interviews you, creates the context shard, wires up symlinks
   and hooks, and updates the manifest. For an existing repo it reads the codebase and
   drafts the context files from what's actually there.

5. Close every work session with /update-context. This is the habit that makes the
   whole system work: the context files only stay useful if they're updated when reality
   changes. State drift is the failure mode.

   NOTE: I define a 'session' as a single task/issue/job to be done. Despite the large context windows and increasingly clever models, 'updating context' and starting a new session per job to be done helps keeps the project context accurate and subsequent sessions spend less tokens reading mountains of code to get orientated with the project state.

The Public-Repo Trick

CLAUDE.md files often contain things you don't want public (infrastructure details,
candid notes, unreleased plans). For public repos: keep the real file in
project-context/<project>/CLAUDE.md, symlink it into the repo, and gitignore the
symlink. Claude Code follows the symlink; GitHub never sees the content. For private
repos you can commit CLAUDE.md directly or still use the symlink for consistency.

Rules of the Road

• Context files track current state, not history. Git log is the changelog. If a
  section describes what happened rather than what is, delete it.
• Encode lessons as policy. When Claude makes a mistake you had to correct, have it add a
  rule to the relevant CLAUDE.md so it helps reduce reoccurrence.
• Specs before implementation. Plan in whatever tool you think best in (Claude web, ChatGBT
  a whiteboard, whatever), land the result as a spec in the project's context directoy, then point
  Claude Code at the spec. "Implement the spec" beats re-explaining every detail at the start of a session.
• Surgical updates only. /update-context touches only sections the session
  changed. Rewriting whole files churns git history and invites drift.

What's in This Kit

Everything here is a starting point. Delete what doesn't fit and adjust as needed.

Have a lot of fun :)