Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 2 additions & 2 deletions .claude/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Delegated by description; invoke explicitly by name when you want a specific one
| Agent | Use it for |
|---|---|
| `workers-engineer` | The two proxy Workers, wrangler config, the `/api/*` contract, bindings and secrets |
| `ui-engineer` | React/Vite/Tailwind work in `apps/chat-ui`, streaming UI, `@felix/ui` |
| `ui-engineer` | React/Vite/Tailwind work in `apps/web`, streaming UI, `@felix/ui` |
| `python-harness-engineer` | Python work on the harness (felix-run/felix); requires that checkout in scope |
| `postgres-engineer` | Harness schema, migrations, indexing, query plans, tenant-scoped access |
| `devops-engineer` | CI, turbo/pnpm pipeline, wrangler deploys, secrets, release verification |
Expand Down Expand Up @@ -78,7 +78,7 @@ Hooks fail open — every script exits 0 unless it is deliberately blocking. Tes
JSON before wiring it:

```bash
echo '{"tool_input":{"file_path":"'"$PWD"'/apps/chat-ui/src/api.ts"}}' | .claude/hooks/impact-reminder.sh
echo '{"tool_input":{"file_path":"'"$PWD"'/apps/web/src/api/client.ts"}}' | .claude/hooks/impact-reminder.sh
```

**Editing `settings.json` requires a session restart.** Skills, agents, and rules hot-reload.
Expand Down
4 changes: 2 additions & 2 deletions .claude/agents/code-quality-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,15 +46,15 @@ The per-dimension checklist with concrete repo targets is in the `code-quality`

## What is deliberate here — do not report it as a defect

- **The proxy contract is stated twice on purpose** — `apps/chat-ui/worker/index.ts` and the `/api`
- **The proxy contract is stated twice on purpose** — `apps/web/worker/index.ts` and the `/api`
rewrite in `vite.config.ts` — because one runs in production and the other only in `vite dev`
(`.claude/rules/protocol-parity.md`). Divergence between them is a finding; the duplication is not.
- **`@felix/protocol` is hand-mirrored** from the Python harness in a separate repo. It looks
redundant and is not.
- **`packages/ui` and `packages/cowork-client` ship raw `.tsx`/`.ts`** with no build step. The
double wiring (exports map + tsconfig paths) is the design, not an oversight.
- **`apps/docs/src/styles/theme.css` is generated** from `packages/design/src/tokens.ts`.
- **shadcn primitives** under `packages/ui/src` and `apps/chat-ui/src/components` are vendored
- **shadcn primitives** under `packages/ui/src` and `apps/web/src/components` are vendored
upstream code with relaxed lint rules. Do not restyle them to match house conventions.

## Calibration
Expand Down
2 changes: 1 addition & 1 deletion .claude/agents/code-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ pre-existing code unless the diff makes it newly wrong.

## This repo's real failure modes — check these first

1. **Proxy contract divergence.** `apps/chat-ui/worker/index.ts` and the `/api` rewrite in
1. **Proxy contract divergence.** `apps/web/worker/index.ts` and the `/api` rewrite in
`vite.config.ts` are two copies of the same contract. A change in one and not the other makes dev
and production behave differently, and nothing reports it.
2. **Silently unhandled SSE events.** `StreamEvent` ends in an open `{ event: string; … }` arm, so a
Expand Down
2 changes: 1 addition & 1 deletion .claude/agents/dx-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ spec.
- Test coverage reaches the VFS, the SSE reader, the proxy Workers, and a first slice of React
(thread store, theme provider, `usePoll`, Gate) under happy-dom. The remaining gap is the **chat
surface**: the composer and the inspector panels, which need a live harness or a lot of mocking.
- The proxy contract lives in two places — `apps/chat-ui/worker/index.ts` and the `/api` rewrite in
- The proxy contract lives in two places — `apps/web/worker/index.ts` and the `/api` rewrite in
`vite.config.ts` — with no mechanical check that they agree; parity is discipline alone.
- "Verified" for app code means type-check + lint + build + a manual run against a live harness.
Any proposal to add an application test suite is a real change in scope — raise it, don't sneak
Expand Down
2 changes: 1 addition & 1 deletion .claude/agents/felix-docs-writer.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ current Python layout** of felix-run/felix. Do not "clean up" a reference to the

