skills: Extract skills from memory

AGENTS.md

@@ -2,10 +2,16 @@
 
 ## Preferred Commands
 - Configure: `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On`
+- Configure on Windows:
+  `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On`
 - Build: `cmake --build build -j8`
 - Test: `ctest --test-dir build --output-on-failure`
 - Prefer targeted tests with `ctest --test-dir build -R <name> --output-on-failure`
   when the affected area is known, because the full enabled suite can be slow.
+- On Windows, do not run runtime test cases yet. Runtime tests are not supported
+  there, so skip them and report the skip instead of treating missing runtime
+  verification as a failure. Configure with `-DFLB_TESTS_RUNTIME=Off` and
+  prefer filtered non-runtime CTest runs over the full suite.
 - Run a focused integration test with
   `ctest --test-dir build -R flb-it-opentelemetry --output-on-failure`
 - Run the in-tree Python integration suite with:
@@ -29,8 +35,23 @@ Fluent Bit is a C/C++ monorepo built with CMake.
 
 Keep changes scoped: plugin logic in its plugin directory, shared behavior in `src/` or `lib/`.
 
+## Bundled Library Changes
+- Treat `lib/` as bundled third-party or separately maintained code unless the
+  specific path is clearly Fluent Bit-owned.
+- Before editing bundled library code, ask for explicit user confirmation. If
+  the agent environment supports confirmation popups, use one; otherwise ask in
+  chat before writing files.
+- Prefer changes that can be sent upstream as a focused patch. Keep bundled
+  library patches isolated from Fluent Bit glue code, and document the upstream
+  project/path in the close-out.
+- Do not mix bundled library edits with unrelated Fluent Bit core, plugin,
+  documentation, or test changes in the same commit unless the user explicitly
+  asks for that structure.
+
 ## Build, Test, and Development Commands
 - `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On`: configure with runtime + internal tests.
+- `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On`:
+  configure on Windows, where runtime tests are unsupported.
 - `cmake --build build -j8`: compile Fluent Bit and tests.
 - `ctest --test-dir build --output-on-failure`: run enabled tests.
 - `ctest --test-dir build -R flb-it-opentelemetry --output-on-failure`: run a focused integration test.
@@ -63,6 +84,12 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s
 - Add or update tests for behavior changes, especially protocol parsing and encoder/decoder paths.
 - Prefer targeted tests close to the changed module (`tests/internal`, plugin runtime tests).
 - Prefer focused `ctest -R ...` runs or specific test binaries when the touched area is known.
+- Windows exception: runtime test cases are not supported on Windows yet. When
+  working on Windows, do not run `tests/runtime`, `flb-rt-*` targets, or runtime
+  CTest matches as verification. Configure with `-DFLB_TESTS_RUNTIME=Off` so
+  unsupported runtime targets are not built. Run applicable non-runtime tests
+  instead and state clearly that runtime verification was skipped because the
+  platform does not support it.
 - Use `tests/integration` when validating end-to-end plugin behavior, network
   protocols, downstream request generation, or local fake-server interactions
   that are awkward to cover in `ctest` binaries alone.
@@ -81,6 +108,9 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s
   `cmake --build build -j8`
   `tests/integration/.venv/bin/python -m pytest <focused-scenario> -q`
   `VALGRIND=1 VALGRIND_STRICT=1 tests/integration/.venv/bin/python -m pytest <focused-scenario> -q`
+- On Windows, replace the configure command above with:
+  `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On`
+  and skip runtime test cases because they are not supported there.
 - Run broader test coverage when changing shared lifecycle, routing, storage, or accounting code.
 - Validate both success and failure paths (invalid payloads, boundary sizes, null/missing fields).
 - You can also run specific binaries from `build/bin` (e.g., `./bin/flb-it-opentelemetry`).
@@ -96,6 +126,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s
   - the exact focused integration command(s) run;
   - whether valgrind was used;
   - pass/fail status;
