Add AI agent guidance, architecture docs, and project skills#7550
Open
The-E wants to merge 10 commits into
Open
Add AI agent guidance, architecture docs, and project skills#7550The-E wants to merge 10 commits into
The-E wants to merge 10 commits into
Conversation
The-E
force-pushed
the
feature/agent-guidance
branch
from
f6bbf9f to
bc3a6ca
Compare
The recent CI script typo fix (missing space in a bash test) means valgrind now actually runs on Debug Linux builds, surfacing a pre-existing one-time internal SDL2 allocation on SDL_Init that is attributed to whichever test fixture's SetUp happens to run first under --gtest_shuffle. This mirrors the existing gr_init suppression below it. Co-Authored-By: Claude Sonnet 5 <[email protected]>
Valgrind 3.18.1 (used by CI) cannot parse the DWARF5 debug info that clang-16 emits by default, causing the "unhandled dwarf2 abbrev form code" errors and a hard valgrind abort before memcheck can even run. Force -gdwarf-4 for Linux clang Debug builds (toolchain-clang.cmake is Linux-only; macOS uses toolchain-apple-clang.cmake and never runs valgrind) to keep the binary symbolizable. Co-Authored-By: Claude Sonnet 5 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch adds onboarding/guidance material for AI coding agents (and
humans) working in the FSO tree, plus two small CI fixes turned up while
writing that guidance.
Top-level & per-module agent guidance
AGENTS.md— vendor-agnostic entry-point guide for agents: projectoverview, core philosophies (backwards compatibility, optional/gated
gameplay changes, graceful hardware fallbacks), repo layout, build/test/style
conventions, CI pipeline requirements (what actually has to pass — fatal
warnings, the full compiler/platform matrix, valgrind on Linux Debug,
clang-tidy's real scope), and runtime logging guidance (
mprintfvsnprintf, per-frame logging pitfalls).CLAUDE.md— thin Claude Code entry point that importsAGENTS.mdvia@AGENTS.mdand indexes the Claude-specific skill stubs.AGENTS.mdstubs acrosscode/*(ai, cfile, cmdline,globalincs, graphics, hud, io, lab, localization, menuui, mission,
mod_table, model, network, object, options, parse, physics, scripting,
ship, sound, ui, weapon) plus
fred2/andqtfred/.Architecture & module documentation
documentation/ARCHITECTURE.md— high-level map of the engine'ssubsystems and where concepts live.
documentation/modules/*.md— per-module entry-point guides (~25 modules)so agents can navigate without blind grepping.
Vendor-agnostic project skills
.agents/skills/is the canonical, tool-agnostic source of truth for FSOworkflow skills:
fso-add-table-field,fso-add-sexp,fso-add-lua-api,fso-add-object-type,fso-add-hud-gauge,fso-build-and-test, andthermo-nuclear-code-quality-review(an opt-in, strictmaintainability/abstraction review, explicit invocation only), each
encoding the exact files to touch and how to verify.
.claude/skills/and.cursor/skills/contain thin pointer stubs to thecanonical
.agents/skills/<name>/SKILL.mdplaybooks, so the guidance isauthored once and shared across agent tools.
.agents/skills/README.mdindexes the available skills and authoringconventions.
CI fixes found while documenting the pipeline
ci/linux/run_tests.sh: fixed a missing space ([ "$CONFIGURATION" = "Debug"]) that made the valgrind-vs-plain-test check always evaluatefalse — valgrind's leak checking was silently never running on the Linux
Debug leg.
.github/workflows/test-pull_request.yaml: removed the macOS job's"Run Clang Tidy" / "Process clang-tidy warnings" steps. They were dead
code (the
if: startsWith(matrix.compiler, 'clang-')condition can nevermatch macOS's bare
clangcompiler name) and, separately,clang_tidy.shhardcodes a Linux-container-only binary path, so they couldn't have worked
as written. clang-tidy remains Linux-only, as documented in
AGENTS.md.Why
FSO is a large, legacy-heavy, cross-platform C++ codebase. These docs give
agents (and new contributors) a navigable map of subsystems, the project's
build/style/CI conventions, and repeatable, FSO-correct workflows for common
engine extensions — reducing blind exploration and convention mistakes.