From d03a661a44eed306f82cf63abb02d34806ed5bb7 Mon Sep 17 00:00:00 2001
From: Abdelrahman Said <said.abdelrahman@flawlessai.com>
Date: Fri, 26 Jun 2026 23:27:12 +0100
Subject: [PATCH] Add AGENTS.md with project conventions and workflows

---
 AGENTS.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..37d0d0c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,134 @@
+# AGENTS.md — Prism
+
+## Project Identity
+
+**Prism** is a node-based image compositing tool. Images flow through a directed
+acyclic graph (DAG) of processing nodes (read, blend, colour-grade, etc.) and
+are rendered via GPU shaders.
+
+- **Language**: C11 / C++11 (dual-mode, like `src/wapp/`)
+- **GPU API**: Vulkan, abstracted behind a Rendering Hardware Interface (RHI)
+- **Shading language**: Slang, stored in external `.slang` files under `src/shaders/`
+- **Build**: TBD — either a standalone shell build script or a `justfile` (Just)
+- **Dependencies**: `src/wapp/` (local utility library, already vendored)
+
+## Coding Conventions
+
+All code follows the patterns established in `src/wapp/`. The project prefix is
+`pr` (functions/macros) / `Pr` (types).
+
+### Naming
+
+| Category              | Convention             | Examples                        |
+|-----------------------|------------------------|---------------------------------|
+| Types                 | `Pr` + PascalCase      | `PrNode`, `PrGraph`, `PrImage`  |
+| Functions             | `pr` + PascalCase      | `prGraphCreate`, `prNodeEval`   |
+| Macros                | `pr` + PascalCase      | `prArrayOf`, `prNodeType`       |
+| Enum constants        | `PR_` + SCREAMING_SNAKE| `PR_NODE_BLEND`, `PR_OK`        |
+| Internal/static funcs | `_` + camelCase        | `_resolveTopology`, `_execCmd`  |
+| File-scope globals    | `_` + camelCase        | `_default_allocator`            |
+| File-scope constants  | SCREAMING_SNAKE        | `MAX_NODE_NAME`                 |
+
+### Storage qualifiers
+
+Use the `wp_extern` / `wp_intern` / `wp_persist` aliases from wapp:
+
+```c
+wp_extern void prGraphInit(PrGraph *g);     // extern linkage
+wp_intern void _helper(void);               // static (file-scope)
+wp_persist u32 _counter;                     // static (file-scope, mutable)
+```
+
+### Structs
+
+POD structs with typedef, following `wapp/base/` patterns. Functions operate
+on structs by pointer rather than through vtables:
+
+```c
+typedef struct PrNode PrNode;
+struct PrNode {
+    PrNodeType  type;
+    u32         input_count;
+    PrNode    **inputs;
+    // ...
+};
+
+void prNodeInit(PrNode *n, PrAllocator *alloc);
+void prNodeEval(PrNode *n, PrRhiCmdList *cl);
+void prNodeDestroy(PrNode *n, PrAllocator *alloc);
+```
+
+### Memory management
+
+Use wapp allocators (`WpAllocator`, arena-based). Stack-allocate where
+possible; pass allocators explicitly.
+
+```c
+PrGraph *prGraphCreate(PrAllocator *alloc);
+void     prGraphDestroy(PrGraph *g, PrAllocator *alloc);
+```
+
+### File organisation
+
+One `.h` / `.c` pair per module, grouped in subdirectories by subsystem.
+A top-level umbrella header re-exports everything (see `src/wapp/wapp.h`).
+
+```
+src/prism/prism.h        ← umbrella include
+src/prism/core/          ← graph, node types, DAG
+src/prism/rhi/           ← rendering hardware interface
+src/prism/node/          ← node implementations
+src/prism/app/           ← entry point, window, main loop
+```
+
+Shaders live in a flat-ish `src/shaders/` tree:
+
+```
+src/shaders/blit.slang
+src/shaders/blend.slang
+src/shaders/common/       ← shared include files
+```
+
+### Data-oriented design
+
+For hot paths (per-frame graph evaluation, image transfers, shader dispatch)
+prefer SoA layouts, batch processing, and minimise pointer chasing. Keep
+the DAG in contiguous arrays (e.g. adjacency lists packed in flat buffers)
+rather than individually allocated linked structures.
+
+## Documentation
+
+Save research notes and implementation plans as markdown in `documents/`:
+
+```
+documents/
+├── ARCHITECTURE.md
+├── RENDERING_HARDWARE_INTERFACE.md
+├── NODE_SYSTEM.md
+├── ROADMAP.md
+└── research/
+    └── vulkan-baseline.md
+```
+
+## Workflows for AI agents
+
+### Research / planning
+
+1. Save findings to `documents/research/<topic>.md`.
+2. When asked for a plan, write it to `documents/<PLAN_NAME>.md` and present
+   a summary; iterate on the plan before writing any code.
+3. Only start implementing after the plan is approved.
+
+### Learning from edits
+
+The user may edit code produced by AI agents. When this happens, infer the
+reason for the change and update AGENTS.md with any new conventions, patterns,
+or constraints that the edit reveals. This keeps the guide aligned with the
+user's evolving preferences.
+
+### Committing
+
+Only commit when explicitly asked. When asked:
+- Stage only intended files.
+- Write a short, conventional commit message in present tense.
+- Never amend, force-push, or create PRs without a request.