# 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. Subagents and parallel
   processing are allowed when they are the effective path (see
   [User expectations](docs/user-expectations.md)). 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