# Default Workflow

This file is the entry point for any Claude Code session working under the Default
Workflow. Keep it small and read the detailed docs on demand so a session does not
load everything at once (see [Cost and tokens](docs/cost-and-tokens.md)).

## What this is

A standard operating procedure for building software with Claude Code. It defines how
a project is set up, how features are branched, committed, reviewed and merged, how
documentation is produced, and what the user expects. Copy this workflow into a new
project (see [Project setup](docs/project-setup.md)) and follow it.

## The five rules

1. **Minimise cost.** Staying within usage limits matters more than speed. Prefer
   cheap actions over expensive ones. Read only what you need. See
   [Cost and tokens](docs/cost-and-tokens.md).

2. **State lives in the repo, not the chat.** Do not rely on chat history, context, or
   cache to remember decisions, todos, notes, architecture, or objectives. Write them
   to the committed markdown files under `state/` so a fresh session can pick up with
   no prior context. See [Documentation policy](docs/documentation-policy.md).

3. **Every feature is a branch.** Create a branch, commit with full notes in each
   message, open a PR describing the feature, the tools used and what was achieved,
   then merge into the trunk. See [Workflow](docs/workflow.md).

4. **Code and its documentation are written in separate sessions.** The building
   session comments the code well enough that a later, cold session can write the docs
   from git history and comments alone. See [Documentation policy](docs/documentation-policy.md).

5. **Comment for a stranger.** Assume the next session has no memory of why you did
   anything. The commit history and code comments are the only record.

## Start of every session

1. Read `state/PROJECT.md`, `state/TODO.md` and `state/DECISIONS.md` (cheap, small).
2. Check `git log --oneline -15` and `git status` to see where things stand.
3. Do the work under the rules above.
4. Before ending, update the `state/` files so the next session needs no chat history.

## Detailed docs

- [Project setup](docs/project-setup.md) - starting a new project on this workflow
- [Workflow](docs/workflow.md) - branch, commit, PR and merge process
- [Cost and tokens](docs/cost-and-tokens.md) - keeping usage within limits
- [Documentation policy](docs/documentation-policy.md) - comments, and docs in a separate session
- [User expectations](docs/user-expectations.md) - how the user wants Claude to behave