+  - on Windows, any runtime test cases intentionally skipped because runtime
+    tests are not supported there;
   - any concrete blocker if a required run could not be completed.
 - Keep generated integration artifacts out of git. Do not commit
   `.venv/`, `.pytest_cache/`, `results/`, or `__pycache__/` under
@@ -167,7 +199,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s
   path inference before choosing a commit subject. For example, changes only to
   `AGENTS.md` must use `agents:`, not `docs:`.
 - For pull-request-style validation, use full history and fetch the base branch
-  first, matching CI behavior:
+  first, matching CI behavior. This is required because the checker can fall
+  back to validating only `HEAD` when the base ref is unavailable:
   `git fetch --all --prune`
   `git fetch origin <base-branch>:origin/<base-branch>`
 - Before pushing a branch or opening/updating a PR, agents must lint the full
@@ -185,6 +218,7 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s
 - Do not open issues, pull requests, or remote branches unless the user explicitly asks.
 - Do not rewrite git history, amend commits, or force-push unless the user explicitly asks.
 - Do not revert user changes outside the requested scope.
+- Do not edit bundled libraries under `lib/` without explicit confirmation.
 - Prefer minimal patches that avoid unrelated formatting or refactoring churn.
 
 ## Agent Playbook (Pipeline Architecture Primer)
@@ -255,7 +289,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s
 
 ### Testing strategy
 - Use `tests/internal` for core lifecycle/accounting logic.
-- Use `tests/runtime` for plugin-level behavior and end-to-end semantics.
+- Use `tests/runtime` for plugin-level behavior and end-to-end semantics, except
+  on Windows where runtime test cases are not supported and must be skipped.
 - Add regression tests for:
   - mixed signals
   - processor drop/modify paths

skills/README.md

@@ -0,0 +1,38 @@
+# LLM Skills
+
+This directory contains portable Markdown skill bundles for LLM agents working
+in this repository. Each skill should live in its own subdirectory with a
+`SKILL.md` entrypoint and any focused companion guides it needs.
+
+## Available Skills
+
+- Fluent Bit: [`fluent-bit/SKILL.md`](fluent-bit/SKILL.md)
+  - Repository workflow, testing, patch review, pipeline architecture, and
+    recurring subsystem guidance for Fluent Bit work.
+  - Sub-skills:
+    - [`fluent-bit/patch-workflow.md`](fluent-bit/patch-workflow.md):
+      implementation, review, and commit workflow.
+    - [`fluent-bit/pipeline-architecture.md`](fluent-bit/pipeline-architecture.md):
+      runtime model for shared pipeline changes.
+    - [`fluent-bit/subsystem-patterns.md`](fluent-bit/subsystem-patterns.md):
+      recurring subsystem search routes and behavioral checks.
+    - [`fluent-bit/testing.md`](fluent-bit/testing.md):
+      focused CTest, integration, valgrind, and Windows runtime-test guidance.
+
+## How to Use
+
+Start with the skill entrypoint, then read only the companion files relevant to
+the task. For Fluent Bit work, begin with:
+
+```text
+skills/fluent-bit/SKILL.md
+```
+
+## Adding Skills
+
+When adding a new skill:
+
+- create a new subdirectory under `skills/`;
+- include a `SKILL.md` entrypoint;
+- keep instructions portable and tool-agnostic when possible;
+- update this index with the new skill name, entrypoint, and purpose.

skills/fluent-bit/README.md

