Skip to content

Commit 3cb403d

Browse files
tomy0000000tomy0000000
committed
🗄 [chore] organize AI notes
1 parent 105a5fa commit 3cb403d

4 files changed

Lines changed: 84 additions & 50 deletions

File tree

‎.agents/rules/tasks.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Tasks
2+
3+
All tasks available in this repo are listed below, all managed by `mise`. Run any task with `mise run <task>`. List them anytime with `mise tasks ls`.
4+
5+
**Never `cd` into a subdirectory to run a task.** Every task is preconfigured (via `#MISE dir=...`) to run correctly from anywhere under the repo, so run `mise run <task>` directly without changing directories first.
6+
7+
**These are the only tasks that exist.** Do not invent task names, flags, or usages beyond what is documented here. Tasks are defined either inline in [`mise.toml`](../../mise.toml) or as `#MISE`-annotated scripts under `scripts/`, `backend/scripts/`, and `frontend/scripts/`. If you need something not covered here, add a new script or `mise.toml` task rather than guessing at one.
8+
9+
## Setup
10+
11+
| Task | Description | Notes |
12+
| -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
13+
| `setup:dotenv` | Setup environment variables for local development | Generates `instance/local.env` with random secrets. Skips if the file already exists. |
14+
| `setup:db` | Setup empty database for local development (data will NOT persist, not for prod) | Runs `start:db` then `db:upgrade`. |
15+
16+
## Dev servers
17+
18+
| Task | Description | Notes |
19+
| ---------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- |
20+
| `start` | Start all dev servers | Runs `start:backend` and `start:frontend` in parallel. |
21+
| `start:backend` | Start backend server with hot reload | `fastapi dev` on `0.0.0.0:8000` with `--reload`. |
22+
| `start:frontend` | Start frontend server with hot reload | `vite` dev server (`localhost:5173`). |
23+
| `start:db` | Start PostgreSQL container for local development (data will NOT persist) | Recreates the `kayman-db` container, starts Docker if needed. |
24+
| `start:db-dev` | Start PostgreSQL, upgrade schema, and seed mock data for local development | Depends on `setup:db`. Forwards extra args to the seed script. |
25+
26+
## Database
27+
28+
| Task | Description | Usage / Notes |
29+
| ------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
30+
| `db:upgrade` | Upgrade database schema | Runs `alembic upgrade head`. |
31+
| `db:backup` | Backup PostgreSQL database to a local dump | Writes `kayman_<timestamp>.dump` in `backend/`. Reads `instance/.env`. |
32+
| `db:restore` | Restore PostgreSQL database from a dump file | `mise run db:restore -- path/to/data.dump`. Reads `instance/.env`. |
33+
34+
## Build
35+
36+
| Task | Description | Usage / Notes |
37+
| ---------------------- | ------------------------------------- | -------------------------------------------------------------------- |
38+
| `build:frontend` | Build frontend for production | `tsc --build` then `vite build`. |
39+
| `build:router` | Generate frontend TanStack router | `tsr generate`. |
40+
| `build:openapi-spec` | Build OpenAPI specification JSON | `mise run build:openapi-spec -- <json_path>` (output path required). |
41+
| `build:openapi-client` | Build OpenAPI client for the frontend | Generates the spec to a temp file, then runs `openapi-ts`. |
42+
| `build:docker` | Build Docker image | Builds `tomy0000000/kayman:latest`. |
43+
44+
## Format
45+
46+
| Task | Description | Notes |
47+
| ----------------- | ----------------------------- | --------------------- |
48+
| `format:backend` | Format backend with ruff | `ruff format kayman`. |
49+
| `format:frontend` | Format frontend with Prettier | `prettier --write .`. |
50+
51+
## Lint
52+
53+
| Task | Description | Notes |
54+
| --------------- | --------------- | ------------------------------------------------------------- |
55+
| `lint:backend` | Lint backend | `mypy`, `ruff check`, and `ruff format --check`. |
56+
| `lint:frontend` | Lint frontend | `tsc --build --noEmit`, `eslint .`, and `prettier --check .`. |
57+
| `lint:docker` | Lint Dockerfile | `hadolint Dockerfile`. |
58+
59+
## Test
60+
61+
| Task | Description | Notes |
62+
| -------------- | ------------ | ---------------------------------------------------------------- |
63+
| `test:backend` | Test backend | Runs `pytest`, then prints the path to the HTML coverage report. |
64+
65+
## Preview
66+
67+
| Task | Description | Notes |
68+
| ------------------ | ----------------------------------------------------------- | ---------------------------------------------------------- |
69+
| `preview:frontend` | Preview production build locally | Depends on `build:frontend`, then `vite preview`. |
70+
| `preview:docker` | Preview docker run by connecting to development environment | Runs the image with `instance/development.env` on `:8000`. |
71+
72+
## Other
73+
74+
| Task | Description | Notes |
75+
| ----------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
76+
| `postinstall` | Frontend post-install hook (no `#MISE description`) | Generates the OpenAPI client and router. On Vercel, also downloads the schema first. |
77+
| `download-schema` | Download the OpenAPI schema from a running API (no `#MISE description`) | Requires the `API_HOST` env var. Fetches `https://${API_HOST}/openapi.json` into `/tmp/openapi.json`. |