You may edit files under `apps/docs/src/content/` (MDX), `CLAUDE.md`, and
`.claude/skills/*/SKILL.md` / `.claude/agents/*.md` when they describe docs workflow. Never
change runtime behavior in `apps/chat-ui` unless the prompt explicitly asks. Never deploy.
change runtime behavior in `apps/web` unless the prompt explicitly asks. Never deploy.

## Scope of truth

Expand Down
4 changes: 2 additions & 2 deletions .claude/agents/python-harness-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ not in `felix-web`. Before doing anything:

## What the web clients depend on

Changes here are load-bearing for `apps/chat-ui`. Treat these as a public contract:
Changes here are load-bearing for `apps/web`. Treat these as a public contract:

- **SSE framing on `POST /chat/stream`** — one event per `\n\n`, `data: <json>` lines, terminated by
`data: [DONE]`. Clients decode with a carry buffer; a malformed or unterminated frame hangs the UI.
Expand All @@ -40,7 +40,7 @@ Changes here are load-bearing for `apps/chat-ui`. Treat these as a public contra
payload shape is a breaking change on both clients.

Whenever you change one of these, say so explicitly in your output and name the client files that
must change with it (`packages/felix-protocol/src/types.ts`, `apps/chat-ui/src/{api,types}.ts`).
must change with it (`packages/felix-protocol/src/types.ts`, `apps/web/src/{api,types}.ts`).

## Engineering standards

Expand Down
4 changes: 2 additions & 2 deletions .claude/agents/refactor-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ saying so.

## Invariants you must not break

1. **The proxy contract is stated twice on purpose.** `apps/chat-ui/worker/index.ts` runs in
1. **The proxy contract is stated twice on purpose.** `apps/web/worker/index.ts` runs in
production; the `/api` rewrite in `vite.config.ts` runs only in `vite dev`. They cannot be one
module (`.claude/rules/protocol-parity.md`). The correct cleanup is the opposite one: make the
copies match, in the same PR.
Expand All @@ -34,7 +34,7 @@ saying so.
`packages/design/src/tokens.ts` via `pnpm sync:theme`; `block-generated.sh` will deny the edit.
5. **Shared dependency versions live in `pnpm-workspace.yaml` under `catalog:`.** Fixing drift means
replacing a literal version with `"catalog:"`, not bumping it in the manifest.
6. **shadcn primitives are vendored.** Leave `packages/ui/src` and `apps/chat-ui/src/components`
6. **shadcn primitives are vendored.** Leave `packages/ui/src` and `apps/web/src/components`
alone unless the finding is about our own code inside them.

## How to work
Expand Down
2 changes: 1 addition & 1 deletion .claude/agents/security-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ exploitable in this architecture — describe the attack, not the category.
**Browser → proxy Worker → Python harness → model → back out again.** Two of those hops carry
attacker-influenceable content, and one carries credentials.

### 1. The proxy Worker (`apps/chat-ui/worker/index.ts`)
### 1. The proxy Worker (`apps/web/worker/index.ts`)

- **No credential of its own.** The Worker forwards a browser's bearer untouched and attaches
nothing. Any change that makes it add a credential to a request — an injected key, a service
Expand Down
6 changes: 3 additions & 3 deletions .claude/agents/test-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ defect, and you say plainly what remains unverified.

## What is covered today, and what is not

Vitest 4, two configs, no root config: `apps/chat-ui/vitest.config.ts` and
Vitest 4, two configs, no root config: `apps/web/vitest.config.ts` and
`packages/cowork-client/vitest.config.ts`. `pnpm test` runs both through turbo — deliberately with **no** `dependsOn`, so a failing dependency can never silently
skip a package's tests.

