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>
2.1 KiB
Project setup
How to start a new project on the Default Workflow. Do this once, at the beginning of a project, before any feature work.
1. Create the repository
- Create an empty repo on the forge (git.discworld.casa or wherever the project lives).
- Clone it, or
git initlocally and add the remote. - The trunk branch is
mainunless the forge defaults tomaster; either is fine, be consistent and refer to it as "the trunk" in docs.
2. Copy the workflow files in
From this Default-Workflow repo, copy into the new project root:
CLAUDE.md- so every session loads the workflow automatically.docs/- the detailed workflow docs (or link to them if you prefer one source of truth; copying keeps the project self contained and offline readable).templates/*intostate/(see next step).
3. Create the state directory
The state/ directory is the project's memory. It replaces chat history. Copy the
templates and fill in the project specifics:
state/
PROJECT.md - objectives, scope, description, who it is for
ARCHITECTURE.md - how the system is built and why
DECISIONS.md - dated log of decisions and their rationale
TODO.md - what is done, in progress, and pending
NOTES.md - working notes, gotchas, environment quirks
Fill in PROJECT.md first. It anchors every later session. A session that reads only
PROJECT.md, TODO.md and DECISIONS.md should understand what the project is and
what to do next.
4. Add a .gitignore
Ignore build artefacts, dependencies, secrets and local scratch. Never commit tokens or credentials.
5. First commit
Commit the scaffold to the trunk directly (this is bootstrap, not a feature):
git add .
git commit
Write a full commit message describing what the scaffold contains and why. From here on, all work follows the Workflow: a branch per feature.
Checklist
- Repo created and remote set
CLAUDE.mdanddocs/present in project rootstate/created from templates,PROJECT.mdfilled in.gitignorein place, no secrets tracked- Scaffold committed to the trunk