Bootstrap agent-ready docs and permissions (D-036)
Root AGENTS.md is now the single source of truth for coding agents; CLAUDE.md, GEMINI.md and docs/CLAUDE.md are pointers. The product spec moves from docs/CLAUDE.md to PRODUCT.md, DESIGN.md records the shipped visual system, and docs/PERMISSIONS.md defines agent permission tiers rendered to .claude/, .codex/ and .gemini/. Adds docs/specs/ and docs/plans/, logs issues noticed (not fixed) in WorkBreakdown.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Lucas Winther
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
c1b710cb23
commit
0ece4b3a2a
@@ -1,7 +1,7 @@
|
||||
# Architecture
|
||||
|
||||
> Companion to `CLAUDE.md` (product spec & tooling rules) and `Decisions.md` (why things
|
||||
> are the way they are). This file describes **how the system is structured**. Update it
|
||||
> Companion to `../PRODUCT.md` (product spec), `../AGENTS.md` (agent & tooling rules) and
|
||||
> `Decisions.md` (why things are the way they are). This file describes **how the system is structured**. Update it
|
||||
> whenever the structure changes.
|
||||
|
||||
## 1. System overview
|
||||
|
||||
+9
-126
@@ -1,129 +1,12 @@
|
||||
# CLAUDE.md — Read this first, every session
|
||||
# docs/CLAUDE.md
|
||||
|
||||
This is the single source of truth for any agent working in this repo. If anything
|
||||
you're told conflicts with this file, this file wins.
|
||||
**`AGENTS.md` (repo root) is the single source of truth for agents in this repository.** Read
|
||||
`../AGENTS.md` and follow it exactly. This file contains no rules of its own.
|
||||
|
||||
## 1. What we are building
|
||||
This file used to hold the product spec and the Bun toolchain rules (it was the original `bun init`
|
||||
CLAUDE.md, extended). Its content now lives in:
|
||||
- Product spec ("what we are building") → `PRODUCT.md`
|
||||
- Bun toolchain and API rules → `AGENTS.md` § Rules
|
||||
- Bun API reference → `node_modules/bun-types/docs/`
|
||||
|
||||
A browser-first speech-to-text web app powered by OpenAI Whisper, running through
|
||||
[Transformers.js](https://github.com/huggingface/transformers) (`@huggingface/transformers`).
|
||||
|
||||
**Anonymous users (no login) can:**
|
||||
- Run Whisper models fully in the browser (no data leaves the device).
|
||||
- Choose which Whisper model to use (tiny → large, English-only and multilingual, quantized variants).
|
||||
- Keep working when the network — or our own server — is offline (installable PWA + cached model weights).
|
||||
- Accelerate inference with WebNN or WebGPU (auto-selected in that order, D-017), falling back to WASM automatically.
|
||||
- Transcribe from an uploaded audio/video file.
|
||||
|
||||
**Logged-in users (Passport.js) get all of the above, plus:**
|
||||
- A toggle to choose where inference runs: **their own device** (browser engine) or **the server** the app is deployed on (server engine).
|
||||
- The server engine MUST use [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (CTranslate2) for inference — not Transformers.js (see Decisions.md D-013). faster-whisper cannot run in a browser (no WASM build of CTranslate2), so the browser engine stays on Transformers.js.
|
||||
|
||||
## 2 How to run things
|
||||
|
||||
|
||||
Default to using Bun instead of Node.js.
|
||||
|
||||
- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
|
||||
- Use `bun test` instead of `jest` or `vitest`
|
||||
- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
|
||||
- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
|
||||
- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
|
||||
- Use `bunx <package> <command>` instead of `npx <package> <command>`
|
||||
- Bun automatically loads .env, so don't use dotenv.
|
||||
|
||||
## APIs
|
||||
|
||||
- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
|
||||
- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
|
||||
- `Bun.redis` for Redis. Don't use `ioredis`.
|
||||
- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
|
||||
- `WebSocket` is built-in. Don't use `ws`.
|
||||
- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
|
||||
- Bun.$`ls` instead of execa.
|
||||
|
||||
## Testing
|
||||
|
||||
Use `bun test` to run tests.
|
||||
|
||||
```ts#index.test.ts
|
||||
import { test, expect } from "bun:test";
|
||||
|
||||
test("hello world", () => {
|
||||
expect(1).toBe(1);
|
||||
});
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
|
||||
|
||||
Server:
|
||||
|
||||
```ts#index.ts
|
||||
import index from "./index.html"
|
||||
|
||||
Bun.serve({
|
||||
routes: {
|
||||
"/": index,
|
||||
"/api/users/:id": {
|
||||
GET: (req) => {
|
||||
return new Response(JSON.stringify({ id: req.params.id }));
|
||||
},
|
||||
},
|
||||
},
|
||||
// optional websocket support
|
||||
websocket: {
|
||||
open: (ws) => {
|
||||
ws.send("Hello, world!");
|
||||
},
|
||||
message: (ws, message) => {
|
||||
ws.send(message);
|
||||
},
|
||||
close: (ws) => {
|
||||
// handle close
|
||||
}
|
||||
},
|
||||
development: {
|
||||
hmr: true,
|
||||
console: true,
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
|
||||
|
||||
```html#index.html
|
||||
<html>
|
||||
<body>
|
||||
<h1>Hello, world!</h1>
|
||||
<script type="module" src="./frontend.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
With the following `frontend.tsx`:
|
||||
|
||||
```tsx#frontend.tsx
|
||||
import React from "react";
|
||||
import { createRoot } from "react-dom/client";
|
||||
|
||||
// import .css files directly and it works
|
||||
import './index.css';
|
||||
|
||||
const root = createRoot(document.body);
|
||||
|
||||
export default function Frontend() {
|
||||
return <h1>Hello, world!</h1>;
|
||||
}
|
||||
|
||||
root.render(<Frontend />);
|
||||
```
|
||||
|
||||
Then, run index.ts
|
||||
|
||||
```sh
|
||||
bun --hot ./index.ts
|
||||
```
|
||||
|
||||
For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
|
||||
See Decisions.md D-036.
|
||||
|
||||
@@ -1126,3 +1126,28 @@ change needs its own accuracy verification against
|
||||
`tests/live-accuracy.test.ts` and `tests/live-real-model.test.ts` (a
|
||||
repetition guard can change correct-transcript wording too) before landing,
|
||||
which is out of scope for this investigation.
|
||||
|
||||
## D-036 — Root `AGENTS.md` is the single source of truth for agents
|
||||
**Status:** Accepted (2026-10-29)
|
||||
`docs/CLAUDE.md` called itself the single source of truth, but Claude Code
|
||||
only auto-loads it when working inside `docs/`, other agents (Codex, Gemini,
|
||||
Cursor) never read it, and most of it was the generic `bun init` boilerplate
|
||||
(sample `Bun.serve`/HTML snippets) rather than repo-specific rules.
|
||||
**Decision:** a root `AGENTS.md` (read natively by Codex/Gemini, imported by
|
||||
the root `CLAUDE.md` via `@AGENTS.md`) holds the rules: verified commands, the
|
||||
conventions agents would otherwise break (Bun only, D-013 engine split, the
|
||||
transformers patch, COEP, D-020, D-030, D-032), boundaries, and docs duties.
|
||||
`CLAUDE.md`, `GEMINI.md`, and `docs/CLAUDE.md` are pointers only. The product
|
||||
spec from `docs/CLAUDE.md` §1 moved to `PRODUCT.md`; `DESIGN.md` records the
|
||||
shipped visual system (both read by the impeccable skill). Specs from the
|
||||
superpowers workflow live permanently in `docs/specs/`; plans live in
|
||||
`docs/plans/` only while work is in progress and are `git rm`'d before
|
||||
merging. Agent tool permissions are defined in `docs/PERMISSIONS.md` and
|
||||
rendered to `.claude/settings.json`, `.codex/`, `.gemini/settings.json`.
|
||||
**Kept as-is:** `docs/Architecture.md`, `docs/Decisions.md` (same filenames —
|
||||
renaming would break every existing reference) and `docs/WorkBreakdown.md`
|
||||
as the one backlog (its own rule: no separate backlog), rather than adding a
|
||||
`docs/TODO.md`.
|
||||
**Trade-off:** `AGENTS.md` is kept short (<150 lines) on purpose — rationale
|
||||
goes here, not there. Changes to it redirect every agent session, so review
|
||||
them like CI config.
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# Agent permissions
|
||||
|
||||
Source of truth for what AI coding agents may run here. Tool files are renderings of this page:
|
||||
`.claude/settings.json`, `.codex/config.toml` + `.codex/rules/project.rules`, `.gemini/settings.json`.
|
||||
Change this page and every tool file in the same commit. (No Cursor/Copilot files: no sign the team uses them.)
|
||||
|
||||
## Verified commands
|
||||
|
||||
Run on 2026-10-29 (Bun 1.3.14). Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands.
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `bun install --frozen-lockfile` | worked |
|
||||
| `bun test tests/export.test.ts` | worked — 28 pass |
|
||||
| `bun test tests/models.test.ts -t "dtype"` | worked — 5 pass, 14 filtered |
|
||||
| `bun test --path-ignore-patterns='tests/live-real-model.test.ts'` | worked — 239 pass, 1 skip, ~6 s |
|
||||
| `bun test` | ran — 242 pass, 1 skip, 1 fail in ~17 min. The fail is pre-existing: `tests/live-real-model.test.ts` › `en_alien` hits its 900 s timeout (reproduced in isolation). Allowed anyway: the command itself is the verified dev loop. |
|
||||
| `bun run build` | worked |
|
||||
| `bun run icons` | worked |
|
||||
| `bun dev` | worked — HTTP 200 on `/` |
|
||||
| `FW_INTEGRATION=1 bun test tests/transcribe.test.ts` | not run — faster-whisper not installed here |
|
||||
| `bun start` | not run — documented in README |
|
||||
| Typecheck / lint | not run — `typescript` not installed, no linter configured |
|
||||
| `docker build .` | not run — CI-only; in Ask tier |
|
||||
|
||||
TODO(maintainer): confirm every row above that is not worked.
|
||||
|
||||
## Tiers
|
||||
|
||||
| Tier | Commands | Why |
|
||||
|---|---|---|
|
||||
| Allow | `git status`, `git diff`, `git log`, `git show`, `git branch --list`, `git rev-parse`, `git add`, `git commit`; `bun install --frozen-lockfile`, `bun test`, `bun run build`, `bun run icons`, `bun dev` | Inspection and the verified dev loop; no prompt needed. |
|
||||
| Ask | `git push`, `git merge`, `git rebase`, `git switch`, `git restore`, `git commit --amend`, `rm`; `bun add`/`remove`/`update`/`upgrade`/`patch`, `bunx`, `bun x`; `docker`; `pip install`, `python3 -m pip install` | Leaves the machine, rewrites work, changes dependencies or the transformers patch, or touches deployment — a human decides. |
|
||||
| Deny | `git push --force`/`-f`/`--force-with-lease`, `git reset --hard`, `git clean`, `git add -f`/`--force`, `git commit --no-verify`/`-n`, `rm -r`/`-R`/`-rf`/`-fr`/`-Rf`/`-fR`/`--recursive`, `sudo`; reading `.env`, `.env.*`, `data/**` (local SQLite users + sessions) | Destroys work, skips checks, or exposes secrets/user data. |
|
||||
|
||||
## Known gaps
|
||||
- Allowlists save prompts; they are not a security boundary. Use the tool's sandbox for isolation.
|
||||
- Prefix rules are bypassable: `git -C dir push`, flags placed later (`git push origin main --force`),
|
||||
`+refspec` pushes. Claude Code's `:*` matches at a word boundary, so each flag cluster must be
|
||||
listed — which is why `git clean` is denied whole and `rm` always asks.
|
||||
- `bun install <pkg>` adds a dependency but cannot be put in Ask without also catching the allowed
|
||||
`bun install --frozen-lockfile` (Ask beats Allow in Claude Code). Treat it as Ask by convention.
|
||||
- `bun run build` deletes and rewrites `dist/` itself (`scripts/build.ts`), outside the `rm` rules.
|
||||
- Allowed test, build, and dev commands run code from the repo; an agent that can edit
|
||||
`package.json`, `scripts/`, or the tests can run anything through them. `bun test` also downloads
|
||||
model weights from huggingface.co (`tests/live-real-model.test.ts`).
|
||||
- Denying reads of `.env` does not stop a script that opens it itself (Bun auto-loads `.env`), and
|
||||
git can print staged or committed secrets. `git add -f` is denied so an agent cannot stage an
|
||||
ignored secret; keep real secrets out of the working tree.
|
||||
- Codex: loaded only once the project is trusted; `approval_policy = "on-request"` here can loosen a
|
||||
stricter user setting. No allow rules (Codex `allow` = run outside the sandbox). In
|
||||
`workspace-write`, `.git/` is read-only, so `git add`/`commit` ask for escalation; `bun install`
|
||||
needs network and asks too. `--force-with-lease=<ref>` and late flags only match the Ask rule.
|
||||
Rules checked with `codex execpolicy check`.
|
||||
- Gemini: ignored until the folder is trusted; `tools.exclude` is the only project-level deny; no
|
||||
Ask tier (anything not allowed already asks); cannot deny file reads.
|
||||
@@ -345,3 +345,35 @@ cached.
|
||||
Arbitrary Hub model ids, OAuth providers, multi-user transcript storage,
|
||||
whisper.cpp server backend, i18n of the UI.
|
||||
Promote to a milestone via a new entry in `Decisions.md` first.
|
||||
|
||||
---
|
||||
|
||||
## Noticed, not fixed
|
||||
Found while bootstrapping agent docs (D-036); docs-only pass, so no code changed.
|
||||
- [ ] `bun test tests/live-real-model.test.ts` fails: the `en_alien (en)` case
|
||||
times out at its 900 s limit (2026-10-29, Linux CPU/WASM, reproduced in
|
||||
isolation; `da_festuge` and `en_aiproblem` pass).
|
||||
- [ ] `isolate_wer2.ts` (repo root) is marked "TEMP (delete after use)" and
|
||||
writes to a stale `/tmp/claude-1000/...` scratchpad path.
|
||||
- [ ] `docs/Architecture.md` §3 and `scripts/build.ts` say `src/pwa/icons/`
|
||||
is "not checked in", but `icon-192.png`/`icon-512.png` are tracked.
|
||||
- [ ] No typecheck or lint: `tsconfig.json` is strict but `typescript` is not
|
||||
installed, so nothing checks types (`bun` strips them).
|
||||
- [ ] `.gitlab-ci.yml` only builds Docker images; `bun test` never runs in CI.
|
||||
- [ ] README "Graceful degradation" says server-engine weights download into
|
||||
the data volume; the env table, Dockerfile and D-031 say they are baked
|
||||
into the image at `/opt/faster-whisper/models`.
|
||||
- [ ] `src/index.css` declares `color-scheme: light dark` but only has a dark
|
||||
palette; `Inter` is listed first in the font stack but never loaded.
|
||||
|
||||
## Recurring
|
||||
- [ ] Maintain `AGENTS.md`:
|
||||
- **Add a rule only in response to a real failure.** When an agent repeatedly
|
||||
gets something wrong, add one line, ideally with a code example. Do not
|
||||
pre-empt hypothetical mistakes.
|
||||
- **Update in the same commit as the convention change.** A stale rules file
|
||||
actively misleads.
|
||||
- **Prune quarterly.** Delete rules whose convention changed or whose mistake
|
||||
no longer occurs. Keep it under 150 lines.
|
||||
- **Optional validation:** run the same task twice in clean sessions, with and
|
||||
without the file, and compare steps and token use.
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Plans
|
||||
|
||||
Implementation plans from the superpowers writing-plans workflow. **Transient:** a plan lives only while
|
||||
its work is in progress and is removed with `git rm` before merging. This README stays.
|
||||
|
||||
- Naming: `NNN-short-slug.md`, matching its spec number.
|
||||
- Links back to its spec. Bite-sized checkbox tasks with exact file paths, test commands, and
|
||||
commit checkpoints.
|
||||
- Written for an engineer with zero context for this codebase — spell out the obvious.
|
||||
- Tick checkboxes as you go so another agent can resume an interrupted session.
|
||||
- Front matter: `status: draft | approved | in-progress`. There is no `done` — a finished plan is deleted.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Specs
|
||||
|
||||
Approved specifications from the superpowers brainstorming workflow. Nothing non-trivial gets
|
||||
implemented without one.
|
||||
|
||||
- Naming: `NNN-short-slug.md`, zero-padded, sequential.
|
||||
- A spec states **what** and **why**, plus acceptance criteria. Not **how**.
|
||||
- Front matter: `status: draft | approved | implemented | superseded`. No link to a plan — plans are
|
||||
removed before merge.
|
||||
- Never delete an implemented spec; it is the record of intent.
|
||||
- A spec that makes an architectural choice also gets a `D-###` entry in `docs/Decisions.md`.
|
||||
Reference in New Issue
Block a user