diff --git a/AGENTS.md b/AGENTS.md --- a/AGENTS.md +++ b/AGENTS.md @@ -1,17 +1,22 @@ # AGENTS.md This file provides guidance for coding agents when working with the Artcraft monorepo. +Claude Code, Codex and other agents read `AGENTS.md` files directly; do not add +`CLAUDE.md` mirrors (see [agent documentation](_docs/AGENTS.md)). ## Project Overview Artcraft is a public-facing Tauri desktop app for generating AI images and video. -It uses Rust and TypeScript. Backend services, company tooling, and website builds -live in the separate `artcraft-services` repository. +It uses Rust and TypeScript. `artcraft-native/` is a separate pure Rust/egui +desktop app over the same API client crates. Backend services, company tooling, +and website builds live in the separate `artcraft-services` repository. +[Development setup](_docs/dev_setup.md) owns environment commands. ## Project Structure ``` artcraft/ +├── artcraft-native/ # Rust/egui desktop app over shared API clients ├── _database/sql/artcraft_migrations/ # Embedded SQLite task database migrations ├── .sqlx/ # SQLite query metadata for offline builds ├── crates/ @@ -66,11 +71,32 @@ Organize for top-to-bottom reading. Important things first, details later. column width: ```markdown - | Model | Configuration | Credits | Speed | Score | - |--------------|---------------|--------------------|---------| - | Meshy 6 | text or image | 104 | 80.0 | +24 | - | Rodin 2.5 | text or image | 13 | 10.0 | +3 | + | Model | Configuration | Credits | Speed | Score | + |--------------|---------------|---------|-------|-------| + | Meshy 6 | text or image | 104 | 80.0 | +24 | + | Rodin 2.5 | text or image | 13 | 10.0 | +3 | ``` Not: `| Model | Configuration | Credits | Speed | Score |` packed tight with varying widths per row. + +## Working Rules + +- Reproduce a found defect with a test before fixing it and confirm the failure's cause. + If automation cannot reach it, record the limitation and the nearest executable check. + Never weaken a valid test to make a suite pass. +- Use the owning boundary's existing types, error idiom and dependency direction. Read a + dependency's source before wrapping it; avoid unrelated cleanup or new frameworks. +- Run checks that reach the changed boundary and widen them for shared wire types or + routing. Compilation, fixture tests, live-provider behavior, native startup and visual + acceptance are different evidence; report which ones ran and which were skipped. +- Keep ordinary tests local and hermetic. Paid generation, uploads, real credentials, + account changes, releases and destructive operations need explicit authorization. +- Nested `AGENTS.md` files own their context. For a change that crosses boundaries, read + the `AGENTS.md` of each affected directory before editing. + +Contexts: [Rust](crates/AGENTS.md), [frontend](frontend/AGENTS.md), +[pagescene](frontend/libs/components/pagescene/AGENTS.md), +[native app](artcraft-native/AGENTS.md), [agent documentation](_docs/AGENTS.md). +The [engineering methodology](_docs/agent-engineering-methodology.md) explains these +rules and describes optional review and concurrent-agent workflows. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -136,6 +136,7 @@ Additional provider integrations are planned for Kling, Google, Runway, and Luma ## Documentation +- [Agent instructions](./AGENTS.md) and [engineering methodology](./_docs/agent-engineering-methodology.md) - [Development setup](./_docs/dev_setup.md) - [Developer documentation](./_docs) - [Desktop build and development scripts](./script/artcraft) diff --git a/_docs/AGENTS.md b/_docs/AGENTS.md new file mode 100644 --- /dev/null +++ b/_docs/AGENTS.md @@ -0,0 +1,16 @@ +# Agent and development documentation + +The root `AGENTS.md` holds operative rules and style; nested `AGENTS.md` files hold the +rules of the code they sit next to; `agent-engineering-methodology.md` explains them and +describes optional workflows. Keep concise rules an agent must follow in `AGENTS.md` files +and explanation in the methodology. + +When editing agent guidance, map each rule to the failure it prevents and its actual +test or manual check. Do not imply that documentation enforces permissions or isolation. +Check moved links and retain existing conventions unless a deliberate change replaces them. + +Name instruction files `AGENTS.md` only. Do not add `CLAUDE.md` copies or symlinks: +Claude Code (v2.1.277+) reads `AGENTS.md` only when no `CLAUDE.md` is on the path, and +Git for Windows checks symlinks out as one-line text files by default, so a mirrored +`CLAUDE.md` replaces the real instructions on those clones. See the +[Claude Code AGENTS.md guide](https://code.claude.com/docs/en/memory#agents-md). diff --git a/_docs/agent-engineering-methodology.md b/_docs/agent-engineering-methodology.md new file mode 100644 --- /dev/null +++ b/_docs/agent-engineering-methodology.md @@ -0,0 +1,183 @@ +# Evidence-oriented agent engineering for ArtCraft + +Operative instructions are in the root and contextual `AGENTS.md` files. This document +explains their reasoning and describes optional workflows; it does not activate agents, +hooks, CI or merge rights. + +## Why this fits this repository + +ArtCraft places Rust, endpoint, Tauri-command, schema and 3D-editor rules near the +code they govern. This methodology keeps that structure. It adds explicit ways to +challenge an agent's diagnosis, confidence and scope before a plausible implementation +becomes an accidental product contract. + +The architecture has several different evidence boundaries: shared Rust API clients, +the provider router, Tauri IPC and cookie handling, SQLite task persistence, React +state, the Three.js editor and the separate egui app. A result in one does not establish +the same result in another. Backend services are outside this repository. + +It does not introduce a universal result type, numbered stages or new approval +machinery. Existing Rust `anyhow` conventions, schema types, module layout, two-space +style, API endpoint/command files and pagescene invariants remain in force. + +## Define the claim before its implementation + +For a consequential capability, write a small observable contract: input/state/sequence, +success, refusal, side effects and required evidence. Number items when traceability +helps; do not create a document for every trivial edit. Include cancellation and failure +behavior rather than specifying only a happy-path screenshot. + +For example, a router draft cost estimate should not trigger media upload or generation. +The existing video instructions already distinguish draft, finalize and send phases. +Tests should observe which operation actually occurred, not merely assert a helper's name. +For pagescene, a mode switch that hides chrome must preserve the mounted engine canvases +and the unsaved scene. The nested invariant is the contract; a new visual arrangement +must not silently redefine it. + +Prefer typed identities where the code already distinguishes identity spaces, reuse +the schema tokens, and keep primitives at external seams. Preserve existing error +idioms within a boundary. Avoid mass API/type migrations in an unrelated repair. +Keep dependency direction and state authority explicit; a new convenience abstraction +must not become a second engine, store or provider-routing authority. + +## Reproduce defects before fixes + +A reported defect is a hypothesis. First write the smallest test that names its trigger, +run it against the unfixed code and read the failure. Only then fix. A passing pre-fix +test means the test did not reach the alleged fault or the diagnosis needs revision. +Do not invent a red result when the environment cannot execute it: label the test an +unrun draft and state the missing runtime, dependency or native surface. + +Write assertions alongside new behavior. A load-bearing dependency assumption, a +comment promising behavior under a named scenario and a numbered contract item each +deserve a test that can distinguish the promised outcome from a plausible wrong one. +Choose expectations from the contract, not from the finished implementation's output. +Exercise acceptance and refusal. For recurring omissions, a convention/property guard +can cover the class better than an enumeration of today's examples. + +Where a defect cannot be automated, record why and exercise the nearest observable +boundary plus a concrete manual reproduction. Compilation errors need compile evidence; +visual judgments need visual evidence. Never weaken, skip or delete a valid assertion +to make a repair appear successful. An obsolete assertion can change only with an +explicitly justified contract change. + +## Make evidence reproducible and bounded + +Record the revision, command, platform, fixture/input, result and limitation. Inspect +completed artifacts rather than infer final behavior from in-flight state. Pin rolling +measurements and remeasure after correcting the method. Verify paths, hashes and bytes +where multiple checkouts or encodings can make plausible output misleading. + +Use local fixtures and temporary stores for ordinary tests. A loopback login test can +prove native request/cookie behavior under its fixture; it cannot prove a production +provider, another OS or an artist's live account. A frontend build proves compilation, +not native IPC or user acceptance. Source inspection and an unrun test are different +evidence again. Report absent credentials and skipped native surfaces explicitly. + +Select checks by reach: changed crate/library first; affected consumers for shared types; +full relevant build boundaries for broad dependency/configuration changes. Read actual +manifests and scripts rather than invent one universal monorepo command. Existing examples: + +- Rust crate: `cargo check -p ` / `cargo test -p `; SQLx paths use + `SQLX_OFFLINE=true` and retain `.sqlx/` plus SQLite migrations. +- Native login: the existing local `login_bridge_tests` command in the command/client + instructions and the desktop-session regression guide. +- Pure Rust app: `cargo test -p artcraft_native`, with unit and `egui_kittest` coverage. +- Frontend: owning package/Nx targets, existing specs and relevant desktop-session checks. + +Documentation changes check links, preserved conventions and the final diff. + +## Optional: review by trying to falsify a claim + +The workflows in this section and the next are opt-in; the root rules do not require +them. + +Self-review is useful but shares the author's assumptions. For consequential changes, +seek a fresh context over a pinned diff and relevant contracts. Give it one concrete +claim to falsify, not an incentive to manufacture a list of findings. A clean answer +is legitimate when it states its scope and what it did not examine. + +First ask cold whether the implementation's claim holds, without the author's +suspicions. Separately, supply the author's reasoning and alternatives and ask whether +that reasoning holds. Combining those briefs anchors both onto the same explanation. +Independent agreement is evidence; one reviewer's finding is a lead to reproduce. + +A useful finding includes a trigger, affected boundary and an executed failing +reproducer where possible; otherwise it includes a labelled draft. Verify the mechanism +before fixing. Green does not refute a finding if the test did not reach it. Close +confirmed in-scope defects and review the changed lines again; report out-of-scope or +maintainer-owned decisions instead of silently expanding the change. + +For a bounded optional review loop, name the claims and set a round ceiling before +dispatch. Stop on convergence, meaning no remaining substantiated defects in scope, +or report the limit and outstanding work. A capped loop is not convergence. Report +scope, omissions, rounds and cumulative agents when used. This workflow is optional; +it grants no permission to spawn agents or turn an agent report into maintainer approval. + +## Optional: concurrent agents and shared work + +Pin the revision a reviewer reads. Do not let another agent edit underneath that read: +use separate worktrees/scratch for execution or serialize read and write phases. +Assign one owner when findings touch the same files. A discovery reproducer runs in +the reviewer's isolated tree; the landing author reruns it on the actual branch and +owns the red/green evidence. A reviewer without execution capability supplies a draft. + +Preserve unrelated tracked, untracked and ignored files. Do not reset, clean, stage +everything or kill shared processes as a shortcut. Separate ports alone do not isolate +ArtCraft's account data, cookie stores, app paths or Cargo locks. Follow the launcher +documentation and use test-owned temporary resources rather than a developer's profile. +Pass through supplied model, effort and budget limits; do not silently increase fan-out. +Pause dependent work for a real owner decision while completing independent authorized work. + +## Scope, dependencies and delivery + +User authorization defines scope. Paid provider calls, uploads, credential access, +external messages, releases and destructive operations need their own authorization. +Ordinary local tests use synthetic fixtures. Keep secrets and private customer +material out of source, logs and PR evidence. + +Read a dependency's actual contract/source before wrapping it or claiming it cannot do +something. If a workaround is needed, name the dependency behavior, cost and retirement +condition; add a probe when that behavior is load-bearing. Prefer removing the cause +within scope, and separate adjacent architectural changes into their own reviewable work. + +When delivering through a PR, describe the complete final change, evidence and +limitations. A green suite does not grant wider scope. Keep lasting rationale in the +repository; a PR description alone may be lost at merge. + +## Instruction discovery and maintenance + +The root `AGENTS.md` is the universal entrypoint and holds layout and style; nested +instructions own their context; this methodology owns explanations and optional +workflows. Tools differ in when they load nested files: Claude Code loads a +subdirectory's `AGENTS.md` when it reads a file there, while Codex reads the files from +the root down to its working directory at startup. So a session started at the root +should read each affected directory's `AGENTS.md` explicitly before editing. + +Instruction files are named `AGENTS.md` only. Claude Code v2.1.277 and later reads them +directly, but only when no `CLAUDE.md` or `CLAUDE.local.md` is on the path. A +`CLAUDE.md` symlink is unnecessary, and harmful on Windows: Git for Windows checks +symlinks out as one-line text files unless `core.symlinks` is enabled, and that one-line +`CLAUDE.md` then hides the real instructions. Contributors who keep a personal +`CLAUDE.local.md` can set Claude Code's "Project instructions" option to +`claude-md-and-agents-md` to load both. + +Keep instructions concise and durable. State the failure prevented and the actual +guard or manual check. Do not claim prose enforces permissions or reader/writer isolation. +Report concrete friction with an example rather than praise or copy another project's +rule by default. Do not require a phrase or a paragraph to remain in an entrypoint just +to satisfy a test; guard the behavior or owned contract instead. + +Codex discovery reference: [official AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md). +Claude discovery/reference: [official memory and instruction guide](https://code.claude.com/docs/en/memory). +Tool versions and configuration affect discovery; verify loaded files in the actual +session (in Claude Code, `/memory` lists them). + +## Status of each part + +| Part | Where | Status | +|------------------------|------------------------------|--------------------------------------------| +| Operative rules | Root and nested `AGENTS.md` | Agents follow them | +| Explanation | This document | Reference only | +| Optional deeper review | This document | Opt-in; no required agent count or cadence | +| Mechanical enforcement | Not implemented | Possible follow-up, such as a link check | diff --git a/artcraft-native/AGENTS.md b/artcraft-native/AGENTS.md new file mode 100644 --- /dev/null +++ b/artcraft-native/AGENTS.md @@ -0,0 +1,16 @@ +# Pure Rust native app + +Read this app's `README.md` before changing its architecture or known limitations. +This egui host is separate from Tauri; do not import webview/React architecture into +ordinary UI code. The dedicated sign-in webview remains its own credential boundary. + +- Backend owns Tokio/API work and returns events to the UI. Keep network/download/decode + work off the UI thread and reuse shared API client/router crates at their public seams. +- Preserve session ownership and identity headers. Test with temporary synthetic files; + never use or expose a developer's cookie jar, provider credentials or real library. +- Write defect reproducers in native unit or `egui_kittest` coverage before fixes. + Async results, cancellation, retries and restart recovery need explicit ownership. +- Run `cargo test -p artcraft_native` for affected behavior. It does not prove real + generation, credential interoperability, native-window behavior or visual quality. +- Do not claim full parity from a test of one control; name the operation and boundary + actually exercised. Keep known limitations visible in the owning README. diff --git a/crates/AGENTS.md b/crates/AGENTS.md --- a/crates/AGENTS.md +++ b/crates/AGENTS.md @@ -42,6 +42,11 @@ helpers go in the parent `mod tests` so sub-modules can `use super::*`. ## Building +Write defect reproducers before fixes and confirm the failure's cause. Use local +fixtures and temporary stores; ignored live-provider tests remain explicitly invoked. +When shared wire types or routing change, check affected consumers, not only the +crate that defines them. Report compilation, fixture and live/native evidence separately. + - Most crates: `cargo check -p {crate_name}` or `cargo test -p {crate_name}` - Crates using SQLx: `SQLX_OFFLINE=true cargo check -p {crate_name}` - The desktop SQLite query cache and migrations must remain in `.sqlx/` and `_database/sql/artcraft_migrations/` diff --git a/crates/CLAUDE.md b/crates/CLAUDE.md deleted file mode 120000 --- a/crates/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/crates/api_clients/artcraft/artcraft_api_defs/CLAUDE.md b/crates/api_clients/artcraft/artcraft_api_defs/CLAUDE.md deleted file mode 120000 --- a/crates/api_clients/artcraft/artcraft_api_defs/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/crates/api_clients/artcraft/artcraft_client/AGENTS.md b/crates/api_clients/artcraft/artcraft_client/AGENTS.md --- a/crates/api_clients/artcraft/artcraft_client/AGENTS.md +++ b/crates/api_clients/artcraft/artcraft_client/AGENTS.md @@ -22,6 +22,10 @@ Rust HTTP endpoint bindings used by the ArtCraft Tauri desktop app. ## Validation +Pin method/path/header/cookie defects with a local HTTP fixture before fixing them. +Do not substitute a live account call for an ordinary regression test. Shared wire +changes also inspect `artcraft_api_defs` and both desktop consumers. + Run `cargo check --offline -p artcraft_client` for client changes. For native login bindings, also run `SQLX_OFFLINE=true cargo test --offline -p artcraft --lib login_bridge_tests`; these tests use local HTTP fixtures and temporary cookie jars. diff --git a/crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/CLAUDE.md b/crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/CLAUDE.md deleted file mode 120000 --- a/crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/crates/desktop/artcraft/src/services/storyteller/commands/AGENTS.md b/crates/desktop/artcraft/src/services/storyteller/commands/AGENTS.md --- a/crates/desktop/artcraft/src/services/storyteller/commands/AGENTS.md +++ b/crates/desktop/artcraft/src/services/storyteller/commands/AGENTS.md @@ -1,5 +1,9 @@ # Tauri Commands +Reproduce IPC/authentication defects at the native command/client boundary before +fixing them. Frontend mocks do not prove Rust cookie behavior or Tauri registration. +Use local fixtures and temporary stores; report native startup separately. + - Put each `#[tauri::command]` function in its own `.rs` file module named after that command, such as `storyteller_create_login_challenge_command.rs`. Do not collect multiple commands in a catch-all `*_commands.rs` file. diff --git a/crates/schema/public/enums/CLAUDE.md b/crates/schema/public/enums/CLAUDE.md deleted file mode 120000 --- a/crates/schema/public/enums/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/crates/schema/public/tokens/CLAUDE.md b/crates/schema/public/tokens/CLAUDE.md deleted file mode 120000 --- a/crates/schema/public/tokens/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md new file mode 100644 --- /dev/null +++ b/frontend/AGENTS.md @@ -0,0 +1,19 @@ +# Frontend boundaries + +Use the existing Nx/React/Vite/Zustand/Three.js structure and the root style rules. +Inspect the owning package's scripts and test configuration before choosing a command; +do not assume every library exposes the same test target. + +- Keep host-specific HTTP, upload, auth and navigation in the owning adapter. Reuse + existing components and stores rather than creating a parallel state authority. +- For UI defects, reproduce the observable event/state sequence in the owning test + suite before fixing. Include refusal, cancellation and teardown paths where relevant. +- Pagescene has its own `AGENTS.md`: keep canvases mounted, preserve the + engine → bus → bridge → store → React flow and route shortcuts through the registry. +- Mechanical interaction checks and native-webview/visual evidence are separate. + Browser-only success does not prove Tauri IPC, cookies or native filesystem behavior. +- Use synthetic fixtures and local servers by default. Live uploads, provider calls, + account operations and paid generation are not ordinary test dependencies. + +Run affected tests/build targets and broaden for shared libraries. For login, origin, +port or session changes also follow `docs/desktop-session-regression.md` from the root. diff --git a/frontend/libs/components/pagescene/AGENTS.md b/frontend/libs/components/pagescene/AGENTS.md --- a/frontend/libs/components/pagescene/AGENTS.md +++ b/frontend/libs/components/pagescene/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md — pagescene (3D Scene Editor) +# AGENTS.md — pagescene (3D Scene Editor) Guidance for working in the `pagescene` library — the 3D editor (a.k.a. "pagescene" / "Stage3D"). diff --git a/frontend/libs/components/pagescene/CLAUDE.md b/frontend/libs/components/pagescene/CLAUDE.md deleted file mode 120000 --- a/frontend/libs/components/pagescene/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file