@@ -0,0 +1,29 @@
+# Fluent Bit LLM Skills
+
+This folder contains portable Markdown skills for agents working on the Fluent
+Bit repository. They are intentionally tool-agnostic: any LLM can read these
+files as instructions, then use whatever shell, editor, or CI interface it has.
+
+## Files
+
+- `SKILL.md`: entrypoint and operating principles.
+- `testing.md`: focused CTest, integration, and valgrind expectations.
+- `patch-workflow.md`: implementation, review, and commit workflow.
+- `pipeline-architecture.md`: runtime model for shared pipeline changes.
+- `subsystem-patterns.md`: recurring Fluent Bit subsystem routes and checks.
+
+## Suggested Agent Prompt
+
+```text
+Before working in this repository, read skills/fluent-bit/SKILL.md.
+For code changes, also read skills/fluent-bit/patch-workflow.md and
+skills/fluent-bit/testing.md. For shared runtime changes, read
+skills/fluent-bit/pipeline-architecture.md. For known subsystem areas, read
+skills/fluent-bit/subsystem-patterns.md.
+```
+
+## Maintenance
+
+Keep these files concise and operational. Add subsystem notes only when they
+change how an agent should search, patch, test, or report work in this repo.
+

skills/fluent-bit/SKILL.md

@@ -0,0 +1,89 @@
+# Fluent Bit Repository Skill
+
+Use this skill when working in the Fluent Bit repository or in a similar
+C/C++ plugin-based telemetry pipeline. It is written for any LLM agent: read the
+relevant linked files, inspect the current checkout, make the smallest correct
+change, and report exact verification.
+
+## When to Use
+
+- A task mentions Fluent Bit source, tests, plugins, runtime behavior, routing,
+  storage, shutdown, configuration validation, or protocol encoding.
+- A task asks whether a reported Fluent Bit bug is still present.
+- A task asks for implementation or review of a Fluent Bit patch.
+- A task asks for the right focused tests, integration scenarios, or valgrind
+  checks for a touched Fluent Bit component.
+
+## Required Reading Order
+
+1. Read this file.
+2. Read `testing.md` before changing behavior or closing out a task.
+3. Read `patch-workflow.md` before editing code or reviewing a patch.
+4. Read `pipeline-architecture.md` for shared runtime, routing, lifecycle,
+   processor, chunk, task, storage, metrics, retry, or signal-aware changes.
+5. Read `subsystem-patterns.md` when the task touches one of the listed
+   recurring areas.
+
+## Operating Principles
+
+- Verify the current checkout before patching. A report may already be fixed.
+- Prefer the repository's existing helpers, source-of-truth resolvers, and
+  local conventions over new parallel logic.
+- Keep changes scoped to the affected component. Put plugin logic in its plugin
+  directory; shared behavior belongs in `src/`, `include/fluent-bit/`, or `lib/`.
+- Treat bundled libraries under `lib/` as third-party or separately maintained
+  code unless the path is clearly Fluent Bit-owned. Ask for explicit user
+  confirmation before editing them, using a confirmation popup when available.
+  Keep those edits isolated and upstreamable as focused patches.
+- Fix shared helper semantics when the bug is in a helper, instead of patching
+  only one visible caller.
+- Preserve real input paths. If the request asks to enrich or correct an
+  existing path, solve it in the relevant layer instead of faking another input
+  route.
+- Treat shutdown, architecture-specific failures, memory errors, and route
+  accounting mismatches as real lifecycle problems until traced through the
+  exact failing path.
+- Separate validated behavior from environment noise. If a focused test passes
+  but a broader legacy suite fails for unrelated reasons, report both signals.
+
+## Standard Commands
+
+```sh
+cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On
+cmake --build build -j8
+ctest --test-dir build --output-on-failure
+ctest --test-dir build -R <name> --output-on-failure
+./build/bin/fluent-bit -c conf/fluent-bit.conf
+```
+
+On Windows, skip runtime test cases. Runtime tests are not supported there yet,
+so configure with runtime tests disabled, use applicable non-runtime
+verification, and report the runtime-test skip:
+
+```sh
+cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On
+cmake --build build -j8
+ctest --test-dir build -R <non-runtime-name> --output-on-failure
+```
+
+For Python integration scenarios:
+
+```sh
+cd tests/integration && ./setup-venv.sh
+cd tests/integration && ./run_tests.py --list
+cd tests/integration && ./run_tests.py
+```
+
+## Close-Out Requirements
+
+Final responses for implementation tasks should include:
+
+- What changed, with file paths.
+- The exact verification commands run.
+- Pass/fail status.
+- Whether valgrind was used when integration coverage applies.
+- Any runtime tests skipped on Windows because runtime test cases are
+  unsupported there.
+- Any bundled library patch touched, including the upstream project/path and
+  confirmation that the user approved editing it.
+- Any concrete blocker for required tests that could not run.