‎AGENTS.md‎

Lines changed: 4 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ This file provides guidance to work on Kayman.
44

55
For app-specific guidance, see:
66

7-
- [`backend/CLAUDE.md`](backend/CLAUDE.md): FastAPI server (Python, `uv`)
8-
- [`frontend/CLAUDE.md`](frontend/CLAUDE.md): React/Vite SPA (TypeScript, `pnpm`)
7+
- [`backend/AGENTS.md`](backend/AGENTS.md): FastAPI server (Python, `uv`)
8+
- [`frontend/AGENTS.md`](frontend/AGENTS.md): React/Vite SPA (TypeScript, `pnpm`)
99

1010
Historical design notes and context for past decisions live in [`.agents/docs/`](.agents/docs/). Check there when a current convention's rationale isn't obvious from the code.
1111

@@ -21,31 +21,9 @@ Historical design notes and context for past decisions live in [`.agents/docs/`]
2121

2222
## Common commands
2323

24-
Run from the repo root. All custom tasks go through `mise run <task>`. Use `mise tasks` to list everything.
24+
Run from the repo root. All custom tasks go through `mise run <task>`. For the complete list of available tasks and their usage, see [`.agents/rules/tasks.md`](.agents/rules/tasks.md). Those are the only tasks that exist: don't invent task names or usages.
2525

26-
### One-time setup
27-
28-
```bash
29-
mise install # install pinned node/pnpm/python/uv
30-
mise run setup:dotenv # generate instance/local.env with random secrets
31-
mise run start:db-dev # start a postgres container named kayman-db
32-
mise run db:upgrade # apply alembic migrations
33-
```
34-
35-
### Dev servers
36-
37-
```bash
38-
mise run start # backend + frontend in parallel
39-
mise run start:backend # uvicorn with --reload on :8000 (serves /api and the built SPA at /)
40-
mise run start:frontend # vite dev server
41-
```
42-
43-
### Docker
44-
45-
```bash
46-
mise run build:docker # builds docker image (multi-stage: frontend build → python runtime)
47-
mise run preview:docker # run the image against the development environment
48-
```
26+
When debugging in Chrome, the base URL is always `localhost:5173` for the frontend and `localhost:8000` for the backend.
4927

5028
## End-to-end request flow
5129

‎backend/AGENTS.md‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,7 @@ Guidance for the Kayman backend. See the repo-root `CLAUDE.md` for cross-cutting
1313

1414
## Common commands
1515

16-
Run from the repo root. Tasks change into `backend/` automatically.
17-
18-
```bash
19-
mise run start:backend # uvicorn with --reload on :8000 (serves /api and the built SPA at /)
20-
mise run lint:backend # mypy + ruff check + ruff format --check
21-
mise run format:backend # ruff format
22-
mise run test:backend # pytest with coverage (xml + html + term)
23-
mise run db:upgrade # alembic upgrade head
24-
mise run build:openapi-spec -- /tmp/openapi.json # dump OpenAPI spec
25-
```
16+
Run from the repo root. For the complete list of available tasks and their usage, see [`.agents/rules/tasks.md`](../.agents/rules/tasks.md). Those are the only tasks that exist: don't invent task names or usages.
2617

2718
Run a single test: `cd backend && uv run pytest kayman/tests/path/to/test_x.py::test_name`.
2819

‎frontend/AGENTS.md‎

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,25 +15,13 @@ Guidance for the Kayman frontend. See the repo-root `CLAUDE.md` for cross-cuttin
1515

1616
## Common commands
1717

18-
Run from the repo root. Tasks change into `frontend/` automatically.
19-
20-
```bash
21-
mise run start:frontend # vite dev server
22-
mise run lint:frontend # eslint
23-
mise run format:frontend # prettier -w .
24-
mise run build:frontend # tsc -b && vite build
25-
```
18+
Run from the repo root. For the complete list of available tasks and their usage, see [`.agents/rules/tasks.md`](../.agents/rules/tasks.md). Those are the only tasks that exist: don't invent task names or usages.
2619

2720
There is no frontend test suite.
2821

2922
### Codegen
3023

31-
The API client and route tree are generated, not hand-written.
32-
33-
```bash
34-
mise run build:openapi-client # regenerate src/lib/client/ from the backend's OpenAPI spec
35-
mise run build:router # regenerate src/routeTree.gen.ts
36-
```
24+
The API client and route tree are generated, not hand-written. Use `build:openapi-client` to regenerate `src/lib/client/` from the backend's OpenAPI spec, and `build:router` to regenerate `src/routeTree.gen.ts`.
3725

3826
Regenerate the client whenever backend routes or schemas change. The router tree is also generated automatically by the `tanstackRouter` Vite plugin during dev.
3927

0 commit comments

Comments
 (0)