# AI Agent Working Guide

This file applies to the whole repository. Use it as the first stop before
editing OpenLiteSpeed so future agent sessions do not need to rediscover the
same workflow rules.

## Work Style

- Keep each change focused on one problem, feature, or cleanup.
- Do not mix unrelated refactors, formatting churn, dependency updates, and
  behavior changes in the same patch.
- Prefer small commits with a one-line summary and a clear body that records:
  the change, why it was needed, how it was implemented, what improved, and
  what problem it solved.
- Preserve existing user work. Check `git status --short` before editing and do
  not revert unowned changes.
- Follow the local style in the files being edited before introducing new
  structure or naming conventions.
- Keep performance characteristics in mind when changing code, especially hot
  paths such as parsing, lookup, request handling, response generation, and
  buffering. Preserve existing bounded or constant-time behavior unless a
  slower approach is measured and justified.
- Update nearby documentation when behavior, build steps, configuration, public
  APIs, or maintainer workflow changes.

## Project Memory

- Use `doc/AI_AGENT_PROJECT_MEMORY.md` to record durable project knowledge,
  design notes, progress, verification results, and handoff context.
- Read project memory before broad repository scans. Start with handoff notes,
  then project map/design notes, then the progress log.
- Add only useful, reusable knowledge. Avoid dumping raw command output unless a
  short excerpt is needed to explain a decision.
- When learning a stable fact about a subsystem, record where it came from and
  which files it affects.
- When finishing work or leaving partial work, add a handoff note if anything
  remains open, risky, or worth checking in the next session.
- When starting or landing a milestone, update the progress log.
- Keep memory updates separate from code changes unless the memory entry is
  directly about the code change being made.

## Existing Layout Notes

- `src/` contains the main server implementation and modules.
- `include/` contains public and shared headers, including `lsr/` C APIs.
- `test/` contains UnitTest++-style tests and server-root fixtures.
- `addon/` contains example modules.
- `support/` and `lshostexec/` are built from the top-level CMake project.
- `lsquic/` and `src/lshpack/` are bundled protocol/compression components.
- `doc/` currently holds project documentation and is the right place for
  maintainer-facing notes.

## Coding Style

- Respect `.editorconfig`: LF endings, final newline, four-space indentation for
  C, C++, shell, and PHP files.
- C and C++ source commonly use the existing OpenLiteSpeed GPL header, include
  project headers first, and keep braces on their own lines for functions and
  control blocks.
- Match surrounding naming style instead of normalizing a file to a different
  convention.
- For sequential string or array scans, prefer incremental pointer loops with a
  precomputed end pointer over index-based loops.
- Keep comments concise and use them to explain non-obvious behavior, protocol
  constraints, or ownership rules.

## Build And Test Notes

- The top-level CMake project is named `openlitespeed`.
- `CMAKE_BUILD_TYPE=Debug` on Linux enables `BUILD_TEST`, defines `RUN_TEST`,
  and adds the `test/` directory.
- Prefer targeted builds or tests for the subsystem being changed before running
  broader verification.
- Record exact commands and results in `doc/AI_AGENT_PROJECT_MEMORY.md` when
  they are useful for future sessions.

Useful starting commands:

```bash
git status --short
git log --oneline -8
cmake --build build -j2
```

## Change Checklist

1. Read the smallest set of files needed to understand the change.
2. Check existing call sites, ownership, error handling, and tests before
   editing.
3. Make the narrowest code change that solves the problem.
4. Add or update focused tests when behavior changes.
5. Run the most relevant verification available in the local environment.
6. Update docs or project memory if the change creates durable knowledge.
7. Review the diff for unrelated edits, formatting churn, and accidental file
   changes.

## Commit Message Pattern

Use a concise subject line, then a body when the change is non-trivial:

```text
area: short summary

What changed:
- ...

Why:
- ...

How:
- ...
```

## Updating AI Docs

Update `doc/AI_AGENT_PROJECT_MEMORY.md` when you discover durable facts,
complete a meaningful milestone, leave known follow-up work, or identify a
verification command that future agents should reuse.