skills/fluent-bit/patch-workflow.md

@@ -0,0 +1,97 @@
+# Fluent Bit Patch and Review Workflow
+
+Use this guide when implementing or reviewing Fluent Bit changes.
+
+## Before Editing
+
+- Inspect the current checkout. Do not assume a reported bug is still live.
+- Search with `rg` first.
+- Read the exact source path, tests, and helpers involved.
+- Trace from public configuration or input surface to the failing behavior.
+- Identify whether the problem belongs in a plugin, a shared helper, core
+  runtime, a bundled library, or tests.
+- If the fix would touch bundled library code under `lib/`, get explicit user
+  confirmation before editing. Use a confirmation popup when the environment
+  supports one; otherwise ask in chat.
+
+## Implementation Rules
+
+- Keep patches minimal and scoped.
+- Use existing helpers and source-of-truth functions before adding new logic.
+- When a shared helper has wrong semantics, fix the helper and update callers
+  consistently.
+- Preserve explicit zero values; use clear sentinels for unknown values.
+- Do not downgrade real I/O, parse, or lifecycle failures just to quiet logs.
+- Do not add broad refactors or formatting churn around the fix.
+- Keep bundled library edits isolated from Fluent Bit glue changes and write
+  them as upstreamable patches for the library's own project.
+- Follow Fluent Bit C style:
+  - variables at function start;
+  - braces for all `if`, `else`, `while`, and `do` blocks;
+  - function opening brace on the next line;
+  - `snake_case` names with existing component prefixes;
+  - `/* ... */` comments only where useful.
+
+## Review Stance
+
+Prioritize:
+
+- bugs and behavioral regressions;
+- missing tests;
+- lifecycle or memory-safety risks;
+- config compatibility risks;
+- route, signal, storage, or retry accounting regressions.
+
+When reviewing claims like "this enables validation" or "this caches
+resolution," distinguish:
+
+- what the current patch actually wires;
+- what runtime or binding plumbing is still missing;
+- whether behavior is one-shot lookup, repeated resolver use, or true cache
+  semantics.
+
+## Commit Guidance
+
+Use component-prefix subjects consistent with local history:
+
+```sh
+git commit -s -m "component: short imperative description"
+```
+
+Common examples:
+
+- `engine: fix flush buffer handling`
+- `tests: internal: add parser regression coverage`
+- `tests: integration: cover schema registry resolution`
+
+For bundled library changes, keep the library patch in its own commit unless the
+user explicitly asks otherwise. Use the prefix accepted for that path by the
+repository linter, and mention the upstream project/path in the commit body when
+that context is useful.
+
+Do not invent generic prefixes when the repository linter infers a narrower
+prefix. Run the linter when creating commits:
+
+```sh
+python .github/scripts/commit_prefix_check.py
+```
+
+If `gitpython` is missing:
+
+```sh
+python3 -m pip install gitpython
+```
+
+Before pushing or opening a PR, fetch the base branch and lint the PR range, not
+just `HEAD`. The checker can fall back to `HEAD`-only validation if the base ref
+is missing locally:
+
+```sh
+git fetch --all --prune
+git fetch origin <base-branch>:origin/<base-branch>
+GITHUB_EVENT_NAME=pull_request GITHUB_BASE_REF=<base-branch> \
+  python .github/scripts/commit_prefix_check.py
+```
+
+Do not open issues, pull requests, or remote branches unless explicitly asked.
+Do not rewrite history, amend commits, or force-push unless explicitly asked.