Laurence
031074c9a9
Bootstrap of the project (M0). Sets up the monorepo, design docs, hardware BOM, the open API contract, component skeletons, licensing and CI, following the Default Workflow SOP. What changed: - CLAUDE.md + docs/: copied the Default Workflow so sessions load the SOP. - state/: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES filled in for OpenScribe. ARCHITECTURE captures the four-part design (firmware, server, app, case) and the three sync paths; DECISIONS records the hardware, AI-stack, storage, app and licensing choices; TODO lays out milestones M1-M9. - hardware/BOM.md: two build options (compact XIAO ESP32-S3 Sense; dev ESP32-S3 + I2S mic + SD), wiring/pinout, indicative cost. - api/openapi.yaml: the completely open API (device + server surfaces), including recording list/download/delete and exports (wav/ogg/txt/srt/vtt/md/json). - firmware/: PlatformIO ESP32-S3 project, two board profiles, pin map, boot scaffold with module seams for M1-M4. - server/: FastAPI skeleton mirroring the OpenAPI, config for self-hosted MinIO, faster-whisper and Ollama; stub routes browsable at /docs. - app/, case/: Flutter app plan; parametric OpenSCAD enclosure. - Licensing: GPL-3.0 (code), CERN-OHL-S-2.0 (hardware), CC-BY-SA-4.0 (case/docs), REUSE-style LICENSES/ with SPDX headers; LICENSING.md explains the split. - CI: Forgejo Actions workflow builds firmware (both profiles) and lints/imports server. Why: - Everything self-hosted and openly licensed per the user's requirements: an open API, three sync paths (BLE control, WiFi transfer, independent WiFi upload on charge to generic cloud storage), and a full self-hosted transcription+summary stack. Notes: - No custom PCB in v1; off-the-shelf modules. Physical verification waits on parts. - Component code is stubs at M0; features land milestone by milestone, each as its own branch/PR per the workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
# 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
|