Restructure agent setup

AGENTS.md

@@ -9,7 +9,7 @@ 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)
+- **Build**: `justfile` (Just) as a task runner
 - **Dependencies**: `src/wapp/` (local utility library, already vendored)
 
 ## Coding Conventions
@@ -34,25 +34,20 @@ All code follows the patterns established in `src/wapp/`. The project prefix is
 
 ### Formatting
 
-- **Indentation**: tabs (no spaces). Tab width is a viewer preference.
-- **Braces**: always required after `if`, `else`, `for`, `while`, `do` — even
-  when the body is a single statement. This avoids ambiguity and makes diffs
-  cleaner.
+Machine-enforceable rules (tabs, braces, pointer alignment, continuation
+alignment) are in `.clang-format` — run `clang-format -i <file>` to apply.
 
-```c
-// correct
-if (condition) {
-	do_thing();
-}
-
-for (int i = 0; i < n; i++) {
-	process(i);
-}
-
-// wrong — no braces, spaces instead of tabs
-if (condition)
-	do_thing();
-```
+- **Return-type alignment**: Within each `// =====` section, align function
+  declaration names so the first letter of every function occupies the same
+  column. For pointer return types, place `*` directly against the function
+  name (no space) and put all alignment padding between the type name and `*`.
+  ```c
+  // correct — * against fn name, padding before *
+  PrRhiSwapchain      *prRhiCreateSwapchain(…);
+  void                 prRhiDestroySwapchain(…);
+  PrRhiSwapchainResult prRhiAcquireNextImage(…);
+  ```
+  This cannot be automated by clang-format and must be done manually.
 
 ### Storage qualifiers
 
@@ -171,6 +166,16 @@ Always use typed array aliases (`WpU64Array`, `PrNodeIdArray`, etc.) rather
 than raw pointers when declaring array variables. Follow the existing typedef
 pattern in the module (`typedef Type *TypeArray`).
 
+Typedef pattern:
+- Opaque handles use `**` (pointer-to-pointer)
+- Value types use `*` (contiguous block)
+```c
+typedef PrRhiBuffer         **PrRhiBufferArray;           // opaque handles → **
+typedef PrRhiColorAttachment *PrRhiColorAttachmentArray;  // value types → *
+```
+Group opaque handle arrays first, value type arrays second, separated by a
+blank line.
+
 Use named init flags (`WP_ARRAY_INIT_NONE`, `WP_ARRAY_INIT_FILLED`) instead of
 bare `0` — they make the initialisation policy explicit.
 
@@ -202,10 +207,21 @@ documents/
 ├── RENDERING_HARDWARE_INTERFACE.md
 ├── NODE_SYSTEM.md
 ├── ROADMAP.md
-└── research/
-    └── vulkan-baseline.md
+├── research/
+│   └── <topic>.md
+└── session-logs/
+    └── YYYY-MM-DD.md
 ```
 
+## Skills
+
+Domain-specific conventions are stored as skills in `.opencode/skills/<name>/SKILL.md`.
+These are loaded on-demand by the AI agent when a task matches their description,
+keeping AGENTS.md lean.
+
+- **`prism-rhi`** — RHI backend dispatch, by-value descs, file layout
+- **`prism-dag`** — DAG adjacency lists, arena allocation, Kahn's algorithm
+
 ## Workflows for AI agents
 
 ### Research / planning
@@ -215,20 +231,12 @@ documents/
    a summary; iterate on the plan before writing any code.
 3. Only start implementing after the plan is approved.
 
-### README
+### Skill maintenance
 
-Keep `README.md` in sync with the project as it evolves. Update it when:
-- The directory layout changes meaningfully
-- Language, toolchain, or build system decisions are settled
-- Dependencies are added or removed
-- The project reaches a notable milestone
-
-### 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.
+When you observe the user correcting your output (e.g. formatting, conventions),
+infer the rule and add it to the relevant skill's `SKILL.md`. If no skill
+matches, add a new one. This keeps AGENTS.md focused on project identity and
+critical workflow rules rather than accumulating domain details.
 
 ### Committing
 
@@ -236,30 +244,3 @@ 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.
-
-## Session Log — 2026-07-05
-
-### Completed
-- **DAG refactoring** (`scratchpad/dag.c`): Decoupled PrGraph from PrNodeManager.
-  Graph tracks its own active vertices (`vertex_count`, `max_vertex_ever`, `b8 active`).
-  `prGraphAddEdge`, `prGraphTopologicalSort` no longer take `PrNodeManager*`.
-  Kahn's algorithm integrated into `prGraphAddEdge` for cycle detection with rollback.
-  Output verified matching baseline.
-- **RHI research document** written to `documents/research/rendering-hardware-interface.md`.
-  Covers 8 reference RHIs, architecture patterns, core API surface, Vulkan-specific
-  considerations, Slang integration, and proposed directory layout / lifecycle design.
-- Added NVRHI to `documents/resources.md`.
-
-### Key Decisions
-- Graph API is self-contained — no graphics or node-manager dependencies.
-- RHI will use object-based + command-list-oriented architecture with vtbl dispatch.
-- Object lifecycle: `prRhiCreate*` / `prRhiDestroy*` with explicit `WpAllocator*`.
-- All GPU state explicit (no hidden pipeline state).
-- Per-frame command pools and descriptor pools, arena-allocated scratch.
-- `#version-macro` convention removed from Slang files; `__slang` define used instead.
-
-### Next Steps
-1. User reviews RHI research document, then iterate if needed.
-2. Begin implementing RHI layer: types header, device creation, Vulkan backend skeleton.
-3. Implement Slang shader compilation + reflection integration.
-4. Wire up per-frame lifecycle (command pool reset, descriptor pool reset, scratch reset).