[v4] Agents (#52)

* macros + format

* add benchmark to lint

* agents.md

* tweaks to agents.md

* fix typos

* add .gemini

* hide banner

* Update .clang-format

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix comment

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 2 people

.clang-format

@@ -2,19 +2,27 @@
 Language: Cpp
 ColumnLimit: 110
 IndentPPDirectives: BeforeHash
-AlwaysBreakTemplateDeclarations : true
-PackConstructorInitializers : CurrentLine
+AlwaysBreakTemplateDeclarations: Yes
+PackConstructorInitializers: CurrentLine
 AccessModifierOffset: -1
-IndentCaseLabels : true
+IndentCaseLabels: true
 AllowShortLambdasOnASingleLine: Empty
 RequiresExpressionIndentation: OuterScope
-BinPackArguments : false
-BinPackParameters : false
-LambdaBodyIndentation : Signature
-PenaltyReturnTypeOnItsOwnLine : 1
+BinPackArguments: false
+# BinPackParameters: false
+LambdaBodyIndentation: Signature
+PenaltyReturnTypeOnItsOwnLine: 1
+
+Macros:
+  - LF_HOF(x)={x;}
+  - LF_HOF(x,y)={x,y;}
+  - LF_HOF(x,y,z)={x,y,z;}
+  - LF_HOF(x,y,z,w)={x,y,z,w;}
+  - LF_HOF(a,b,c,d,e)={a;}
+  - LF_HOF(a,b,c,d,e,f)={a,b,c,d,e,f;}
 
 SpaceBeforeParens: Custom
 SpaceBeforeParensOptions:
-    AfterRequiresInClause: true
-    AfterRequiresInExpression : true
+  AfterRequiresInClause: true
+  AfterRequiresInExpression: true
 ...

.codespellrc

@@ -3,5 +3,5 @@ builtin = clear,rare,en-GB_to_en-US,names,informal,code
 check-filenames =
 check-hidden =
 ignore-words-list = deque,warmup,stdio,copyable,combinate
-skip = */.git,*/build,*/prefix,*/vcpkg,*/_build,*/bench
+skip = */.git,*/build,*/.legacy
 quiet-level = 2

.gemini/settings.json

@@ -0,0 +1,8 @@
+{
+  "context": {
+    "fileName": "AGENTS.md"
+  },
+  "ui": {
+    "hideBanner": true
+  }
+}

.github/workflows/lint.yml

@@ -25,4 +25,4 @@ jobs:
 
       - name: Run clang-format
         run: |
-          find src include test -name "*.cpp" -o -name "*.hpp" -o -name "*.cxx" | xargs clang-format --dry-run --Werror
+          find src include test benchmark/src -name "*.cpp" -o -name "*.hpp" -o -name "*.cxx" | xargs clang-format --dry-run --Werror

.legacy/include/libfork/core/macro.hpp

@@ -61,17 +61,6 @@
   #define LF_STATIC_CONST const
 #endif
 
-// clang-format off
-
-/**
- * @brief Use like `BOOST_HOF_RETURNS` to define a function/lambda with all the noexcept/requires/decltype specifiers.
- * 
- * This macro is not truly variadic but the ``...`` allows commas in the macro argument.
- */
-#define LF_HOF_RETURNS(...) noexcept(noexcept(__VA_ARGS__)) -> decltype(__VA_ARGS__) requires requires { __VA_ARGS__; } { return __VA_ARGS__;}
-
-// clang-format on
-
 /**
  * @brief __[public]__ Detects if the compiler has exceptions enabled.
  *

AGENTS.md

@@ -0,0 +1,229 @@
+# Libfork Copilot Instructions
+
+## Project Overview
+
+**libfork** is a continuation-stealing coroutine-tasking library implementing
+strict fork-join parallelism using C++20 coroutines.
+
+- **Type**: C++ library with module/`import std` support
+- **Languages**: C++23
+
+## Critical Build Requirements
+
+### Compiler & Module Support
+
+This project **requires C++23 `import std`** and **MUST** use the appropriate
+toolchain file:
+
+- **MacOS**: Use `-DCMAKE_TOOLCHAIN_FILE=cmake/llvm-brew-toolchain.cmake`
+- **Linux**: Use `-DCMAKE_TOOLCHAIN_FILE=cmake/gcc-brew-toolchain.cmake`
+
+**Common Error**: Without the toolchain file, CMake will fail.
+
+**Always include the toolchain file** in configure commands.
+
+### Dependencies (Homebrew)
+
+Make sure Homebrew is installed and `brew` is in your `PATH`:
+
+```bash
+brew --version
+```
+
+**Required for building/testing:**
+
+- `cmake`
+- `ninja`
+- `catch2`
+- `google-benchmark`
+- `clang-format`
+- `codespell`
+
+If on MacOS, also require:
+
+- `llvm`
+
+If on Linux, also require:
+
+- `gcc`
+- `binutils`
+
+Install all at once (MacOS):
+
+```bash
+brew install cmake ninja catch2 google-benchmark clang-format codespell llvm
+```
+
+Install all at once (Linux):
+
+```bash
+brew install cmake ninja catch2 google-benchmark clang-format codespell gcc binutils
+```
+
+## Build & Test Workflow
+
+### 1. Configure
+
+Always use presets with the toolchain file:
+
+```bash
+cmake --preset <preset-name> -DCMAKE_TOOLCHAIN_FILE=cmake/<toolchain>.cmake
+```
+
+**Relevant available presets** (from `CMakePresets.json`):
+
+- `ci-hardened` - Debug build with warnings and hardening flags
+- `ci-release` - Optimized release build
+
+All presets enable developer mode (`libfork_DEV_MODE=ON`) and use Ninja generator.
+
+You should use the `ci-hardened` preset for development/testing and
+`ci-release` for benchmarking.
+
+### 2. Build
+
+```bash
+cmake --build --preset <preset-name>
+```
+
+**Build warnings** (expected and safe):
+
+- "It is recommended to build benchmarks in Release mode" - only relevant for `ci-hardened`
+- CMake experimental `import std;` warning - expected for C++23 modules
+
+### 3. Test
+
+```bash
+ctest --preset <preset-name>
+```
+
+All tests should pass. If tests fail, check that:
+
+- Configuration used the correct toolchain file
+- Build completed without errors
+- Any changes you have made are correct
+
+## Linting & Validation
+
+The CI runs two linting tools that you should run before committing:
+
+### codespell (spelling)
+
+```bash
+codespell
+```
+
+Config: `.codespellrc` (ignores: build/, .git/, etc.)
+Should produce no output if passing.
+
+### clang-format (code formatting)
+
+```bash
+find src include test benchmark/src -name "*.cpp" -o -name "*.hpp" -o -name "*.cxx" | xargs clang-format --dry-run --Werror
+```
+
+Config: `.clang-format` (110 column limit, specific style)
+Should produce no output if passing.
+
+**To auto-fix formatting**:
+
+```bash
+find src include test benchmark/src -name "*.cpp" -o -name "*.hpp" -o -name "*.cxx" | xargs clang-format -i
+```
+
+## Project Structure
+
+### Source Layout
+
+```sh
+libfork/
+├── cmake/                    # CMake utilities
+├── include/libfork/**/*.hpp  # Public headers
+├── src/**/                   # Module and source files
+│   ├── *.cxx                 # Module files
+│   └── *.cpp                 # Source files
+├── test/src/**/              # Test suite (Catch2)
+│   └── *.cpp                 # Test source files
+├── benchmark/src/            # Benchmarking suite (google-benchmark)
+│   └── libfork_benchmark/    # Merged source/header files for benchmarks
+│          └── fib/           # Each benchmark in its own sub-directory
+│              ├── *.hpp      # Benchmark header files
+│              └── *.cpp      # Benchmark source files
+├── .github/workflows/        # CI workflows
+│   ├── linux.yml             # Linux builds
+│   ├── macos.yml             # MacOS builds
+│   ├── lint.yml              # Linting
+│   └── linear.yml            # Enforces linear history (no merge commits)
+└── CMakeLists.txt            # Main build configuration
+```
+
+## Workflows
+
+### Workflow Command Pattern
+
+All workflows follow this pattern:
+
+```yaml
+- Install Dependencies: brew install ...
+- Configure: cmake --preset <preset> -DCMAKE_TOOLCHAIN_FILE=<toolchain>.cmake
+- Build: cmake --build --preset <preset> 
+- Test: ctest --preset <preset>
+```
+
+## Common Development Tasks
+
+### Making Code Changes
+
+1. **Modify source files** in `src/`, `include/`, `test/`, or `benchmark/`
+2. **Rebuild**: `cmake --build --preset <your-preset>`
+3. **Test**: `ctest --preset <your-preset>`
+4. **Lint**: Run codespell and clang-format checks
+
+#### Adding/removing files from `src/` or `include/`
+
+- Update the root `CMakeLists.txt` with new/removed files.
+
+#### Adding/removing files from `benchmark/src/`
+
+- Update `benchmark/CMakeLists.txt` with new/removed files.
+
+### Adding Tests
+
+Strive to add tests for new features/bug fixes.
+
+- Add `.cpp` files to `test/src/`
+- Tests auto-discovered by CMake (GLOB_RECURSE)
+- Links against `libfork::libfork` and `Catch2::Catch2WithMain`
+- Uses `cxx_std_23` feature requirement
+
+### Modifying Build Configuration
+
+**Warning**: Module-related changes are complex. Test thoroughly with clean builds.
+
+## Troubleshooting
+
+### Build Failures
+
+**Problem**: Configuration/Build fails after adding/removing files or modifying CMakeLists.txt
+**Solution**: Try a clean build directory:
+
+```bash
+rm -rf build/
+```
+
+**Problem**: "compiler does not provide a way to discover the import graph"
+**Solution**: Add `-DCMAKE_TOOLCHAIN_FILE=cmake/llvm-brew-toolchain.cmake` to configure
+
+**Problem**: "Could not find 'brew' executable"  
+**Solution**: Install Homebrew
+
+**Problem**: "Could not automatically find libc++.modules.json"
+**Solution**: Ensure LLVM is installed via Homebrew; toolchain auto-detects the path
+
+### Linting Failures
+
+**Problem**: clang-format errors
+**Solution**: Run fix command above to auto-format code
+
+**Problem**: codespell errors  
+**Solution**: Fix typos or add to ignore list in `.codespellrc` if false positive

include/libfork/macros.hpp

@@ -9,6 +9,24 @@
  * however, only macros that are marked as __[public]__ should be consumed.
  */
 
+// =============== Utility =============== //
+
+// clang-format off
+
+/**
+ * @brief Use like `BOOST_HOF_RETURNS` to define a function/lambda with all the noexcept/decltype specifiers.
+ *
+ * This macro is not truly variadic but the ``...`` allows commas in the macro argument.
+ */
+#define LF_HOF(...) noexcept(noexcept(__VA_ARGS__)) -> decltype(__VA_ARGS__) { return __VA_ARGS__;}
+
+// clang-format on
+
+/**
+ * @brief Use like `std::forward` to perfectly forward an expression.
+ */
+#define LF_FWD(...) std::forward<decltype(__VA_ARGS__)>(__VA_ARGS__)
+
 // =============== Inlining/optimization =============== //
 
 /**

src/core/promise.cxx

@@ -1,27 +1,36 @@
 module;
 #include <version>
+
+#include "libfork/macros.hpp"
 export module libfork.core:promise;
 
 import std;
 
 namespace lf {
 
-export template <typename T>
-struct promise {
-  auto test() -> std::string_view { return "hi"; }
-};
+// =============== Frame =============== //
 
 struct frame_type {
   frame_type *parent;
 };
 
 static_assert(std::is_standard_layout_v<frame_type>);
 
+// =============== Frame-mixin =============== //
+
+struct mixin_frame {
+  auto self(this auto &&self) LF_HOF(LF_FWD(self).frame)
+};
+
+static_assert(std::is_empty_v<mixin_frame>);
+
+// =============== Promises =============== //
+
 template <typename T>
 struct promise_type;
 
 template <>
-struct promise_type<void> {
+struct promise_type<void> : mixin_frame {
   frame_type frame;
 };
 
@@ -34,7 +43,7 @@ static_assert(std::is_standard_layout_v<promise_type<void>>);
 #endif
 
 template <typename T>
-struct promise_type {
+struct promise_type : mixin_frame {
   frame_type frame;
   T *return_address;
 };

test/src/promise.cpp

@@ -3,6 +3,5 @@
 import libfork.core;
 
 TEST_CASE("Promise test", "[promise]") {
-  lf::promise<int> p;
-  REQUIRE(p.test() == "hi");
+  // TODO:
 }