Expand All @@ -29,8 +29,8 @@ Packages with no `test` script at all: `@felix/ui`, `@felix/protocol`, `@felix/d
## Where a test belongs

- **A contract that outlives its caller goes in `packages/test-kit/src/`**, exported through the
`exports` map and called from `apps/chat-ui/tests/`. The suites are parameterized on purpose — see
`apps/chat-ui/tests/sse.test.ts`: the suite takes an injected `run`, the caller supplies the
`exports` map and called from `apps/web/tests/`. The suites are parameterized on purpose — see
`apps/web/tests/sse.test.ts`: the suite takes an injected `run`, the caller supplies the
implementation. That indirection is what lets the Worker and reader contracts be stated once,
independently of who satisfies them.
- **A component test** opens with a `/** @vitest-environment happy-dom */` docblock. The configs
Expand Down
16 changes: 8 additions & 8 deletions .claude/agents/ui-engineer.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
name: ui-engineer
description: React/Vite/Tailwind engineer for the chat-ui SPA. Use proactively for any component, hook, state, styling, or streaming-UI work under apps/chat-ui/src, and whenever a change touches the SSE event handling in @felix/client's engine or the shared @felix/ui primitives.
description: React/Vite/Tailwind engineer for the chat-ui SPA. Use proactively for any component, hook, state, styling, or streaming-UI work under apps/web/src, and whenever a change touches the SSE event handling in @felix/client's engine or the shared @felix/ui primitives.
tools: Read, Grep, Glob, Edit, Write, Bash, WebFetch
model: inherit
color: cyan
---

You build the browser client in **felix-web**: `apps/chat-ui` — streaming chat, harness inspector,
and the unattended-run surface (background runs, approval polling, `src/lib/presence.ts`).
You build the browser client in **felix-web**: `apps/web` — streaming chat, harness inspector,
and the unattended-run surface (background runs, approval polling, `src/lib/conversation/presence.ts`).

Stack: React 18, Vite 8, Tailwind v4 (CSS-first — there is no `tailwind.config`), shadcn/ui via
`@felix/ui`, `streamdown` for markdown, `sonner` for toasts, `lucide-react` for icons.
Expand Down Expand Up @@ -36,7 +36,7 @@ Use the `api-contract-change` skill for the full procedure.
- Client state that must survive reload goes in `localStorage` under a `felix.*` key
(`felix.threadId`, `felix.manifest`, …). Server state is authoritative:
hydrate from `GET /chat/sessions/{id}`; the `localStorage` transcript mirror in
`src/lib/threads.ts` exists only because `GET /chat/history/{id}` rejects anonymous callers.
`src/lib/conversation/threads.ts` exists only because `GET /chat/history/{id}` rejects anonymous callers.
- Each tab mints a holder id and takes an exclusive session lease. A 409 means another client
drives the thread: the keeper observes (`shared`), the shell goes read-only, and the keeper
retries `exclusive` once per renewal tick — never in a tight loop. Driving requests carry the
Expand All @@ -54,12 +54,12 @@ Gate, the engine at the wire, and `App.tsx` end to end — **not** the composer
Never say "tests pass" as if the UI you changed were covered. Verify with:

```bash
pnpm --filter @felix/chat-ui check-types
pnpm --filter @felix/chat-ui lint
pnpm --filter @felix/chat-ui build
pnpm --filter @felix/web check-types
pnpm --filter @felix/web lint
pnpm --filter @felix/web build
```

For behavior, `pnpm chat:dev` needs the Python harness running on `:8080`
For behavior, `pnpm web:dev` needs the Python harness running on `:8080`
(`make up && make migrate` in felix-run/felix). Without it the app loads and every `/api/*` call
fails — say so rather than reporting a broken UI as a code bug.

Expand Down
6 changes: 3 additions & 3 deletions .claude/agents/workers-engineer.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: workers-engineer
description: Cloudflare Workers specialist for the felix-web proxy Worker and wrangler config. Use proactively whenever apps/chat-ui/worker/index.ts, a wrangler.jsonc, an assets/SPA-fallback question, or the /api/* proxy contract is involved — including header handling, SSE pass-through, bindings, secrets, and routes.
description: Cloudflare Workers specialist for the felix-web proxy Worker and wrangler config. Use proactively whenever apps/web/worker/index.ts, a wrangler.jsonc, an assets/SPA-fallback question, or the /api/* proxy contract is involved — including header handling, SSE pass-through, bindings, secrets, and routes.
tools: Read, Grep, Glob, Edit, Write, Bash, WebFetch
model: inherit
color: orange
Expand Down Expand Up @@ -36,7 +36,7 @@ client possible at all. Same-origin in, HTTP out.

## Config facts

- `apps/chat-ui/wrangler.jsonc` is **tracked** and is what CI deploys to make.felix.run; it ships a `.dev.vars.example` for `wrangler dev`. Keep
- `apps/web/wrangler.jsonc` is **tracked** and is what CI deploys to make.felix.run; it ships a `.dev.vars.example` for `wrangler dev`. Keep
that example in step when you change bindings or vars. `apps/docs/wrangler.jsonc` is tracked because it holds no
account or resource ids.
- Routes are custom domains: `make.felix.run`, `docs.felix.run`.
Expand All @@ -46,7 +46,7 @@ client possible at all. Same-origin in, HTTP out.

1. Read the Worker and the `vite.config.ts` dev proxy before editing either. State in your output
whether the change applies to one or both, and why.
2. Type-check with `pnpm --filter @felix/chat-ui check-types`, then run `pnpm test`: the suite in
2. Type-check with `pnpm --filter @felix/web check-types`, then run `pnpm test`: the suite in
`@felix/test-kit` holds the Worker to the `/api/*` contract — the gate key never going upstream,
the body streaming through untouched. It does not cover deployed behavior.
3. For runtime verification, `wrangler dev` in the app directory, against a running harness on
Expand Down
2 changes: 1 addition & 1 deletion .claude/hooks/failure-hint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,6 @@ case "$cmd" in
*) exit 0;;
esac

jq -cn --arg ctx "felix-web failure shortlist: (1) 'Cannot find module @felix/ui/...' or @felix/cowork-client → those packages have NO build step; the export must exist in the package's exports map AND in the tsconfig paths of apps/chat-ui (add-ui-primitive skill). (2) tsc errors on possibly-undefined index access → the workspace tsconfig sets noUncheckedIndexedAccess; handle the undefined rather than adding '!'. (3) tsc noUnusedLocals/noUnusedParameters → chat-ui enables them; delete the unused binding. (4) biome check failures → pnpm format fixes formatting; real lint errors need a code change, not a config change. (5) wrangler 'assets directory does not exist' → run the build first ('*:deploy' scripts already do). (6) wrangler cannot find wrangler.jsonc → run wrangler from the app directory (pnpm --filter @felix/<app> exec wrangler); both configs are tracked. (7) ECONNREFUSED / 502 on :8080 in dev → the Python harness is not running; 'make up && make migrate' in felix-run/felix. (8) 502 felix_origin_unset → vars.FELIX_ORIGIN missing in wrangler.jsonc. (9) astro 'does not exist in collection docs' or a missing page → prose lives at src/content/ (not src/content/docs/) and new pages must be registered in the sidebar in astro.config.mjs. (10) ERR_PNPM_OUTDATED_LOCKFILE → run pnpm install; never hand-edit the lockfile. (11) 'vitest not found' / 'no test specified' → only apps/chat-ui and packages/cowork-client have a test script and a vitest.config.ts; the other packages have none by design, so scope the run with pnpm --filter rather than adding a config." \
jq -cn --arg ctx "felix-web failure shortlist: (1) 'Cannot find module @felix/ui/...' or @felix/cowork-client → those packages have NO build step; the export must exist in the package's exports map AND in the tsconfig paths of apps/web (add-ui-primitive skill). (2) tsc errors on possibly-undefined index access → the workspace tsconfig sets noUncheckedIndexedAccess; handle the undefined rather than adding '!'. (3) tsc noUnusedLocals/noUnusedParameters → chat-ui enables them; delete the unused binding. (4) biome check failures → pnpm format fixes formatting; real lint errors need a code change, not a config change. (5) wrangler 'assets directory does not exist' → run the build first ('*:deploy' scripts already do). (6) wrangler cannot find wrangler.jsonc → run wrangler from the app directory (pnpm --filter @felix/<app> exec wrangler); both configs are tracked. (7) ECONNREFUSED / 502 on :8080 in dev → the Python harness is not running; 'make up && make migrate' in felix-run/felix. (8) 502 felix_origin_unset → vars.FELIX_ORIGIN missing in wrangler.jsonc. (9) astro 'does not exist in collection docs' or a missing page → prose lives at src/content/ (not src/content/docs/) and new pages must be registered in the sidebar in astro.config.mjs. (10) ERR_PNPM_OUTDATED_LOCKFILE → run pnpm install; never hand-edit the lockfile. (11) 'vitest not found' / 'no test specified' → only apps/web and packages/cowork-client have a test script and a vitest.config.ts; the other packages have none by design, so scope the run with pnpm --filter rather than adding a config." \
'{hookSpecificOutput:{hookEventName:"PostToolUseFailure",additionalContext:$ctx}}'
exit 0
Loading
Loading