159 lines
5.7 KiB
Markdown
159 lines
5.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
**WoodShop** - Voice-driven conversational 3D woodworking & furniture modeler.
|
||
Speak (or type) commands like *"place a 6 foot 2x4, sand it, attach a 2 foot 2x4
|
||
at 90 degrees 10 inches from the end"* and watch the model build in a live 3D
|
||
viewport — Holodeck-style.
|
||
|
||
## Architecture
|
||
|
||
**Design principle:** reuse existing CmdForge tools for everything that isn't
|
||
woodshop-specific; don't reinvent voice/AI plumbing.
|
||
|
||
```
|
||
woodshop-talk (driver.py) ── the conversational loop
|
||
│ dictate ............... speech→text (CmdForge tool, reused)
|
||
│ pa-load-tools ......... wood-* → Claude schemas (reused)
|
||
│ claude -p ............. interpret utterance → JSON tool calls (reused provider)
|
||
│ pa-execute-tool ....... dispatch each wood-* tool (reused)
|
||
│ read-aloud ........... speak confirmation (reused)
|
||
▼
|
||
scene.json ← single source of truth (parts, joints, selection, undo stack)
|
||
▲ │ writes
|
||
│ reads/mutates ▼
|
||
wood-* CmdForge tools woodshop-view (viewer.py)
|
||
(place/join/sand/delete/undo) watches scene.json → live pyvista 3D
|
||
thin wrappers over `woodshop` CLI
|
||
```
|
||
|
||
Only woodshop-specific code lives in this repo: the scene model
|
||
(`scene.py`), nominal→actual lumber table (`lumber.py`), length parsing
|
||
(`units.py`), the `woodshop` CLI (`cli.py`), build123d geometry + STL/STEP
|
||
export (`geometry.py`), the pyvista viewport (`viewer.py`), and the driver
|
||
(`driver.py`). The driver uses Claude (not `pa-tool-loop`, which hard-wires a
|
||
small local model) for reliable structured tool-calling.
|
||
|
||
### Entry points
|
||
|
||
| Command | Purpose |
|
||
|---------|---------|
|
||
| `woodshop <op>` | CLI ops: place, join, stand, lay, rotate, move, trim, copy, rename, sand, delete, undo, clear, status, cutlist, export, save, open, projects |
|
||
| `woodshop-view` | Live 3D viewport (watches `scene.json`; labels, grid, isometric) |
|
||
| `woodshop-talk` | Conversational driver (`--voice` for mic, `--once "..."` for one command) |
|
||
|
||
Scene file location: `$WOODSHOP_SCENE` or `~/.local/share/woodshop/scene.json`.
|
||
Named projects: `~/.local/share/woodshop/projects/<slug>.json`.
|
||
|
||
Parts have full 3D orientation (`yaw_deg`/`tilt_deg`/`roll_deg`) so legs and
|
||
uprights stand vertically. Parts can be referred to by id (`p1`) or by a name
|
||
set with `rename`. The cut list (`cutlist.py`) reports board-feet and an 8'-stick
|
||
shopping estimate.
|
||
|
||
### CmdForge tools (the documented command vocabulary)
|
||
|
||
`wood-place`, `wood-join`, `wood-sand`, `wood-delete`, `wood-undo` live in
|
||
`~/.cmdforge/<name>/` and wrap the `woodshop` CLI. Regenerate them with
|
||
`/tmp/gen_wood_tools.py` (kept in the repo plan) if their schemas change. The
|
||
arg descriptions ARE the LLM's documentation, so keep them clear.
|
||
|
||
### Setup
|
||
|
||
```bash
|
||
python3 -m venv .venv && source .venv/bin/activate
|
||
pip install -e ".[viewer,dev]" # viewer extra pulls build123d + pyvista
|
||
pytest # 25 tests
|
||
```
|
||
|
||
### Known limitations / next steps
|
||
|
||
1. **Joins stack in Z** (board B rests on A's top face). This avoids
|
||
interpenetration and handles vertical legs, but isn't true joinery (no
|
||
butt/mortise/lap geometry).
|
||
2. **Latency** ~7–13s per utterance (one `claude -p` call).
|
||
3. Voice path (`--voice`) reuses `dictate`; the driver loop is hardened against
|
||
failures but the mic path isn't exercised in the unit tests.
|
||
4. Auto-placement of parts in a multi-step "build a table" request depends on
|
||
the LLM choosing good offsets; geometry is correct but corners may need nudging.
|
||
|
||
## ⚠️ CRITICAL: Updating Todos, Milestones, and Goals
|
||
|
||
**DO NOT edit `todos.md`, `milestones.md`, or `goals.md` files directly.**
|
||
|
||
These files are managed by Development Hub which has file watchers and sync logic. Direct edits will be overwritten or cause conflicts.
|
||
|
||
**Use the `devhub-tasks` CLI instead:**
|
||
|
||
```bash
|
||
# Status overview
|
||
devhub-tasks status woodshop
|
||
|
||
# Add todos
|
||
devhub-tasks todo add woodshop "Task description" --priority high --milestone M1
|
||
|
||
# Complete todos (by text match or ID number)
|
||
devhub-tasks todo complete woodshop "Task description"
|
||
devhub-tasks todo complete woodshop 3
|
||
|
||
# List todos
|
||
devhub-tasks todo list woodshop
|
||
|
||
# Add milestones
|
||
devhub-tasks milestone add woodshop M2 --name "Milestone Name" --target "March 2026"
|
||
|
||
# Complete milestones (also completes linked todos)
|
||
devhub-tasks milestone complete woodshop M1
|
||
|
||
# Goals
|
||
devhub-tasks goal add woodshop "Goal description" --priority high
|
||
devhub-tasks goal complete woodshop "Goal description"
|
||
```
|
||
|
||
Use `--json` flag for machine-readable output. Run `devhub-tasks --help` for full documentation.
|
||
|
||
**Files you CAN edit directly:** `overview.md`, `architecture.md`, `README.md`, and any other docs.
|
||
|
||
## Development Commands
|
||
|
||
```bash
|
||
# Install for development
|
||
pip install -e ".[dev]"
|
||
|
||
# Run tests
|
||
pytest
|
||
|
||
# Run a single test
|
||
pytest tests/test_file.py::test_name
|
||
```
|
||
|
||
## Architecture
|
||
|
||
*TODO: Describe the project architecture*
|
||
|
||
### Key Modules
|
||
|
||
*TODO: List key modules and their purposes*
|
||
|
||
### Key Paths
|
||
|
||
- **Source code**: `src/woodshop/`
|
||
- **Tests**: `tests/`
|
||
- **Documentation**: `docs/` (symlink to project-docs)
|
||
|
||
## Documentation
|
||
|
||
Documentation lives in `docs/` (symlink to centralized docs system).
|
||
|
||
**Before updating docs, read `docs/updating-documentation.md`** for full details on visibility rules and procedures.
|
||
|
||
Quick reference:
|
||
- Edit files in `docs/` folder
|
||
- Use `public: true` frontmatter for public-facing docs
|
||
- Use `<!-- PRIVATE_START -->` / `<!-- PRIVATE_END -->` to hide sections
|
||
- Deploy: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh woodshop --deploy`
|
||
|
||
Do NOT create documentation files directly in this repository.
|