diff --git a/.agents/skills/00-orchestration/fivem-audit/SKILL.md b/.agents/skills/00-orchestration/fivem-audit/SKILL.md index 51d4ac6..f1cfd0b 100644 --- a/.agents/skills/00-orchestration/fivem-audit/SKILL.md +++ b/.agents/skills/00-orchestration/fivem-audit/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-audit -description: Perform a comprehensive FiveM resource audit across architecture, security, networking, performance, persistence, UI, framework compatibility, lifecycle, testing, and release readiness. +description: 'Perform a comprehensive FiveM resource audit across architecture, security, networking, performance, persistence, UI, framework compatibility, lifecycle, testing, and release readiness.' --- # fivem-audit ## Purpose @@ -16,20 +16,11 @@ Review an existing resource systematically and prioritize findings by exploitabi 7. Audit resource restart, player disconnect, missing dependency, and partial-failure behavior. 8. Report findings as BLOCKER/HIGH/MEDIUM/LOW with file/line evidence, impact, and remediation. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not report style preferences as security findings. @@ -47,4 +38,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/00-orchestration/fivem-build/SKILL.md b/.agents/skills/00-orchestration/fivem-build/SKILL.md index f2e7b5f..6a8a2a3 100644 --- a/.agents/skills/00-orchestration/fivem-build/SKILL.md +++ b/.agents/skills/00-orchestration/fivem-build/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-build -description: Execute a production-minded BUILD workflow for a new FiveM feature or resource. Use when implementing new functionality end-to-end. +description: 'Execute a production-minded BUILD workflow for a new FiveM feature or resource. Use when implementing new functionality end-to-end.' --- # fivem-build ## Purpose @@ -15,20 +15,11 @@ Coordinate design, implementation, integration, and verification for a new featu 6. Run static checks, focused tests, restart/disconnect scenarios, security review, and performance checks. 7. Document configuration, dependencies, exports/events, and operational notes. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not build speculative abstractions without a current use case. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/00-orchestration/fivem-fix/SKILL.md b/.agents/skills/00-orchestration/fivem-fix/SKILL.md index 37b3069..aeb104d 100644 --- a/.agents/skills/00-orchestration/fivem-fix/SKILL.md +++ b/.agents/skills/00-orchestration/fivem-fix/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-fix -description: Run a root-cause-first FIX workflow for FiveM bugs. Use for errors, regressions, desync, NUI failures, event failures, entity issues, database problems, or performance regressions. +description: 'Run a root-cause-first FIX workflow for FiveM bugs. Use for errors, regressions, desync, NUI failures, event failures, entity issues, database problems, or performance regressions.' --- # fivem-fix ## Purpose @@ -15,20 +15,11 @@ Reproduce and isolate before patching. Prefer the smallest correction that fixes 6. Verify resource restart, player reconnect, and ownership/state transitions when relevant. 7. Run security/performance review if the failure path is externally triggerable or hot. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not apply random defensive guards without explaining the root cause. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/00-orchestration/fivem-project-inspector/SKILL.md b/.agents/skills/00-orchestration/fivem-project-inspector/SKILL.md index f1c9ed8..04e333f 100644 --- a/.agents/skills/00-orchestration/fivem-project-inspector/SKILL.md +++ b/.agents/skills/00-orchestration/fivem-project-inspector/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-project-inspector -description: Inspect an existing FiveM project before modification. Use to identify framework, dependencies, resource boundaries, events, exports, database access, NUI stack, conventions, and risk areas. +description: 'Inspect an existing FiveM project before modification. Use to identify framework, dependencies, resource boundaries, events, exports, database access, NUI stack, conventions, and risk areas.' --- # fivem-project-inspector ## Purpose @@ -15,20 +15,11 @@ Build a factual project map before changing code. Prefer repository evidence ove 6. Record existing naming, error, logging, config, localization, and test conventions. 7. Produce a concise change-impact map: files to touch, contracts affected, migrations, restart risks, and verification commands. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Deterministic helper @@ -50,4 +41,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/00-orchestration/fivem-project-inspector/scripts/scan_project.py b/.agents/skills/00-orchestration/fivem-project-inspector/scripts/scan_project.py index 815be31..86dfe0c 100755 --- a/.agents/skills/00-orchestration/fivem-project-inspector/scripts/scan_project.py +++ b/.agents/skills/00-orchestration/fivem-project-inspector/scripts/scan_project.py @@ -1,34 +1,72 @@ #!/usr/bin/env python3 +""" +Scans an existing FiveM project for structural signals, dependencies, and architecture. +""" +import argparse +import re +import json from pathlib import Path -import re, json, argparse -p=argparse.ArgumentParser(); p.add_argument('root', nargs='?', default='.'); a=p.parse_args() -root=Path(a.root).resolve() -files=[x for x in root.rglob('*') if x.is_file() and '.git' not in x.parts and 'node_modules' not in x.parts] -manifest=[str(x.relative_to(root)) for x in files if x.name=='fxmanifest.lua'] -lua=[x for x in files if x.suffix=='.lua'] -texts={} -for f in lua: - try: texts[f]=f.read_text(encoding='utf-8',errors='ignore') - except: pass -patterns={ - 'net_events': r"RegisterNetEvent\s*\(\s*['\"]([^'\"]+)", - 'server_triggers': r"TriggerServerEvent\s*\(\s*['\"]([^'\"]+)", - 'client_triggers': r"TriggerClientEvent\s*\(\s*['\"]([^'\"]+)", - 'exports': r"exports(?:\s*\[?\s*['\"]?[^\n]*|\s*\()", - 'nui_callbacks': r"RegisterNuiCallback|RegisterNUICallback", - 'nui_messages': r"SendNUIMessage\s*\(", - 'statebags': r"(?:Entity|Player)\s*\([^\)]*\)\.state|GlobalState", - 'wait0': r"Wait\s*\(\s*0\s*\)|Citizen\.Wait\s*\(\s*0\s*\)", -} -report={'root':str(root),'manifests':manifest,'lua_files':len(lua),'signals':{}} -for k,pat in patterns.items(): - hits=[] - rx=re.compile(pat) - for f,t in texts.items(): - ms=rx.findall(t) - if ms: hits.append({'file':str(f.relative_to(root)),'count':len(ms),'examples':ms[:10] if isinstance(ms[0] if ms else '',str) else []}) - report['signals'][k]=hits -# dependency hints -alltext='\n'.join(texts.values()).lower() -report['framework_hints']={k:(k in alltext) for k in ['qbx_core','qb-core','es_extended','ox_lib','oxmysql','ox_target','ox_inventory']} -print(json.dumps(report, indent=2)) + +def main(): + parser = argparse.ArgumentParser(description="Inspect FiveM project architecture") + parser.add_argument("root", nargs="?", default=".", help="Project root directory") + args = parser.parse_args() + + root = Path(args.root).resolve() + + files = [x for x in root.rglob("*") if x.is_file() and ".git" not in x.parts and "node_modules" not in x.parts] + manifests = [str(x.relative_to(root)) for x in files if x.name in ("fxmanifest.lua", "__resource.lua")] + lua_files = [x for x in files if x.suffix == ".lua"] + + texts = {} + for f in lua_files: + try: + texts[f] = f.read_text(encoding="utf-8", errors="ignore") + except: + pass + + patterns = { + "net_events": r"RegisterNetEvent\s*\(\s*['\"]([^'\"]+)", + "server_triggers": r"TriggerServerEvent\s*\(\s*['\"]([^'\"]+)", + "client_triggers": r"TriggerClientEvent\s*\(\s*['\"]([^'\"]+)", + "exports": r"exports(?:\s*\[?\s*['\"]?[^\n]*|\s*\()", + "nui_callbacks": r"Register(?:Nui|NUI)Callback", + "nui_messages": r"SendNUIMessage\s*\(", + "statebags": r"(?:Entity|Player)\s*\([^\)]*\)\.state|GlobalState", + "wait0": r"(?:Citizen\.)?Wait\s*\(\s*0\s*\)", + } + + report = { + "root": str(root), + "manifests": manifests, + "lua_files_count": len(lua_files), + "signals": {} + } + + for key, pat in patterns.items(): + hits = [] + rx = re.compile(pat) + for f, t in texts.items(): + matches = rx.findall(t) + if matches: + # Some regexes capture groups, some don't. + examples = matches[:5] if matches and isinstance(matches[0], str) else [] + hits.append({ + "file": str(f.relative_to(root)), + "count": len(matches), + "examples": examples + }) + report["signals"][key] = hits + + # Dependency / framework heuristics + all_text = "\n".join(texts.values()).lower() + frameworks = ["qbx_core", "qb-core", "es_extended", "ox_lib", "oxmysql", "ox_target", "ox_inventory"] + + report["framework_hints"] = { + fw: (fw in all_text) for fw in frameworks + } + + print(json.dumps(report, indent=2)) + +if __name__ == "__main__": + main() diff --git a/.agents/skills/00-orchestration/fivem-router/SKILL.md b/.agents/skills/00-orchestration/fivem-router/SKILL.md index 740acc2..92a2864 100644 --- a/.agents/skills/00-orchestration/fivem-router/SKILL.md +++ b/.agents/skills/00-orchestration/fivem-router/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-router -description: Route FiveM development tasks to the minimum relevant specialist skills. Use for any FiveM resource work, feature, bug, audit, UI, networking, framework, database, gameplay, security, or performance task. +description: 'Route FiveM development tasks to the minimum relevant specialist skills. Use for any FiveM resource work, feature, bug, audit, UI, networking, framework, database, gameplay, security, or performance task.' --- # fivem-router ## Purpose @@ -14,20 +14,11 @@ Act as the orchestration layer. Inspect the task and repository context, select 5. For code changes, finish with security/performance/testing/code-review when materially relevant. 6. State assumptions only when they affect implementation; otherwise inspect instead of asking. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not activate every skill by default. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/routing-matrix.md` in this skill for signal-to-skill mapping. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/00-orchestration/fivem-router/references/routing-matrix.md b/.agents/skills/00-orchestration/fivem-router/references/routing-matrix.md new file mode 100644 index 0000000..ddc50cc --- /dev/null +++ b/.agents/skills/00-orchestration/fivem-router/references/routing-matrix.md @@ -0,0 +1,27 @@ +# Routing Matrix + +Use this as a secondary router reference, not as an instruction to load everything. + +| Signal | Primary skills | Often pair with | +|---|---|---| +| `fxmanifest.lua`, dependencies, new resource | fivem-resource-architecture | fivem-compatibility, fivem-release | +| `.lua`, threads, vectors | fivem-cfxlua | fivem-native-expert, fivem-performance | +| native/hash/task/entity call | fivem-native-expert | gameplay specialist, fivem-onesync | +| `TriggerServerEvent`, `RegisterNetEvent` | fivem-events, fivem-server-authority | fivem-security | +| network entity/NetID | fivem-onesync, fivem-entity-lifecycle | fivem-statebags | +| `Entity(...).state`, `GlobalState` | fivem-statebags | fivem-onesync | +| routing bucket/instance | fivem-routing-buckets | fivem-security, fivem-entity-lifecycle | +| NUI / `ui_page` | fivem-nui | fivem-nui-bridge, fivem-ui-design | +| React/Vue/Svelte/Tailwind UI | fivem-frontend-stack, fivem-ui-design | fivem-nui-bridge, fivem-performance | +| DUI/runtime texture | fivem-dui | fivem-entity-lifecycle, fivem-performance | +| SQL/oxmysql | fivem-database | framework skill, fivem-security | +| Qbox/QBCore/ESX | matching framework skill | fivem-framework-adapter | +| ox_lib/target/inventory | fivem-ox-ecosystem | fivem-interactions, fivem-database | +| vehicles | fivem-vehicles | fivem-onesync, fivem-entity-lifecycle | +| convoy/autodrive | fivem-vehicle-ai | fivem-native-expert, fivem-onesync | +| NPCs | fivem-peds-ai | fivem-native-expert, fivem-entity-lifecycle | +| target/zones | fivem-interactions | fivem-zones-raycasts, fivem-security | +| exploit/cheat concern | fivem-security | fivem-server-authority, fivem-events | +| high resmon / lag | fivem-performance | fivem-observability, relevant domain skill | +| error/regression | fivem-fix, fivem-debugging | fivem-testing | +| release-ready review | fivem-audit, fivem-code-review | fivem-testing, fivem-release | diff --git a/.agents/skills/01-core/fivem-cfxlua/SKILL.md b/.agents/skills/01-core/fivem-cfxlua/SKILL.md index 18f323b..de8d266 100644 --- a/.agents/skills/01-core/fivem-cfxlua/SKILL.md +++ b/.agents/skills/01-core/fivem-cfxlua/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-cfxlua -description: Write and review modern CfxLua for FiveM using Lua 5.4 semantics, Cfx extensions, coroutine/thread patterns, efficient tables, vectors, errors, and hot-path discipline. +description: 'Write and review modern CfxLua for FiveM using Lua 5.4 semantics, Cfx extensions, coroutine/thread patterns, efficient tables, vectors, errors, and hot-path discipline.' --- # fivem-cfxlua ## Purpose @@ -15,20 +15,11 @@ Produce idiomatic, allocation-conscious Lua that fits FiveM runtime semantics ra 6. Handle nil/deleted entities and resource shutdown explicitly. 7. For CPU-heavy pure logic, isolate functions so they can be unit tested outside GTA runtime. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not add Lua 5.3 compatibility workarounds without evidence. @@ -47,4 +38,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/cfxlua-sources.md` in this skill for CfxLua and manifest documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/01-core/fivem-cfxlua/references/cfxlua-sources.md b/.agents/skills/01-core/fivem-cfxlua/references/cfxlua-sources.md new file mode 100644 index 0000000..46e5e7a --- /dev/null +++ b/.agents/skills/01-core/fivem-cfxlua/references/cfxlua-sources.md @@ -0,0 +1,8 @@ +# CfxLua & Resource Manifest Sources + +Checked: 2026-08-30. + +- CfxLua runtime: https://docs.fivem.net/docs/scripting-manual/runtimes/lua/ +- Resource manifest: https://docs.fivem.net/docs/scripting-reference/resource-manifest/ +- Developer docs: https://docs.fivem.net/docs/developers/ +- Native reference: https://docs.fivem.net/natives/ diff --git a/.agents/skills/01-core/fivem-client-gameplay/SKILL.md b/.agents/skills/01-core/fivem-client-gameplay/SKILL.md index 36b8c0b..d4f043f 100644 --- a/.agents/skills/01-core/fivem-client-gameplay/SKILL.md +++ b/.agents/skills/01-core/fivem-client-gameplay/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-client-gameplay -description: Implement FiveM client gameplay systems: player/ped/vehicle interaction, cameras, animations, props, blips, markers, particles, audio, controls, and local presentation logic. +description: 'Implement FiveM client gameplay systems: player/ped/vehicle interaction, cameras, animations, props, blips, markers, particles, audio, controls, and local presentation logic.' --- # fivem-client-gameplay ## Purpose @@ -15,20 +15,11 @@ Keep the client responsive and presentation-focused while delegating trusted sta 6. Batch or throttle UI updates generated from gameplay state. 7. Send requests to server with minimal evidence; let server revalidate critical facts. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not grant money/items/permissions client-side. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/01-core/fivem-events/SKILL.md b/.agents/skills/01-core/fivem-events/SKILL.md index f8226b4..c0008e9 100644 --- a/.agents/skills/01-core/fivem-events/SKILL.md +++ b/.agents/skills/01-core/fivem-events/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-events -description: Design and review FiveM local/network event contracts, handlers, callbacks, exports, cancellation, payload validation, naming, rate limits, and versioning. +description: 'Design and review FiveM local/network event contracts, handlers, callbacks, exports, cancellation, payload validation, naming, rate limits, and versioning.' --- # fivem-events ## Purpose @@ -15,20 +15,11 @@ Make event-driven systems explicit, secure, traceable, and cheap enough for thei 6. Add rate limiting/debouncing for abuse-prone or high-frequency calls. 7. Remove dynamically registered handlers when lifecycle requires it. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not use `RegisterNetEvent` where a local event/export suffices. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/01-core/fivem-native-expert/SKILL.md b/.agents/skills/01-core/fivem-native-expert/SKILL.md index 81a9511..606c450 100644 --- a/.agents/skills/01-core/fivem-native-expert/SKILL.md +++ b/.agents/skills/01-core/fivem-native-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-native-expert -description: Select, verify, and use FiveM/GTA natives correctly, including client/server context, hashes, parameters, return values, entity validity, network implications, and safer alternatives. +description: 'Select, verify, and use FiveM/GTA natives correctly, including client/server context, hashes, parameters, return values, entity validity, network implications, and safer alternatives.' --- # fivem-native-expert ## Purpose @@ -15,20 +15,11 @@ Prevent hallucinated or context-invalid native usage and choose the narrowest co 6. Prefer server setters or server authority when state must be trusted/replicated. 7. Document unusual flag bitmasks/driving styles with meaning, not magic numbers. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Never invent a native name or signature. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/01-core/fivem-resource-architecture/SKILL.md b/.agents/skills/01-core/fivem-resource-architecture/SKILL.md index 8d90a5a..4e41f01 100644 --- a/.agents/skills/01-core/fivem-resource-architecture/SKILL.md +++ b/.agents/skills/01-core/fivem-resource-architecture/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-resource-architecture -description: Design and review FiveM resource architecture, fxmanifest metadata, module boundaries, exports, dependencies, lifecycle, configuration, and multi-resource composition. +description: 'Design and review FiveM resource architecture, fxmanifest metadata, module boundaries, exports, dependencies, lifecycle, configuration, and multi-resource composition.' --- # fivem-resource-architecture ## Purpose @@ -16,20 +16,11 @@ Create cohesive resources with explicit public contracts and minimal coupling. 7. Avoid circular dependencies; introduce a small interface/adapter boundary instead. 8. Version public contracts when external resources consume them. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not use `lua54 'yes'`. @@ -47,4 +38,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/cfxlua-sources.md` in this skill for resource manifest documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/01-core/fivem-resource-architecture/references/cfxlua-sources.md b/.agents/skills/01-core/fivem-resource-architecture/references/cfxlua-sources.md new file mode 100644 index 0000000..46e5e7a --- /dev/null +++ b/.agents/skills/01-core/fivem-resource-architecture/references/cfxlua-sources.md @@ -0,0 +1,8 @@ +# CfxLua & Resource Manifest Sources + +Checked: 2026-08-30. + +- CfxLua runtime: https://docs.fivem.net/docs/scripting-manual/runtimes/lua/ +- Resource manifest: https://docs.fivem.net/docs/scripting-reference/resource-manifest/ +- Developer docs: https://docs.fivem.net/docs/developers/ +- Native reference: https://docs.fivem.net/natives/ diff --git a/.agents/skills/01-core/fivem-server-authority/SKILL.md b/.agents/skills/01-core/fivem-server-authority/SKILL.md index 62632f9..5766952 100644 --- a/.agents/skills/01-core/fivem-server-authority/SKILL.md +++ b/.agents/skills/01-core/fivem-server-authority/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-server-authority -description: Design secure server-authoritative FiveM logic for permissions, economy, inventory, ownership, proximity, cooldowns, state mutation, spawning, and validation. +description: 'Design secure server-authoritative FiveM logic for permissions, economy, inventory, ownership, proximity, cooldowns, state mutation, spawning, and validation.' --- # fivem-server-authority ## Purpose @@ -15,20 +15,11 @@ Treat clients as untrusted requesters and make the server the source of truth fo 6. Return explicit success/error results instead of silent mutation. 7. Log security-relevant denials without leaking secrets. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Never trust client money, inventory, job, permission, reward, price, or ownership claims. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/02-networking/fivem-entity-lifecycle/SKILL.md b/.agents/skills/02-networking/fivem-entity-lifecycle/SKILL.md index 2ea7c05..0437ad0 100644 --- a/.agents/skills/02-networking/fivem-entity-lifecycle/SKILL.md +++ b/.agents/skills/02-networking/fivem-entity-lifecycle/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-entity-lifecycle -description: Manage FiveM entity lifecycle reliably across model loading, creation, networking, ownership, persistence, migration, deletion, resource stop, and player disconnect. +description: 'Manage FiveM entity lifecycle reliably across model loading, creation, networking, ownership, persistence, migration, deletion, resource stop, and player disconnect.' --- # fivem-entity-lifecycle ## Purpose @@ -15,20 +15,11 @@ Prevent leaked, orphaned, duplicated, or stale entities and NetIDs. 6. Clean entities on cancellation, resource stop, session teardown, and invalid owner cases as designed. 7. Make cleanup idempotent so repeated calls are safe. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not assume DeleteEntity always succeeds immediately across network ownership boundaries. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/02-networking/fivem-onesync/SKILL.md b/.agents/skills/02-networking/fivem-onesync/SKILL.md index 77dd9b7..9d01c81 100644 --- a/.agents/skills/02-networking/fivem-onesync/SKILL.md +++ b/.agents/skills/02-networking/fivem-onesync/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-onesync -description: Design OneSync-aware FiveM networking: server-created entities, network IDs, ownership migration, culling, routing buckets, population, synchronization, and large-player behavior. +description: 'Design OneSync-aware FiveM networking: server-created entities, network IDs, ownership migration, culling, routing buckets, population, synchronization, and large-player behavior.' --- # fivem-onesync ## Purpose @@ -15,20 +15,11 @@ Build networked systems that remain correct as players enter/leave scope and ent 6. Choose entity lockdown mode intentionally for buckets when clients should not create entities. 7. Test with at least two clients and ownership migration for networked gameplay. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not assume all clients stream every entity. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/onesync-sources.md` in this skill for OneSync and state bag documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/02-networking/fivem-onesync/references/onesync-sources.md b/.agents/skills/02-networking/fivem-onesync/references/onesync-sources.md new file mode 100644 index 0000000..46471ef --- /dev/null +++ b/.agents/skills/02-networking/fivem-onesync/references/onesync-sources.md @@ -0,0 +1,7 @@ +# OneSync & State Bag Sources + +Checked: 2026-08-30. + +- OneSync: https://docs.fivem.net/docs/scripting-reference/onesync/ +- State bags: https://docs.fivem.net/docs/scripting-manual/networking/state-bags/ +- Native reference: https://docs.fivem.net/natives/ diff --git a/.agents/skills/02-networking/fivem-routing-buckets/SKILL.md b/.agents/skills/02-networking/fivem-routing-buckets/SKILL.md index 6fd1e0b..116b053 100644 --- a/.agents/skills/02-networking/fivem-routing-buckets/SKILL.md +++ b/.agents/skills/02-networking/fivem-routing-buckets/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-routing-buckets -description: Design and review routing bucket usage, population settings, entity lockdown modes, player/entity assignment, and instance teardown in OneSync. +description: 'Design and review routing bucket usage, population settings, entity lockdown modes, player/entity assignment, and instance teardown in OneSync.' --- # fivem-routing-buckets ## Purpose @@ -15,20 +15,11 @@ Use buckets as deliberate isolation domains with safe entry/exit and teardown. 6. Delete or migrate bucket-owned entities during teardown. 7. Prevent cross-instance data/event leakage at application level. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not assume buckets provide authorization by themselves. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/02-networking/fivem-statebags/SKILL.md b/.agents/skills/02-networking/fivem-statebags/SKILL.md index f653be1..a8dbcdc 100644 --- a/.agents/skills/02-networking/fivem-statebags/SKILL.md +++ b/.agents/skills/02-networking/fivem-statebags/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-statebags -description: Use FiveM state bags efficiently and safely for replicated entity/player/global attributes, including ownership, replication direction, change handlers, namespacing, and serialization cost. +description: 'Use FiveM state bags efficiently and safely for replicated entity/player/global attributes, including ownership, replication direction, change handlers, namespacing, and serialization cost.' --- # fivem-statebags ## Purpose @@ -15,20 +15,11 @@ Represent small replicated facts, not arbitrary application databases, in state 6. Avoid high-frequency state bag churn for telemetry that can be local or batched. 7. Treat replicated state as observable, not secret. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not store secrets in state bags. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/onesync-sources.md` in this skill for state bag documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/02-networking/fivem-statebags/references/onesync-sources.md b/.agents/skills/02-networking/fivem-statebags/references/onesync-sources.md new file mode 100644 index 0000000..46471ef --- /dev/null +++ b/.agents/skills/02-networking/fivem-statebags/references/onesync-sources.md @@ -0,0 +1,7 @@ +# OneSync & State Bag Sources + +Checked: 2026-08-30. + +- OneSync: https://docs.fivem.net/docs/scripting-reference/onesync/ +- State bags: https://docs.fivem.net/docs/scripting-manual/networking/state-bags/ +- Native reference: https://docs.fivem.net/natives/ diff --git a/.agents/skills/03-ui/fivem-dui/SKILL.md b/.agents/skills/03-ui/fivem-dui/SKILL.md index 090d5d9..71a2d14 100644 --- a/.agents/skills/03-ui/fivem-dui/SKILL.md +++ b/.agents/skills/03-ui/fivem-dui/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-dui -description: Implement and review Direct-rendered UI (DUI) for in-world screens, terminals, vehicle displays, signs, TVs, and runtime textures. +description: 'Implement and review Direct-rendered UI (DUI) for in-world screens, terminals, vehicle displays, signs, TVs, and runtime textures.' --- # fivem-dui ## Purpose @@ -15,20 +15,11 @@ Use DUI when an interface must exist on a world surface, while managing browser/ 6. Destroy DUI/runtime resources on teardown and resource stop. 7. Handle missing texture/model targets without leaking browser instances. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not create one expensive DUI browser per entity without capacity analysis. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/03-ui/fivem-frontend-stack/SKILL.md b/.agents/skills/03-ui/fivem-frontend-stack/SKILL.md index f6a2d67..da37432 100644 --- a/.agents/skills/03-ui/fivem-frontend-stack/SKILL.md +++ b/.agents/skills/03-ui/fivem-frontend-stack/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-frontend-stack -description: Engineer modern FiveM NUI frontends with TypeScript and an appropriate framework/build tool while controlling bundle size, render frequency, state, accessibility, and CEF compatibility. +description: 'Engineer modern FiveM NUI frontends with TypeScript and an appropriate framework/build tool while controlling bundle size, render frequency, state, accessibility, and CEF compatibility.' --- # fivem-frontend-stack ## Purpose @@ -15,20 +15,11 @@ Choose React/Vue/Svelte/vanilla based on UI complexity, not habit, and ship a co 6. Use transform/opacity animations where possible. 7. Build to a deterministic directory declared by the resource manifest. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not add a full framework for a tiny static HUD without reason. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/03-ui/fivem-nui-bridge/SKILL.md b/.agents/skills/03-ui/fivem-nui-bridge/SKILL.md index 9421164..fc8d94c 100644 --- a/.agents/skills/03-ui/fivem-nui-bridge/SKILL.md +++ b/.agents/skills/03-ui/fivem-nui-bridge/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-nui-bridge -description: Design typed, validated communication contracts between FiveM Lua and NUI frontends, including request/response envelopes, errors, timeouts, message routing, and rate limits. +description: 'Design typed, validated communication contracts between FiveM Lua and NUI frontends, including request/response envelopes, errors, timeouts, message routing, and rate limits.' --- # fivem-nui-bridge ## Purpose @@ -15,20 +15,11 @@ Make the Lua↔browser boundary explicit and mechanically consistent rather than 6. Throttle high-frequency game→UI telemetry; send deltas when practical. 7. Document which NUI action may trigger a server request and the server validation required. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Deterministic helper @@ -50,4 +41,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/nui-contract-pattern.md` in this skill for the canonical contract envelope. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/03-ui/fivem-nui-bridge/references/nui-contract-pattern.md b/.agents/skills/03-ui/fivem-nui-bridge/references/nui-contract-pattern.md new file mode 100644 index 0000000..ab52ae1 --- /dev/null +++ b/.agents/skills/03-ui/fivem-nui-bridge/references/nui-contract-pattern.md @@ -0,0 +1,21 @@ +# NUI Contract Pattern + +Recommended envelope: + +```ts +export type NuiResult = + | { ok: true; data: T } + | { ok: false; error: { code: string; message: string } }; +``` + +Browser request helper should: +1. Resolve `GetParentResourceName()` in FiveM; allow a dev fallback only in development. +2. POST JSON to `https://${resource}/${callback}`. +3. Apply timeout/abort handling. +4. Parse a stable result envelope. + +Lua callback should: +1. Runtime-validate the payload. +2. Perform local presentation work or forward the minimal request to the server. +3. Call `cb(...)` exactly once on every path. +4. Never treat UI visibility/disabled controls as authorization. diff --git a/.agents/skills/03-ui/fivem-nui-bridge/scripts/scan_nui.py b/.agents/skills/03-ui/fivem-nui-bridge/scripts/scan_nui.py index 09dfc65..0dc21f9 100755 --- a/.agents/skills/03-ui/fivem-nui-bridge/scripts/scan_nui.py +++ b/.agents/skills/03-ui/fivem-nui-bridge/scripts/scan_nui.py @@ -1,13 +1,61 @@ #!/usr/bin/env python3 +""" +Scans a FiveM project for NUI related communications and definitions. +""" +import argparse +import re +import json from pathlib import Path -import re, argparse -p=argparse.ArgumentParser(); p.add_argument('root', nargs='?', default='.'); a=p.parse_args(); root=Path(a.root).resolve() -for f in root.rglob('*'): - if not f.is_file() or '.git' in f.parts or 'node_modules' in f.parts: continue - if f.suffix.lower() not in {'.lua','.ts','.tsx','.js','.jsx'}: continue - text=f.read_text(encoding='utf-8',errors='ignore') - for rx,kind in [(r"Register(?:Nui|NUI)Callback\s*\(\s*['\"]([^'\"]+)",'lua-callback'),(r"fetch\s*\(\s*`?['\"]?https://\$\{[^}]+\}/([^`'\"$]+)",'ui-fetch'),(r"SendNUIMessage\s*\(",'nui-message')]: - for m in re.finditer(rx,text): - line=text.count('\n',0,m.start())+1 - val=m.group(1) if m.groups() else '' - print(f'{kind}\t{f.relative_to(root)}:{line}\t{val}') + +def main(): + parser = argparse.ArgumentParser(description="Scan FiveM project for NUI interfaces") + parser.add_argument("root", nargs="?", default=".", help="Project root directory") + parser.add_argument("--format", choices=["json", "text"], default="text", help="Output format") + args = parser.parse_args() + + root = Path(args.root).resolve() + + checks = { + "lua_nui_callbacks": re.compile(r"Register(?:Nui|NUI)Callback\s*\(\s*['\"]([^'\"]+)"), + "lua_nui_messages": re.compile(r"SendNUIMessage\s*\("), + "frontend_fetches": re.compile(r"fetch\s*\(\s*`?['\"]?https://\$\{[^}]+\}/([^`'\"$]+)"), + "frontend_postmessages": re.compile(r"window\.postMessage\s*\(") + } + + results = {key: [] for key in checks} + allowed_extensions = {".lua", ".ts", ".tsx", ".js", ".jsx"} + + for file_path in root.rglob("*"): + if not file_path.is_file(): continue + if ".git" in file_path.parts or "node_modules" in file_path.parts: continue + if file_path.suffix.lower() not in allowed_extensions: continue + + try: + text = file_path.read_text(encoding="utf-8", errors="ignore") + lines = text.splitlines() + + for line_idx, line in enumerate(lines, 1): + for kind, pattern in checks.items(): + match = pattern.search(line) + if match: + value = match.group(1) if match.groups() else "(anonymous/dynamic)" + results[kind].append({ + "file": str(file_path.relative_to(root)), + "line": line_idx, + "value": value, + "snippet": line.strip()[:100] + }) + except Exception: + pass + + if args.format == "json": + print(json.dumps(results, indent=2)) + else: + for kind, findings in results.items(): + print(f"=== {kind.replace('_', ' ').title()} ({len(findings)}) ===") + for f in findings: + print(f" {f['file']}:{f['line']} -> {f['value']}") + print() + +if __name__ == "__main__": + main() diff --git a/.agents/skills/03-ui/fivem-nui/SKILL.md b/.agents/skills/03-ui/fivem-nui/SKILL.md index 1d0e903..3caa716 100644 --- a/.agents/skills/03-ui/fivem-nui/SKILL.md +++ b/.agents/skills/03-ui/fivem-nui/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-nui -description: Build and review FiveM fullscreen NUI using CEF, `ui_page`, resource files, focus, messages, callbacks, development tooling, responsive layout, and safe teardown. +description: 'Build and review FiveM fullscreen NUI using CEF, `ui_page`, resource files, focus, messages, callbacks, development tooling, responsive layout, and safe teardown.' --- # fivem-nui ## Purpose @@ -15,20 +15,11 @@ Create game-native interfaces that load reliably, release focus correctly, and c 6. Keep the UI functional at common FiveM resolutions/aspect ratios. 7. Use NUI devtools for console/network/performance diagnosis. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not put trusted secrets or authority in browser code. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/nui-sources.md` in this skill for NUI/CEF documentation links. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/03-ui/fivem-nui/references/nui-sources.md b/.agents/skills/03-ui/fivem-nui/references/nui-sources.md new file mode 100644 index 0000000..f3acb1c --- /dev/null +++ b/.agents/skills/03-ui/fivem-nui/references/nui-sources.md @@ -0,0 +1,7 @@ +# NUI Sources + +Checked: 2026-08-30. + +- Fullscreen NUI: https://docs.fivem.net/docs/scripting-manual/nui-development/full-screen-nui/ +- NUI callbacks: https://docs.fivem.net/docs/scripting-manual/nui-development/nui-callbacks/ +- SendNUIMessage: https://docs.fivem.net/docs/scripting-reference/runtimes/lua/functions/SendNUIMessage/ diff --git a/.agents/skills/03-ui/fivem-ui-design/SKILL.md b/.agents/skills/03-ui/fivem-ui-design/SKILL.md index 284d104..2452b95 100644 --- a/.agents/skills/03-ui/fivem-ui-design/SKILL.md +++ b/.agents/skills/03-ui/fivem-ui-design/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-ui-design -description: Design premium, game-first FiveM UI/UX for HUDs, menus, MDTs, phones, inventories, garages, dispatch, vehicle controls, admin tools, and custom interfaces. +description: 'Design premium, game-first FiveM UI/UX for HUDs, menus, MDTs, phones, inventories, garages, dispatch, vehicle controls, admin tools, and custom interfaces.' --- # fivem-ui-design ## Purpose @@ -15,20 +15,11 @@ Create polished interfaces that feel native to the game, preserve gameplay visib 6. Plan loading/empty/error/disabled/permission states. 7. Respect 16:9, ultrawide, high-DPI, safe edges, and scalable text. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not imitate copyrighted branded UI pixel-for-pixel unless authorized. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-database/SKILL.md b/.agents/skills/04-data-frameworks/fivem-database/SKILL.md index b5e070c..e4dac2c 100644 --- a/.agents/skills/04-data-frameworks/fivem-database/SKILL.md +++ b/.agents/skills/04-data-frameworks/fivem-database/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-database -description: Design FiveM persistence with oxmysql or project-specific database libraries: queries, prepared parameters, repositories, transactions, indexes, migrations, caching, and failure handling. +description: 'Design FiveM persistence with oxmysql or project-specific database libraries: queries, prepared parameters, repositories, transactions, indexes, migrations, caching, and failure handling.' --- # fivem-database ## Purpose @@ -16,20 +16,11 @@ Keep persistence server-only, safe, efficient, and isolated behind a small data- 7. Make migrations reversible or safely forward-only with documented backup implications. 8. Define cache invalidation and stale-data tolerance when caching. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not access SQL from client/NUI. @@ -47,4 +38,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/framework-sources.md` in this skill for oxmysql documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-database/references/framework-sources.md b/.agents/skills/04-data-frameworks/fivem-database/references/framework-sources.md new file mode 100644 index 0000000..cd43722 --- /dev/null +++ b/.agents/skills/04-data-frameworks/fivem-database/references/framework-sources.md @@ -0,0 +1,11 @@ +# Framework Sources + +Checked: 2026-08-30. + +- Qbox docs: https://docs.qbox.re/ +- QBCore docs: https://docs.qbcore.org/ +- ESX docs: https://docs.esx-framework.org/ +- ox_lib: https://overextended.dev/ox_lib +- oxmysql: https://overextended.dev/oxmysql +- ox_target: https://overextended.dev/ox_target +- ox_inventory: https://overextended.dev/ox_inventory diff --git a/.agents/skills/04-data-frameworks/fivem-esx/SKILL.md b/.agents/skills/04-data-frameworks/fivem-esx/SKILL.md index 6968a8f..834c9d1 100644 --- a/.agents/skills/04-data-frameworks/fivem-esx/SKILL.md +++ b/.agents/skills/04-data-frameworks/fivem-esx/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-esx -description: Implement ESX integrations for xPlayer, jobs, accounts, inventory, callbacks, vehicles, permissions, notifications, and lifecycle using the installed ESX version. +description: 'Implement ESX integrations for xPlayer, jobs, accounts, inventory, callbacks, vehicles, permissions, notifications, and lifecycle using the installed ESX version.' --- # fivem-esx ## Purpose @@ -14,20 +14,11 @@ Use current ESX APIs through a contained adapter while accounting for difference 5. Avoid retaining stale xPlayer objects across disconnect/reload. 6. Document fork-specific behavior. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not assume Legacy/fork APIs are identical. @@ -45,4 +36,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/framework-sources.md` in this skill for ESX documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-esx/references/framework-sources.md b/.agents/skills/04-data-frameworks/fivem-esx/references/framework-sources.md new file mode 100644 index 0000000..cd43722 --- /dev/null +++ b/.agents/skills/04-data-frameworks/fivem-esx/references/framework-sources.md @@ -0,0 +1,11 @@ +# Framework Sources + +Checked: 2026-08-30. + +- Qbox docs: https://docs.qbox.re/ +- QBCore docs: https://docs.qbcore.org/ +- ESX docs: https://docs.esx-framework.org/ +- ox_lib: https://overextended.dev/ox_lib +- oxmysql: https://overextended.dev/oxmysql +- ox_target: https://overextended.dev/ox_target +- ox_inventory: https://overextended.dev/ox_inventory diff --git a/.agents/skills/04-data-frameworks/fivem-framework-adapter/SKILL.md b/.agents/skills/04-data-frameworks/fivem-framework-adapter/SKILL.md index 4264eb2..c4dee83 100644 --- a/.agents/skills/04-data-frameworks/fivem-framework-adapter/SKILL.md +++ b/.agents/skills/04-data-frameworks/fivem-framework-adapter/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-framework-adapter -description: Keep FiveM resources portable across standalone, Qbox, QBCore, ESX, or custom frameworks using narrow adapter interfaces and capability detection. +description: 'Keep FiveM resources portable across standalone, Qbox, QBCore, ESX, or custom frameworks using narrow adapter interfaces and capability detection.' --- # fivem-framework-adapter ## Purpose @@ -15,20 +15,11 @@ Separate domain/gameplay logic from framework-specific player, job, money, item, 6. Prefer optional integrations over hard dependencies when feasible. 7. Test the core with a fake/standalone adapter. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not branch `if ESX ... elseif QBCore ...` throughout domain code. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/SKILL.md b/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/SKILL.md index 60cf49d..e02dc18 100644 --- a/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/SKILL.md +++ b/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-ox-ecosystem -description: Integrate ox_lib, ox_target, ox_inventory, and oxmysql deliberately in FiveM resources, using current APIs and avoiding unnecessary lock-in. +description: 'Integrate ox_lib, ox_target, ox_inventory, and oxmysql deliberately in FiveM resources, using current APIs and avoiding unnecessary lock-in.' --- # fivem-ox-ecosystem ## Purpose @@ -14,20 +14,11 @@ Use ox components when they materially improve the resource and match the existi 5. Respect inventory ownership/metadata semantics rather than direct DB edits. 6. Provide graceful feature disablement when optional ox integrations are absent. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not introduce ox dependencies merely for convenience. @@ -45,4 +36,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/framework-sources.md` in this skill for Overextended documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/references/framework-sources.md b/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/references/framework-sources.md new file mode 100644 index 0000000..cd43722 --- /dev/null +++ b/.agents/skills/04-data-frameworks/fivem-ox-ecosystem/references/framework-sources.md @@ -0,0 +1,11 @@ +# Framework Sources + +Checked: 2026-08-30. + +- Qbox docs: https://docs.qbox.re/ +- QBCore docs: https://docs.qbcore.org/ +- ESX docs: https://docs.esx-framework.org/ +- ox_lib: https://overextended.dev/ox_lib +- oxmysql: https://overextended.dev/oxmysql +- ox_target: https://overextended.dev/ox_target +- ox_inventory: https://overextended.dev/ox_inventory diff --git a/.agents/skills/04-data-frameworks/fivem-qbcore/SKILL.md b/.agents/skills/04-data-frameworks/fivem-qbcore/SKILL.md index 3aae9ab..e50fcad 100644 --- a/.agents/skills/04-data-frameworks/fivem-qbcore/SKILL.md +++ b/.agents/skills/04-data-frameworks/fivem-qbcore/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-qbcore -description: Implement QBCore integrations for players, jobs, money, items, metadata, callbacks, vehicles, permissions, notifications, and lifecycle using the installed server version. +description: 'Implement QBCore integrations for players, jobs, money, items, metadata, callbacks, vehicles, permissions, notifications, and lifecycle using the installed server version.' --- # fivem-qbcore ## Purpose @@ -14,20 +14,11 @@ Use QBCore APIs through a narrow adapter and validate all externally triggered e 5. Respect inventory/vehicle resource boundaries; use their APIs rather than direct table mutation where required. 6. Handle player loaded/unloaded lifecycle and missing player objects. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not assume every QBCore fork exposes identical APIs. @@ -45,4 +36,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/framework-sources.md` in this skill for QBCore documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-qbcore/references/framework-sources.md b/.agents/skills/04-data-frameworks/fivem-qbcore/references/framework-sources.md new file mode 100644 index 0000000..cd43722 --- /dev/null +++ b/.agents/skills/04-data-frameworks/fivem-qbcore/references/framework-sources.md @@ -0,0 +1,11 @@ +# Framework Sources + +Checked: 2026-08-30. + +- Qbox docs: https://docs.qbox.re/ +- QBCore docs: https://docs.qbcore.org/ +- ESX docs: https://docs.esx-framework.org/ +- ox_lib: https://overextended.dev/ox_lib +- oxmysql: https://overextended.dev/oxmysql +- ox_target: https://overextended.dev/ox_target +- ox_inventory: https://overextended.dev/ox_inventory diff --git a/.agents/skills/04-data-frameworks/fivem-qbox/SKILL.md b/.agents/skills/04-data-frameworks/fivem-qbox/SKILL.md index 6c37386..1022bce 100644 --- a/.agents/skills/04-data-frameworks/fivem-qbox/SKILL.md +++ b/.agents/skills/04-data-frameworks/fivem-qbox/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-qbox -description: Implement FiveM integrations for current Qbox/QBX conventions, players, jobs, groups, money, callbacks, metadata, vehicles, inventory bridges, and framework lifecycle. +description: 'Implement FiveM integrations for current Qbox/QBX conventions, players, jobs, groups, money, callbacks, metadata, vehicles, inventory bridges, and framework lifecycle.' --- # fivem-qbox ## Purpose @@ -14,20 +14,11 @@ Use Qbox public APIs/exports and preserve Qbox-owned invariants rather than modi 5. Respect Qbox guidance not to mutate core database tables directly when an API owns the invariant. 6. Handle player unload/resource restart cleanly. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not edit Qbox core for resource-specific behavior. @@ -45,4 +36,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/framework-sources.md` in this skill for Qbox documentation. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/04-data-frameworks/fivem-qbox/references/framework-sources.md b/.agents/skills/04-data-frameworks/fivem-qbox/references/framework-sources.md new file mode 100644 index 0000000..cd43722 --- /dev/null +++ b/.agents/skills/04-data-frameworks/fivem-qbox/references/framework-sources.md @@ -0,0 +1,11 @@ +# Framework Sources + +Checked: 2026-08-30. + +- Qbox docs: https://docs.qbox.re/ +- QBCore docs: https://docs.qbcore.org/ +- ESX docs: https://docs.esx-framework.org/ +- ox_lib: https://overextended.dev/ox_lib +- oxmysql: https://overextended.dev/oxmysql +- ox_target: https://overextended.dev/ox_target +- ox_inventory: https://overextended.dev/ox_inventory diff --git a/.agents/skills/05-game-systems/fivem-input-controls/SKILL.md b/.agents/skills/05-game-systems/fivem-input-controls/SKILL.md index ecd518d..71d6e28 100644 --- a/.agents/skills/05-game-systems/fivem-input-controls/SKILL.md +++ b/.agents/skills/05-game-systems/fivem-input-controls/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-input-controls -description: Design FiveM keyboard/controller input, command/key mapping, control disabling, focus interactions, hold/tap behavior, and conflict-safe cleanup. +description: 'Design FiveM keyboard/controller input, command/key mapping, control disabling, focus interactions, hold/tap behavior, and conflict-safe cleanup.' --- # fivem-input-controls ## Purpose @@ -14,20 +14,11 @@ Make controls configurable, reversible, and compatible with NUI focus/gameplay s 5. Avoid globally disabling broad control sets unless necessary. 6. Document default bindings and conflicts. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not hard-code inaccessible bindings without remapping path. @@ -45,4 +36,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/05-game-systems/fivem-interactions/SKILL.md b/.agents/skills/05-game-systems/fivem-interactions/SKILL.md index 09b4d80..c0d23ba 100644 --- a/.agents/skills/05-game-systems/fivem-interactions/SKILL.md +++ b/.agents/skills/05-game-systems/fivem-interactions/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-interactions -description: Design FiveM interaction systems using targets, zones, context actions, 3D prompts, entities, and keybinds with adapters for ox_target, qb-target, or custom implementations. +description: 'Design FiveM interaction systems using targets, zones, context actions, 3D prompts, entities, and keybinds with adapters for ox_target, qb-target, or custom implementations.' --- # fivem-interactions ## Purpose @@ -14,20 +14,11 @@ Keep interaction discovery client-local but validate privileged actions server-s 5. Avoid registering duplicate targets on resource restart/state change. 6. Provide fallback interaction when optional target dependency is unavailable if required. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not use client role predicates as security. @@ -45,4 +36,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/05-game-systems/fivem-peds-ai/SKILL.md b/.agents/skills/05-game-systems/fivem-peds-ai/SKILL.md index cf2e5be..7cd78d9 100644 --- a/.agents/skills/05-game-systems/fivem-peds-ai/SKILL.md +++ b/.agents/skills/05-game-systems/fivem-peds-ai/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-peds-ai -description: Build FiveM ped AI with task sequences, follow/escort/guard/combat/flee/scenario behavior, relationships, animations, perception, networking, and cleanup. +description: 'Build FiveM ped AI with task sequences, follow/escort/guard/combat/flee/scenario behavior, relationships, animations, perception, networking, and cleanup.' --- # fivem-peds-ai ## Purpose @@ -15,20 +15,11 @@ Use native task systems and relationship configuration while accounting for netw 6. Handle player proximity, scope/ownership migration, and cancellation. 7. Clean relationship/task/entity state on teardown. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not issue tasks every frame. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/05-game-systems/fivem-vehicle-ai/SKILL.md b/.agents/skills/05-game-systems/fivem-vehicle-ai/SKILL.md index 17e159c..39844fa 100644 --- a/.agents/skills/05-game-systems/fivem-vehicle-ai/SKILL.md +++ b/.agents/skills/05-game-systems/fivem-vehicle-ai/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-vehicle-ai -description: Build FiveM vehicle AI for following, escort, convoy, pathfinding, driving styles, speed/gap control, recovery, obstruction handling, and player/AI handover. +description: 'Build FiveM vehicle AI for following, escort, convoy, pathfinding, driving styles, speed/gap control, recovery, obstruction handling, and player/AI handover.' --- # fivem-vehicle-ai ## Purpose @@ -15,20 +15,11 @@ Prefer GTA task natives for baseline driving and layer lightweight supervisory l 6. Handle target deletion, scope loss, driver death, player takeover, and ownership migration. 7. Measure CPU/native-call cost with multiple AI vehicles. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not set steering/velocity/coordinates every frame unless the design explicitly requires custom physics. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/05-game-systems/fivem-vehicles/SKILL.md b/.agents/skills/05-game-systems/fivem-vehicles/SKILL.md index a016f37..d433481 100644 --- a/.agents/skills/05-game-systems/fivem-vehicles/SKILL.md +++ b/.agents/skills/05-game-systems/fivem-vehicles/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-vehicles -description: Implement robust FiveM vehicle systems: creation, persistence, seats, doors, engine, damage, mods, extras, liveries, trailers, towing, ownership, synchronization, and cleanup. +description: 'Implement robust FiveM vehicle systems: creation, persistence, seats, doors, engine, damage, mods, extras, liveries, trailers, towing, ownership, synchronization, and cleanup.' --- # fivem-vehicles ## Purpose @@ -15,20 +15,11 @@ Treat vehicles as networked lifecycle objects with validated ownership and bound 6. Handle driver/passenger transitions and ownership migration. 7. Delete/cleanup on explicit lifecycle and reconcile persistent vehicles on restart. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not trust client vehicle properties as ownership proof. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/05-game-systems/fivem-zones-raycasts/SKILL.md b/.agents/skills/05-game-systems/fivem-zones-raycasts/SKILL.md index ffc1118..dbdfa5e 100644 --- a/.agents/skills/05-game-systems/fivem-zones-raycasts/SKILL.md +++ b/.agents/skills/05-game-systems/fivem-zones-raycasts/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-zones-raycasts -description: Implement spatial queries, zones, raycasts, shape tests, line-of-sight, proximity, and world targeting efficiently in FiveM. +description: 'Implement spatial queries, zones, raycasts, shape tests, line-of-sight, proximity, and world targeting efficiently in FiveM.' --- # fivem-zones-raycasts ## Purpose @@ -15,20 +15,11 @@ Use the cheapest spatial technique that satisfies interaction accuracy and run i 6. Use adaptive sleep when the player is far from interactable areas. 7. Validate critical server actions independently of client hit results. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not raycast multiple times per frame without measured need. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/06-quality/fivem-code-review/SKILL.md b/.agents/skills/06-quality/fivem-code-review/SKILL.md index 9baaa12..7e7a69f 100644 --- a/.agents/skills/06-quality/fivem-code-review/SKILL.md +++ b/.agents/skills/06-quality/fivem-code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-code-review -description: Review FiveM code changes for correctness, architecture, security, networking, lifecycle, performance, persistence, UI, compatibility, and maintainability with evidence-based severity. +description: 'Review FiveM code changes for correctness, architecture, security, networking, lifecycle, performance, persistence, UI, compatibility, and maintainability with evidence-based severity.' --- # fivem-code-review ## Purpose @@ -16,20 +16,11 @@ Act as a senior reviewer: prioritize defects and regression risks over stylistic 7. Check tests against the changed risk surface. 8. Report BLOCKER/HIGH/MEDIUM/LOW with concise remediation. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not manufacture findings to fill severity buckets. @@ -47,4 +38,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/06-quality/fivem-debugging/SKILL.md b/.agents/skills/06-quality/fivem-debugging/SKILL.md index a6217b7..69a4c22 100644 --- a/.agents/skills/06-quality/fivem-debugging/SKILL.md +++ b/.agents/skills/06-quality/fivem-debugging/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-debugging -description: Systematically diagnose FiveM client/server/Lua/NUI/network/database/framework/resource errors and desynchronization. +description: 'Systematically diagnose FiveM client/server/Lua/NUI/network/database/framework/resource errors and desynchronization.' --- # fivem-debugging ## Purpose @@ -15,20 +15,11 @@ Follow evidence from reproduction to root cause across process boundaries instea 6. Check query inputs/results/transactions for DB bugs. 7. Patch the root cause minimally and add regression verification. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not hide stack traces with broad `pcall` without handling. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/06-quality/fivem-observability/SKILL.md b/.agents/skills/06-quality/fivem-observability/SKILL.md index cc92edc..e13ede6 100644 --- a/.agents/skills/06-quality/fivem-observability/SKILL.md +++ b/.agents/skills/06-quality/fivem-observability/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-observability -description: Add practical FiveM observability: structured logs, debug modes, metrics/counters, event tracing, correlation IDs, diagnostics commands, and privacy-conscious telemetry. +description: 'Add practical FiveM observability: structured logs, debug modes, metrics/counters, event tracing, correlation IDs, diagnostics commands, and privacy-conscious telemetry.' --- # fivem-observability ## Purpose @@ -15,20 +15,11 @@ Make production issues diagnosable without flooding console or leaking sensitive 6. Redact tokens, secrets, and unnecessary personal data. 7. Avoid per-frame logging. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not log secrets or full sensitive identifiers unnecessarily. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/06-quality/fivem-performance/SKILL.md b/.agents/skills/06-quality/fivem-performance/SKILL.md index 9dd0232..cefa5e4 100644 --- a/.agents/skills/06-quality/fivem-performance/SKILL.md +++ b/.agents/skills/06-quality/fivem-performance/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-performance -description: Profile and optimize FiveM client/server/NUI performance: resmon, profiler, hot loops, native calls, allocations, events, state bags, entities, database queries, and frontend renders. +description: 'Profile and optimize FiveM client/server/NUI performance: resmon, profiler, hot loops, native calls, allocations, events, state bags, entities, database queries, and frontend renders.' --- # fivem-performance ## Purpose @@ -16,20 +16,11 @@ Measure before optimizing and reduce work at the source: frequency × cost × fa 7. Eliminate N+1/repeated DB queries and add indexes as supported by workload. 8. Profile NUI long tasks/rerenders/layout thrash for complex UIs. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Deterministic helper @@ -51,4 +42,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/performance-checklist.md` in this skill for the profiling checklist. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/06-quality/fivem-performance/references/performance-checklist.md b/.agents/skills/06-quality/fivem-performance/references/performance-checklist.md new file mode 100644 index 0000000..bac8083 --- /dev/null +++ b/.agents/skills/06-quality/fivem-performance/references/performance-checklist.md @@ -0,0 +1,22 @@ +# Performance Checklist + +## Client +- Measure idle/active `resmon` for changed resources. +- Find unconditional `Wait(0)` loops; justify each. +- Reduce native calls and world scans by proximity/event/adaptive sleep/caching. +- Avoid allocation-heavy tables/strings in frame loops. +- Throttle NUI messages and state bag writes. + +## Server +- Profile hot handlers/threads. +- Bound event fanout and payload size. +- Avoid repeated/N+1 DB queries; inspect indexes. +- Bound entity creation and cleanup work. + +## NUI +- Check long tasks, rerenders, layout/paint churn, large images/fonts, and animation cost. +- Prefer transform/opacity for motion. +- Avoid high-frequency full-state replacement when deltas suffice. + +## Evidence +Record the before/after measurement or the exact reproducible measurement plan. diff --git a/.agents/skills/06-quality/fivem-performance/scripts/scan_hotpaths.py b/.agents/skills/06-quality/fivem-performance/scripts/scan_hotpaths.py index 5106fcf..939230e 100755 --- a/.agents/skills/06-quality/fivem-performance/scripts/scan_hotpaths.py +++ b/.agents/skills/06-quality/fivem-performance/scripts/scan_hotpaths.py @@ -1,11 +1,59 @@ #!/usr/bin/env python3 +""" +Scans a FiveM project for potential performance hotpaths. +Identifies Wait(0) loops, threads, state bag writes, and NUI messages. +""" +import argparse +import re +import json from pathlib import Path -import re, argparse -p=argparse.ArgumentParser(); p.add_argument('root', nargs='?', default='.'); a=p.parse_args(); root=Path(a.root).resolve() -patterns=[('wait0',re.compile(r'\b(?:Citizen\.)?Wait\s*\(\s*0\s*\)')),('thread',re.compile(r'\b(?:Citizen\.)?CreateThread\s*\(')),('nui_message',re.compile(r'\bSendNUIMessage\s*\(')),('state_write',re.compile(r'\.state(?::set|\s*\[|\s*\.)'))] -for f in root.rglob('*.lua'): - if '.git' in f.parts or 'node_modules' in f.parts: continue - lines=f.read_text(encoding='utf-8',errors='ignore').splitlines() - for i,line in enumerate(lines,1): - for name,rx in patterns: - if rx.search(line): print(f'{name}\t{f.relative_to(root)}:{i}\t{line.strip()[:180]}') + +def main(): + parser = argparse.ArgumentParser(description="Scan FiveM project for performance hotpaths") + parser.add_argument("root", nargs="?", default=".", help="Project root directory") + parser.add_argument("--format", choices=["json", "text"], default="text", help="Output format") + args = parser.parse_args() + + root = Path(args.root).resolve() + + checks = { + "wait_0_loops": re.compile(r"\b(?:Citizen\.)?Wait\s*\(\s*0\s*\)"), + "threads": re.compile(r"\b(?:Citizen\.)?CreateThread\s*\("), + "nui_messages": re.compile(r"\bSendNUIMessage\s*\("), + "state_writes": re.compile(r"\.state(?::set|\s*\[|\s*\.)"), + "tick_events": re.compile(r"\b(?:RegisterTick|AddEventHandler\s*\(\s*['\"]onTick['\"])\s*\(") + } + + results = {key: [] for key in checks} + + for file_path in root.rglob("*.lua"): + if ".git" in file_path.parts or "node_modules" in file_path.parts: + continue + + try: + text = file_path.read_text(encoding="utf-8", errors="ignore") + lines = text.splitlines() + + for line_idx, line in enumerate(lines, 1): + for kind, pattern in checks.items(): + match = pattern.search(line) + if match: + results[kind].append({ + "file": str(file_path.relative_to(root)), + "line": line_idx, + "snippet": line.strip()[:100] + }) + except Exception: + pass + + if args.format == "json": + print(json.dumps(results, indent=2)) + else: + for kind, findings in results.items(): + print(f"=== {kind.replace('_', ' ').title()} ({len(findings)}) ===") + for f in findings: + print(f" {f['file']}:{f['line']} -> {f['snippet']}") + print() + +if __name__ == "__main__": + main() diff --git a/.agents/skills/06-quality/fivem-security/SKILL.md b/.agents/skills/06-quality/fivem-security/SKILL.md index 49665f2..cbd3fd1 100644 --- a/.agents/skills/06-quality/fivem-security/SKILL.md +++ b/.agents/skills/06-quality/fivem-security/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-security -description: Audit and harden FiveM resources against malicious clients, forged events/callbacks, economy abuse, permission bypass, entity spoofing, replay/race attacks, SQL injection, and exposed secrets. +description: 'Audit and harden FiveM resources against malicious clients, forged events/callbacks, economy abuse, permission bypass, entity spoofing, replay/race attacks, SQL injection, and exposed secrets.' --- # fivem-security ## Purpose @@ -15,20 +15,11 @@ Assume an attacker can trigger client-accessible network events with arbitrary p 6. Prefer allowlists/capabilities over deny-by-obscurity. 7. Log anomalous denials with enough context for investigation but no secrets. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Deterministic helper @@ -50,4 +41,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. See `references/security-checklist.md` and `references/security-sources.md` in this skill for checklists and official docs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/06-quality/fivem-security/references/security-checklist.md b/.agents/skills/06-quality/fivem-security/references/security-checklist.md new file mode 100644 index 0000000..7f86d62 --- /dev/null +++ b/.agents/skills/06-quality/fivem-security/references/security-checklist.md @@ -0,0 +1,15 @@ +# FiveM Security Checklist + +For every externally triggerable server endpoint: + +- [ ] Validate `source` / loaded player/session. +- [ ] Validate payload types, size, enum/range, and required fields. +- [ ] Derive money, reward, price, job/role, item definitions, permissions, and ownership from server-owned state. +- [ ] Validate entity NetID exists, is expected type, and is in an allowed state. +- [ ] Validate proximity/zone on the server when location affects authorization/reward. +- [ ] Validate state transition (e.g. cannot complete before start). +- [ ] Add cooldown/rate limit where spam can create cost or advantage. +- [ ] Define replay/idempotency behavior for purchases/rewards/claims. +- [ ] Use parameterized SQL and transactions for valuable multi-step operations. +- [ ] Do not expose secrets in client/shared/NUI code or replicated state. +- [ ] Log meaningful denied attempts without secrets. diff --git a/.agents/skills/06-quality/fivem-security/references/security-sources.md b/.agents/skills/06-quality/fivem-security/references/security-sources.md new file mode 100644 index 0000000..df56f90 --- /dev/null +++ b/.agents/skills/06-quality/fivem-security/references/security-sources.md @@ -0,0 +1,8 @@ +# FiveM Security Sources + +Checked: 2026-08-30. + +- Server security: https://docs.fivem.net/docs/developers/server-security/ +- NUI callbacks: https://docs.fivem.net/docs/scripting-manual/nui-development/nui-callbacks/ +- OneSync: https://docs.fivem.net/docs/scripting-reference/onesync/ +- Native reference: https://docs.fivem.net/natives/ diff --git a/.agents/skills/06-quality/fivem-security/scripts/scan_attack_surface.py b/.agents/skills/06-quality/fivem-security/scripts/scan_attack_surface.py index ce733ed..f84638a 100755 --- a/.agents/skills/06-quality/fivem-security/scripts/scan_attack_surface.py +++ b/.agents/skills/06-quality/fivem-security/scripts/scan_attack_surface.py @@ -1,17 +1,59 @@ #!/usr/bin/env python3 +""" +Scans a FiveM project for potential security attack surfaces. +Useful for identifying network boundaries and NUI callbacks that require validation. +""" +import argparse +import re +import json from pathlib import Path -import re, argparse -p=argparse.ArgumentParser(); p.add_argument('root', nargs='?', default='.'); a=p.parse_args(); root=Path(a.root).resolve() -checks=[ - ('network_event', re.compile(r"RegisterNetEvent\s*\(\s*['\"]([^'\"]+)")), - ('nui_callback', re.compile(r"Register(?:Nui|NUI)Callback\s*\(\s*['\"]([^'\"]+)")), - ('server_event_trigger', re.compile(r"TriggerServerEvent\s*\(\s*['\"]([^'\"]+)")), -] -for f in root.rglob('*.lua'): - if '.git' in f.parts or 'node_modules' in f.parts: continue - text=f.read_text(encoding='utf-8',errors='ignore') - lines=text.splitlines() - for kind,rx in checks: - for i,line in enumerate(lines,1): - m=rx.search(line) - if m: print(f'{kind}\t{f.relative_to(root)}:{i}\t{m.group(1)}') + +def main(): + parser = argparse.ArgumentParser(description="Scan FiveM project for attack surfaces") + parser.add_argument("root", nargs="?", default=".", help="Project root directory") + parser.add_argument("--format", choices=["json", "text"], default="text", help="Output format") + args = parser.parse_args() + + root = Path(args.root).resolve() + + # Attack surface definitions + checks = { + "network_events": re.compile(r"RegisterNetEvent\s*\(\s*['\"]([^'\"]+)"), + "nui_callbacks": re.compile(r"Register(?:Nui|NUI)Callback\s*\(\s*['\"]([^'\"]+)"), + "server_event_triggers": re.compile(r"TriggerServerEvent\s*\(\s*['\"]([^'\"]+)") + } + + results = {key: [] for key in checks} + + for file_path in root.rglob("*.lua"): + if ".git" in file_path.parts or "node_modules" in file_path.parts: + continue + + try: + text = file_path.read_text(encoding="utf-8", errors="ignore") + lines = text.splitlines() + + for line_idx, line in enumerate(lines, 1): + for kind, pattern in checks.items(): + match = pattern.search(line) + if match: + results[kind].append({ + "file": str(file_path.relative_to(root)), + "line": line_idx, + "name": match.group(1), + "snippet": line.strip()[:100] + }) + except Exception: + pass + + if args.format == "json": + print(json.dumps(results, indent=2)) + else: + for kind, findings in results.items(): + print(f"=== {kind.replace('_', ' ').title()} ({len(findings)}) ===") + for f in findings: + print(f" {f['file']}:{f['line']} -> {f['name']}") + print() + +if __name__ == "__main__": + main() diff --git a/.agents/skills/06-quality/fivem-testing/SKILL.md b/.agents/skills/06-quality/fivem-testing/SKILL.md index db25556..659ad05 100644 --- a/.agents/skills/06-quality/fivem-testing/SKILL.md +++ b/.agents/skills/06-quality/fivem-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-testing -description: Test FiveM resources with static checks, pure-Lua unit tests, frontend tests, integration tests, in-game multi-client scenarios, restart/disconnect cases, and regression matrices. +description: 'Test FiveM resources with static checks, pure-Lua unit tests, frontend tests, integration tests, in-game multi-client scenarios, restart/disconnect cases, and regression matrices.' --- # fivem-testing ## Purpose @@ -15,20 +15,11 @@ Use layered testing because not every GTA runtime behavior is unit-testable outs 6. For networked systems, use at least two clients for ownership/scope cases. 7. Record expected observations and pass/fail evidence. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not call a feature tested because it compiles. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/07-production/fivem-compatibility/SKILL.md b/.agents/skills/07-production/fivem-compatibility/SKILL.md index b53e8cf..3ca50c3 100644 --- a/.agents/skills/07-production/fivem-compatibility/SKILL.md +++ b/.agents/skills/07-production/fivem-compatibility/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-compatibility -description: Assess FiveM compatibility across server artifacts/game builds, GTA5 legacy/enhanced considerations, OneSync modes, frameworks, dependencies, and resource versions. +description: 'Assess FiveM compatibility across server artifacts/game builds, GTA5 legacy/enhanced considerations, OneSync modes, frameworks, dependencies, and resource versions.' --- # fivem-compatibility ## Purpose @@ -15,20 +15,11 @@ State explicit support boundaries and avoid accidental reliance on environment-s 6. Provide migration notes for breaking dependency/API changes. 7. Avoid broad compatibility claims without test evidence. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not promise support for untested forks/builds. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/07-production/fivem-config-localization/SKILL.md b/.agents/skills/07-production/fivem-config-localization/SKILL.md index 97692dd..4c3222c 100644 --- a/.agents/skills/07-production/fivem-config-localization/SKILL.md +++ b/.agents/skills/07-production/fivem-config-localization/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-config-localization -description: Design FiveM configuration and localization for safe defaults, environment-specific values, feature flags, locale files, validation, and backwards-compatible upgrades. +description: 'Design FiveM configuration and localization for safe defaults, environment-specific values, feature flags, locale files, validation, and backwards-compatible upgrades.' --- # fivem-config-localization ## Purpose @@ -15,20 +15,11 @@ Separate deployer-tunable settings from code while keeping secrets server-only a 6. Document breaking config changes and migration defaults. 7. Use ConVars/server config for deployment-specific values when appropriate. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not place secrets in shared/client config. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/07-production/fivem-documentation/SKILL.md b/.agents/skills/07-production/fivem-documentation/SKILL.md index 7f4d4a8..90d1a06 100644 --- a/.agents/skills/07-production/fivem-documentation/SKILL.md +++ b/.agents/skills/07-production/fivem-documentation/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-documentation -description: Write operator and developer documentation for FiveM resources: installation, dependencies, configuration, permissions, events/exports, database, UI build, troubleshooting, security, and upgrade guidance. +description: 'Write operator and developer documentation for FiveM resources: installation, dependencies, configuration, permissions, events/exports, database, UI build, troubleshooting, security, and upgrade guidance.' --- # fivem-documentation ## Purpose @@ -15,20 +15,11 @@ Document the stable contract and operational behavior, not implementation trivia 6. Document common errors and diagnostic commands. 7. Document security assumptions and which values are server authoritative. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not expose secrets in examples. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/07-production/fivem-release/SKILL.md b/.agents/skills/07-production/fivem-release/SKILL.md index c74ac6d..7c2a13b 100644 --- a/.agents/skills/07-production/fivem-release/SKILL.md +++ b/.agents/skills/07-production/fivem-release/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-release -description: Prepare FiveM resources for release: versioning, changelog, migrations, dependency checks, build artifacts, packaging, upgrade notes, rollback, and release verification. +description: 'Prepare FiveM resources for release: versioning, changelog, migrations, dependency checks, build artifacts, packaging, upgrade notes, rollback, and release verification.' --- # fivem-release ## Purpose @@ -15,20 +15,11 @@ Ship reproducible, reviewable releases that operators can upgrade safely. 6. Verify clean install and upgrade from previous supported version when feasible. 7. Define rollback limits, especially after destructive migrations. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not publish dev dependencies/source maps/secrets unintentionally. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.agents/skills/07-production/fivem-resource-packaging/SKILL.md b/.agents/skills/07-production/fivem-resource-packaging/SKILL.md index 185095a..b08945e 100644 --- a/.agents/skills/07-production/fivem-resource-packaging/SKILL.md +++ b/.agents/skills/07-production/fivem-resource-packaging/SKILL.md @@ -1,6 +1,6 @@ --- name: fivem-resource-packaging -description: Package distributable FiveM resources with clean manifests, production UI assets, licenses, source/build separation, optional escrow-aware boundaries, and no secrets or local artifacts. +description: 'Package distributable FiveM resources with clean manifests, production UI assets, licenses, source/build separation, optional escrow-aware boundaries, and no secrets or local artifacts.' --- # fivem-resource-packaging ## Purpose @@ -15,20 +15,11 @@ Create a minimal runtime package while preserving the source repository for deve 6. Verify package on a clean server/resource directory. 7. Generate checksums/release archive if distribution workflow uses them. -## Non-negotiable engineering rules - -- Treat every client and NUI payload as untrusted input. Security-sensitive state is server authoritative. -- Target current CfxLua / Lua 5.4. Do not add `lua54 'yes'`; it is deprecated and unnecessary. -- Prefer `fxmanifest.lua` with `fx_version 'cerulean'` for modern resources unless compatibility evidence requires otherwise. -- Never invent natives, exports, events, framework APIs, SQL columns, or configuration keys. Verify uncertain APIs against project code or authoritative documentation. -- Keep client, server, shared, UI, persistence, and framework-adapter responsibilities explicit. -- Minimize polling and frame loops. `Wait(0)` is reserved for work that genuinely must execute every rendered frame. -- Across network boundaries, use network-safe identifiers and validate existence/ownership/state before mutation. -- Design every entity workflow for create → network/own → use → migration → cleanup/delete, including resource stop and player disconnect. -- NUI callbacks must always return a response; use JSON-encodable contracts and explicit error shapes. -- Prefer small, typed/validated event payloads over large replicated blobs or implicit shared state. -- Do not refactor unrelated code during a focused fix. Preserve existing architecture unless a change is necessary and justified. -- Completion means verification: syntax/static checks, relevant tests, runtime/restart cases, security review, and performance checks proportional to the change. +## Standalone safety + +- Treat client/NUI input as untrusted. Security-sensitive state is server-authoritative. +- Never invent natives, framework APIs, events, exports, or schema. Verify against project code or official docs. +- Completion requires verification proportional to risk. ## Skill-specific guardrails - Do not package credentials or local server data. @@ -46,4 +37,4 @@ When this skill materially affects a task, leave a concise implementation/review ## Reference policy -Use project source and authoritative documentation before relying on memory for version-sensitive APIs. Start with `references/official-sources.md` in this package. When documentation and installed project code disagree, target the installed version and document the compatibility constraint. +Prefer project source and authoritative documentation over memory for version-sensitive APIs. When documentation and installed project code disagree, target the installed version. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..3a6a5fa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,46 @@ +name: Bug Report +description: Create a report to help us improve the Agent Skills +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: input + id: skill + attributes: + label: Affected Skill(s) + description: Which skill(s) caused the problem? e.g. `fivem-security`, `fivem-nui-bridge` + placeholder: "e.g. fivem-security" + validations: + required: true + - type: textarea + id: description + attributes: + label: Description + description: What is the bug? What did the agent do wrong? + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Steps To Reproduce + description: How can we reproduce the bad behavior? (Provide the prompt and context you gave the agent) + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What should the agent have done instead? + validations: + required: true + - type: input + id: agent + attributes: + label: AI Agent / Tool + description: Which agent were you using? e.g. Cursor, Copilot, Antigravity, etc. + placeholder: "e.g. Cursor" + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.yml new file mode 100644 index 0000000..c399c48 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/improvement.yml @@ -0,0 +1,31 @@ +name: Skill Improvement +description: Suggest an improvement to an existing FiveM Agent Skill +title: "[Improvement]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve an existing skill! + - type: input + id: skill + attributes: + label: Target Skill + description: Which skill needs improvement? + placeholder: "e.g. fivem-onesync" + validations: + required: true + - type: textarea + id: improvement + attributes: + label: Proposed Improvement + description: What should be added, changed, or removed in the skill's instructions? + validations: + required: true + - type: textarea + id: reasoning + attributes: + label: Reasoning / Evidence + description: Why is this change necessary? Link to official FiveM docs if applicable. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/skill_request.yml b/.github/ISSUE_TEMPLATE/skill_request.yml new file mode 100644 index 0000000..3ffd840 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/skill_request.yml @@ -0,0 +1,31 @@ +name: Skill Request +description: Request a new FiveM Agent Skill +title: "[Request]: " +labels: ["enhancement", "new-skill"] +body: + - type: markdown + attributes: + value: | + Thanks for proposing a new skill! A good skill solves a specific FiveM engineering problem. + - type: input + id: name + attributes: + label: Proposed Skill Name + description: The name should start with `fivem-`. + placeholder: "e.g. fivem-inventory-system" + validations: + required: true + - type: textarea + id: purpose + attributes: + label: Purpose & Use Cases + description: What problem does this skill solve? When should the agent use it? + validations: + required: true + - type: textarea + id: rules + attributes: + label: Engineering Rules + description: What specific engineering rules, constraints, or best practices should this skill enforce? + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..f966dc4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ +## Description + +Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. + +Fixes # (issue) + +## Type of change + +- [ ] Bug fix (non-breaking change which fixes an issue in a skill) +- [ ] New skill (non-breaking addition of a new FiveM specialist skill) +- [ ] Breaking change (fix or feature that would cause existing behavior to change) +- [ ] Documentation update + +## Validation + +- [ ] I have run `python scripts/validate_skills.py` locally and it passes +- [ ] My changes preserve the required standalone invariants +- [ ] (If adding a skill) I have included the skill in `skills-manifest.json` and updated the `skill_count` + +## Review checklist + +- [ ] I have verified any new FiveM APIs against the official docs +- [ ] I have kept the instructions concise and focused on engineering rules +- [ ] I have not added duplicate context that belongs in `AGENTS.md` diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 75cf2a1..39c4554 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -2,6 +2,7 @@ name: validate-skills on: push: pull_request: + jobs: validate: runs-on: ubuntu-latest @@ -10,4 +11,119 @@ jobs: - uses: actions/setup-python@v5 with: python-version: '3.12' - - run: python scripts/validate_skills.py + - name: Run package validator + run: python scripts/validate_skills.py + + installer-smoke-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Clean project installation + run: | + DEST=$(mktemp -d) + python scripts/install.py --scope project --dest "$DEST" + INSTALLED=$(find "$DEST/.agents/skills" -name SKILL.md | wc -l) + echo "Installed $INSTALLED skills" + [ "$INSTALLED" -eq 43 ] || { echo "FAIL: expected 43, got $INSTALLED"; exit 1; } + + - name: Unrelated skill survives + run: | + DEST=$(mktemp -d) + mkdir -p "$DEST/.agents/skills/unrelated-skill" + echo "---\nname: unrelated-skill\ndescription: test\n---\n# test" > "$DEST/.agents/skills/unrelated-skill/SKILL.md" + python scripts/install.py --scope project --dest "$DEST" + [ -f "$DEST/.agents/skills/unrelated-skill/SKILL.md" ] || { echo "FAIL: unrelated skill deleted"; exit 1; } + echo "OK: unrelated skill preserved" + + - name: Reinstall without force skips + run: | + DEST=$(mktemp -d) + python scripts/install.py --scope project --dest "$DEST" + python scripts/install.py --scope project --dest "$DEST" 2>&1 | tee output.txt + SKIPPED=$(grep -c "SKIP fivem-" output.txt || true) + echo "Skipped $SKIPPED skills on reinstall" + [ "$SKIPPED" -ge 43 ] || { echo "FAIL: expected 43 skips, got $SKIPPED"; exit 1; } + + - name: Force replaces matching skills + run: | + DEST=$(mktemp -d) + mkdir -p "$DEST/.agents/skills/unrelated-skill" + echo "test" > "$DEST/.agents/skills/unrelated-skill/SKILL.md" + python scripts/install.py --scope project --dest "$DEST" --force + [ -f "$DEST/.agents/skills/unrelated-skill/SKILL.md" ] || { echo "FAIL: unrelated skill deleted by force"; exit 1; } + INSTALLED=$(find "$DEST/.agents/skills" -name SKILL.md | wc -l) + echo "Installed $INSTALLED skills (includes unrelated)" + [ "$INSTALLED" -eq 44 ] || { echo "FAIL: expected 44 (43+1), got $INSTALLED"; exit 1; } + + - name: Portable references exist after install + run: | + DEST=$(mktemp -d) + python scripts/install.py --scope project --dest "$DEST" + # Check that skills with references have them + for skill in fivem-router fivem-security fivem-performance fivem-nui-bridge fivem-nui fivem-onesync fivem-cfxlua; do + REF_DIR="$DEST/.agents/skills/$skill/references" + if [ -d "$REF_DIR" ] && [ "$(ls -A "$REF_DIR")" ]; then + echo "OK: $skill has references" + else + echo "FAIL: $skill missing references directory or files" + exit 1 + fi + done + + - name: Root AGENTS.md not overwritten if present + run: | + DEST=$(mktemp -d) + echo "# Existing project instructions" > "$DEST/AGENTS.md" + python scripts/install.py --scope project --dest "$DEST" + head -1 "$DEST/AGENTS.md" | grep -q "Existing project" || { echo "FAIL: root AGENTS.md overwritten"; exit 1; } + echo "OK: existing AGENTS.md preserved" + + installer-windows: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + - name: PowerShell install smoke test + shell: pwsh + run: | + $Dest = Join-Path $env:RUNNER_TEMP "fivem-test-project" + New-Item -Path $Dest -ItemType Directory -Force | Out-Null + & .\scripts\install.ps1 -Scope Project -Dest $Dest + $count = (Get-ChildItem -Path (Join-Path $Dest ".agents\skills") -Recurse -Filter "SKILL.md").Count + Write-Host "Installed $count skills" + if ($count -ne 43) { throw "Expected 43 skills, got $count" } + + skills-discovery: + runs-on: ubuntu-latest + # The skills CLI test might fail due to network/npm registry issues. + # We allow it to fail so package validation remains deterministic, + # but still provide an explicit Vercel skills CLI smoke-test path. + continue-on-error: true + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + - name: Check skills.sh discovery (Vercel CLI) + run: | + # Use the real Vercel skills CLI to verify it can discover the local checkout + # We extract all matching "fivem-*" skill names from the output. + echo "Running 'npx -y skills@latest add . --list'..." + CLI_OUTPUT=$(npx -y skills@latest add . --list) + + # Count unique 'fivem-*' skills, ignoring the 'fivem-agent-skills' package name itself + CLI_COUNT=$(echo "$CLI_OUTPUT" | grep -o "fivem-[a-zA-Z0-9-]*" | grep -v "fivem-agent-skills" | sort | uniq | wc -l) + + echo "CLI discovered $CLI_COUNT skills." + if [ "$CLI_COUNT" -eq 43 ]; then + echo "OK: skills CLI successfully discovered 43 skills." + exit 0 + else + echo "FAIL: expected 43, got $CLI_COUNT" + echo "Raw output:" + echo "$CLI_OUTPUT" + exit 1 + fi diff --git a/.gitignore b/.gitignore index a172144..2ff69c7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,16 @@ .DS_Store +Thumbs.db .idea/ .vscode/ __pycache__/ +.mypy_cache/ +.pytest_cache/ *.pyc *.zip +*.log +logs/ +node_modules/ +coverage/ +.env +.env.* +!.env.example diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..87a3a73 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.1] - 2026-08-30 + +### Fixed +- **YAML Parser Compatibility**: Quoted all YAML frontmatter descriptions to fix a strict parsing bug that caused `skills.sh` to only discover 35 of 43 skills. +- **Portable References**: Fixed broken `references/official-sources.md` path in all skills when installed standalone. Replaced with domain-specific reference files that travel with each skill. +- **NUI Contract**: Hardened `nuiFetch` in the `nui-bridge` template to properly catch and normalize timeout, network, HTTP, and JSON parse errors instead of leaking exceptions. +- **Context Duplication**: Replaced the duplicated 900-byte "Non-negotiable engineering rules" block in all 43 skills with a compact "Standalone safety" section, reducing total skill byte size by ~39%. + +### Added +- **Expanded Validator**: `scripts/validate_skills.py` now checks structural integrity, manifest consistency, version matching, portable references, Python syntax, and eval schemas. +- **Installer Improvements**: `install.py` and `install.ps1` now support `--dry-run`, `--verify`, and generate a `.agents/fivem-agent-skills.json` installation receipt. +- **Community Files**: Added `CONTRIBUTING.md`, `SECURITY.md`, and issue/PR templates. +- **CI Enhancements**: Added installer smoke tests for both Linux and Windows environments. + +## [1.0.0] - 2026-08-15 + +### Added +- Initial release of FiveM Agent Skills. +- 43 specialized skills across 8 engineering domains. +- `fivem-router` for progressive disclosure of expertise. +- `fivem-project-inspector` for existing repository analysis. +- Orchestration modes: BUILD, FIX, AUDIT. +- Security-first and OneSync-aware engineering constraints. +- NUI, database, and framework (Qbox, QBCore, ESX) integration guidance. +- Deterministic helper scripts for project, UI, performance, and security scanning. +- Python and PowerShell installer scripts. +- Evals harness with 10 regression scenarios. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d04f960 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to FiveM Agent Skills + +Thank you for your interest in improving FiveM Agent Skills! This toolkit relies on community expertise to ensure AI coding agents make sound engineering decisions. + +## High-Value Contributions + +We particularly welcome: +- Corrections to outdated FiveM behavior or native documentation +- New regression evals that capture recurring AI mistakes +- Improved security patterns and exploit mitigation +- Improved OneSync and state bag guidance +- Framework compatibility updates (Qbox, QBCore, ESX, ox) +- New deterministic analysis tools (`scripts/*.py`) +- Missing specialist skills + +## Adding a New Skill + +A new skill should solve a specific engineering problem rather than duplicate generic instructions. + +1. **Focus:** Avoid giant catch-all skills. Prefer a focused specialist. +2. **Structure:** Create a directory under the appropriate domain in `.agents/skills/`. +3. **SKILL.md:** Must contain valid YAML frontmatter with `name` and `description` (description must be single-quoted if it contains colons). +4. **Required sections:** Include `## Purpose`, `## Workflow`, `## Standalone safety`, `## Done criteria`, and `## Output contract`. +5. **Portability:** If you reference official docs, create a `references/` directory in your skill and include a small markdown file with the links. Do not point to global reference files. +6. **Manifest:** Add the new skill to `skills-manifest.json` and increment `skill_count`. + +## Making Changes to Existing Skills + +When modifying existing skills: +- **Do not add large duplicated blocks** (e.g., repeating the entire `AGENTS.md` content). Keep skills concise. +- **Ensure standalone safety:** Each skill should retain the critical invariants (untrusted input, no inventing APIs, verification). +- **Run the validator:** Always run `python scripts/validate_skills.py` before submitting a PR. + +## Evals + +If you are fixing a recurring agent failure, please consider adding a regression eval in `evals/cases/`. +An eval is a simple JSON file containing: +- `prompt`: The user request that triggers the failure +- `expected_skills`: The skills the router should select +- `assertions`: What the agent must do correctly +- `forbidden_patterns`: What the agent must avoid + +## Pull Request Process + +1. Create a branch for your feature/fix. +2. Ensure `python scripts/validate_skills.py` passes completely. +3. Open a Pull Request using the provided template. +4. Maintainers will review the engineering advice for safety and accuracy. diff --git a/README.md b/README.md index 216087f..597a1c6 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ A modular, reusable Agent Skills toolkit that gives modern AI coding agents deep FiveM-specific engineering knowledge — from resource architecture and Lua development to networking, custom UIs, framework integration, security auditing, performance optimization, testing, and production releases. -**Designed for Codex · Cursor · Google Antigravity · Agent Skills compatible tooling** +**Designed for Codex · Cursor · Google Antigravity · Claude · Agent Skills compatible tooling** + +[![skills.sh compatible](https://img.shields.io/badge/skills.sh-compatible-blue?logo=vercel&logoColor=white)](https://skills.sh) @@ -456,7 +458,31 @@ LOW # Installation -## Recommended: project-local installation +## Quick Start (Recommended) + +This package is fully compatible with [skills.sh](https://skills.sh), the universal Agent Skills package manager. + +To install into your project interactively: + +```bash +npx skills add CodeCrafter98/fivem-agent-skills +``` + +To install specific skills (e.g. for a UI task): + +```bash +npx skills add CodeCrafter98/fivem-agent-skills -s fivem-nui fivem-nui-bridge fivem-ui-design +``` + +To install globally for a specific agent: + +```bash +npx skills add CodeCrafter98/fivem-agent-skills --global --agent antigravity +``` + +--- + +## Manual / Offline Installation Project-local installation is recommended because the skills become part of the repository and travel with the codebase. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1cd2e5f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,26 @@ +# Security Policy + +## Supported Versions + +Currently, only the latest release of FiveM Agent Skills receives security updates. + +| Version | Supported | +| ------- | ------------------ | +| 1.0.x | :white_check_mark: | +| < 1.0 | :x: | + +## Reporting a Vulnerability + +If you discover a vulnerability in the *guidance* provided by these skills (e.g., a skill instructs an agent to use an insecure pattern that allows SQL injection, event forging, or economy abuse), please report it. + +**Do not open a public issue.** + +Instead, please email the details to the maintainer or send a direct message on the relevant community platforms (Discord/GitHub). + +We take security guidance seriously. Since these skills are used to generate server code, bad security advice in a skill propagates to live servers. We will issue a patch release as quickly as possible to correct the guidance. + +When reporting, please include: +- The name of the skill(s) providing the insecure advice +- A brief description of the vulnerability pattern +- A prompt that reliably causes the agent to generate the insecure code +- (Optional) The official FiveM/framework documentation proving the pattern is insecure diff --git a/VERSION b/VERSION index 3eefcb9..7dea76e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.0 +1.0.1 diff --git a/adapters/antigravity/README.md b/adapters/antigravity/README.md index 655dcec..7a95055 100644 --- a/adapters/antigravity/README.md +++ b/adapters/antigravity/README.md @@ -1,3 +1,16 @@ # Google Antigravity -Workspace skills: `.agents/skills//SKILL.md`. Persistent workspace instructions can use `.agents/AGENTS.md`. For user-global compatibility, the installer can also copy skills to `~/.gemini/config/skills/`. +Antigravity natively supports Agent Skills discovery. + +**Installation via skills.sh (Recommended):** +```bash +npx skills add CodeCrafter98/fivem-agent-skills --agent antigravity +``` + +**Project workspace skills:** +`.agents/skills//SKILL.md` + +**Global user skills:** +`~/.gemini/config/skills//SKILL.md` + +Antigravity uses the `skills-manifest.json` and SKILL.md frontmatter to progressively load only the necessary engineering context when a FiveM task is detected. diff --git a/adapters/codex/README.md b/adapters/codex/README.md index 31e69ce..842d575 100644 --- a/adapters/codex/README.md +++ b/adapters/codex/README.md @@ -1,3 +1,8 @@ # OpenAI Codex +**Installation via skills.sh (Recommended):** +```bash +npx skills add CodeCrafter98/fivem-agent-skills --agent codex +``` + Keep the canonical pack project-local under `.agents/skills/` and retain root `AGENTS.md` as the concise FiveM constitution. Project-local installation is preferred for reproducibility across desktop/CLI/cloud contexts. If your current Codex build uses a different user-global discovery path, keep project-local `.agents/skills/` as the source of truth rather than duplicating edited skill copies. diff --git a/adapters/cursor/README.md b/adapters/cursor/README.md index 9ecf983..c3ea4dd 100644 --- a/adapters/cursor/README.md +++ b/adapters/cursor/README.md @@ -1,3 +1,8 @@ # Cursor -Prefer project-local `.agents/skills/` for portability. Cursor currently discovers `.agents/skills/` directly and progressively loads skills based on their descriptions. Keep persistent project-specific rules short; do not duplicate all skill content into Cursor rules. +**Installation via skills.sh (Recommended):** +```bash +npx skills add CodeCrafter98/fivem-agent-skills --agent cursor +``` + +Prefer project-local `.agents/skills/` for portability. Cursor currently discovers `.agents/skills/` directly and progressively loads skills based on their descriptions. Keep persistent project-specific rules short; do not duplicate all skill content into Cursor rules (e.g. `.cursorrules`). diff --git a/scripts/install.ps1 b/scripts/install.ps1 index ac83b6c..2f5a7cf 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -1,35 +1,218 @@ -param( - [ValidateSet("Project","Global")][string]$Scope = "Project", - [string]$Dest = ".", - [switch]$AntigravityCompat, - [switch]$Force +<# +.SYNOPSIS +Safely install FiveM Agent Skills into a project or globally. + +.DESCRIPTION +Copies skill directories and core instructions to a target project or global agent directory. +Never deletes unrelated existing skills, even with -Force. + +.PARAMETER Scope +Install scope: 'Project' (into -Dest) or 'Global' (~/.agents/skills). + +.PARAMETER Dest +Target project root (required if Scope is 'Project'). + +.PARAMETER AntigravityCompat +Also install to ~/.gemini/config/skills for Antigravity global discovery. + +.PARAMETER Force +Replace existing FiveM skill directories (never deletes unrelated skills). + +.PARAMETER DryRun +Show what would be installed without making changes. + +.PARAMETER Verify +Run post-install validation to ensure files were written. + +.PARAMETER Version +Show script version. +#> + +[CmdletBinding(DefaultParameterSetName="Default")] +param ( + [Parameter(Mandatory=$true, ParameterSetName="Default")] + [ValidateSet('Project', 'Global')] + [string]$Scope, + + [Parameter(Mandatory=$false, ParameterSetName="Default")] + [string]$Dest, + + [Parameter(Mandatory=$false, ParameterSetName="Default")] + [switch]$AntigravityCompat, + + [Parameter(Mandatory=$false, ParameterSetName="Default")] + [switch]$Force, + + [Parameter(Mandatory=$false, ParameterSetName="Default")] + [switch]$DryRun, + + [Parameter(Mandatory=$false, ParameterSetName="Default")] + [switch]$Verify, + + [Parameter(Mandatory=$true, ParameterSetName="Version")] + [switch]$Version ) -$Root = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path) -$Source = Join-Path $Root ".agents\skills" -function Install-Skills($TargetRoot) { - New-Item $TargetRoot -ItemType Directory -Force | Out-Null - $Installed = 0; $Skipped = 0 - Get-ChildItem $Source -Recurse -Filter SKILL.md | ForEach-Object { - $SkillDir = $_.Directory - $Target = Join-Path $TargetRoot $SkillDir.Name - if (Test-Path $Target) { - if (-not $Force) { Write-Host "SKIP existing: $Target"; $Skipped++; return } - Remove-Item $Target -Recurse -Force - } - Copy-Item $SkillDir.FullName $Target -Recurse - $Installed++ - } - Write-Host "Installed $Installed skills into $TargetRoot; skipped $Skipped." + +$ErrorActionPreference = "Stop" +$ScriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition +$RepoRoot = Split-Path -Parent $ScriptRoot +$SrcSkills = Join-Path $RepoRoot ".agents\skills" + +$VersionFile = Join-Path $RepoRoot "VERSION" +$VerStr = "unknown" +if (Test-Path $VersionFile) { + $VerStr = (Get-Content $VersionFile).Trim() } -if ($Scope -eq "Project") { - $TargetRoot = (Resolve-Path $Dest).Path - Install-Skills (Join-Path $TargetRoot ".agents\skills") - $AgentsDir = Join-Path $TargetRoot ".agents"; New-Item $AgentsDir -ItemType Directory -Force | Out-Null - $AgTarget = Join-Path $AgentsDir "AGENTS.md" - if ((-not (Test-Path $AgTarget)) -or $Force) { Copy-Item (Join-Path $Root ".agents\AGENTS.md") $AgTarget -Force } else { Write-Host "SKIP existing: $AgTarget" } - $RootTarget = Join-Path $TargetRoot "AGENTS.md" - if (-not (Test-Path $RootTarget)) { Copy-Item (Join-Path $Root "AGENTS.md") $RootTarget } else { Write-Host "SKIP existing: $RootTarget" } + +if ($Version) { + Write-Host "FiveM Agent Skills v$VerStr" + exit 0 +} + +Write-Host "FiveM Agent Skills v$VerStr" +Write-Host "Source: $RepoRoot`n" + +function Install-Skills { + param([string]$TargetRoot) + + if (-not $DryRun -and -not (Test-Path $TargetRoot)) { + New-Item -ItemType Directory -Force -Path $TargetRoot | Out-Null + } + + $SkillDirs = Get-ChildItem -Path $SrcSkills -Directory -Recurse | Where-Object { Test-Path (Join-Path $_.FullName "SKILL.md") } + $Installed = 0 + $Skipped = 0 + $SkillNames = @() + + foreach ($Dir in $SkillDirs) { + $Dst = Join-Path $TargetRoot $Dir.Name + $SkillNames += $Dir.Name + + if (Test-Path $Dst) { + if (-not $Force) { + if (-not $DryRun) { Write-Host " SKIP $($Dir.Name)" } + $Skipped++ + continue + } + if (-not $DryRun) { Remove-Item -Recurse -Force $Dst } + } + + if ($DryRun) { + Write-Host " WOULD INSTALL $($Dir.Name) -> $Dst" + } else { + Copy-Item -Recurse -Force $Dir.FullName $Dst + } + $Installed++ + } + + $Action = if ($DryRun) { "Would install" } else { "Installed" } + Write-Host "`n $Action $Installed skills into $TargetRoot; skipped $Skipped." + + return @{ Installed = $Installed; Skipped = $Skipped; Names = $SkillNames } +} + +function Write-Receipt { + param([string]$TargetDir, [string[]]$Names) + + if ($DryRun) { return } + + $ReceiptPath = Join-Path $TargetDir ".agents\fivem-agent-skills.json" + $ReceiptDir = Split-Path -Parent $ReceiptPath + if (-not (Test-Path $ReceiptDir)) { + New-Item -ItemType Directory -Force -Path $ReceiptDir | Out-Null + } + + $Receipt = @{ + package = "fivem-agent-skills" + version = $VerStr + source = "https://github.com/CodeCrafter98/fivem-agent-skills" + installed_at = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ") + skill_count = $Names.Count + skills = $Names | Sort-Object + } + + $Receipt | ConvertTo-Json -Depth 3 | Set-Content $ReceiptPath -Encoding UTF8 + Write-Host " Receipt -> $ReceiptPath" +} + +function Verify-Installation { + param([string]$TargetRoot, [int]$ExpectedCount) + + if (-not (Test-Path $TargetRoot)) { return } + $Found = @(Get-ChildItem -Path $TargetRoot -Recurse -Filter "SKILL.md") + $FiveMSkills = $Found | Where-Object { $_.Directory.Name -like "fivem-*" } + + Write-Host "`n Verify: $($FiveMSkills.Count) FiveM skills found in $TargetRoot" + if ($FiveMSkills.Count -lt $ExpectedCount) { + Write-Host " WARNING: expected at least $ExpectedCount FiveM skills" -ForegroundColor Yellow + } +} + +if ($Scope -eq 'Project') { + if (-not $Dest) { + Write-Error "Error: -Dest is required for project scope" + exit 1 + } + + $DestPath = (Resolve-Path $Dest -ErrorAction Ignore).ProviderPath + if (-not $DestPath) { $DestPath = $Dest } + Write-Host "Installing to project: $DestPath" + + $TargetSkills = Join-Path $DestPath ".agents\skills" + $Result = Install-Skills -TargetRoot $TargetSkills + Write-Receipt -TargetDir $DestPath -Names $Result.Names + + $AgDir = Join-Path $DestPath ".agents" + if (-not $DryRun -and -not (Test-Path $AgDir)) { + New-Item -ItemType Directory -Force -Path $AgDir | Out-Null + } + + $AgTarget = Join-Path $AgDir "AGENTS.md" + $AgSrc = Join-Path $RepoRoot ".agents\AGENTS.md" + if (-not (Test-Path $AgTarget) -or $Force) { + if (-not $DryRun) { + Copy-Item $AgSrc $AgTarget -Force + Write-Host " Installed FiveM instructions -> $AgTarget" + } else { + Write-Host " WOULD INSTALL .agents\AGENTS.md -> $AgTarget" + } + } else { + Write-Host " SKIP $AgTarget (merge manually if desired)" + } + + $RootTarget = Join-Path $DestPath "AGENTS.md" + $RootSrc = Join-Path $RepoRoot "AGENTS.md" + if (-not (Test-Path $RootTarget)) { + if (-not $DryRun) { + Copy-Item $RootSrc $RootTarget + Write-Host " Installed root instructions -> $RootTarget" + } else { + Write-Host " WOULD INSTALL AGENTS.md -> $RootTarget" + } + } else { + Write-Host " SKIP $RootTarget (will not overwrite project AGENTS.md)" + } + + if ($Verify -and -not $DryRun) { + Verify-Installation -TargetRoot $TargetSkills -ExpectedCount $Result.Installed + } + } else { - Install-Skills (Join-Path $HOME ".agents\skills") - if ($AntigravityCompat) { Install-Skills (Join-Path $HOME ".gemini\config\skills") } + $HomeDir = [System.Environment]::GetFolderPath('UserProfile') + Write-Host "Installing globally for user: $HomeDir" + + $GlobalSkills = Join-Path $HomeDir ".agents\skills" + $Result = Install-Skills -TargetRoot $GlobalSkills + + if ($AntigravityCompat) { + Write-Host "`nAntigravity compatibility:" + $AgSkills = Join-Path $HomeDir ".gemini\config\skills" + Install-Skills -TargetRoot $AgSkills | Out-Null + } + + if ($Verify -and -not $DryRun) { + Verify-Installation -TargetRoot $GlobalSkills -ExpectedCount $Result.Installed + } } + +Write-Host "`nDone." diff --git a/scripts/install.py b/scripts/install.py index 7d61293..7047ec5 100755 --- a/scripts/install.py +++ b/scripts/install.py @@ -1,56 +1,154 @@ #!/usr/bin/env python3 """Safely install FiveM Agent Skills without deleting unrelated existing skills.""" from pathlib import Path -import argparse, shutil +import argparse, shutil, json, datetime root = Path(__file__).resolve().parents[1] src_skills = root / '.agents' / 'skills' -parser=argparse.ArgumentParser() -parser.add_argument('--scope', choices=['project','global'], required=True) -parser.add_argument('--dest', help='Target project root for --scope project') -parser.add_argument('--antigravity-compat', action='store_true', help='Also install a compatibility copy to ~/.gemini/config/skills') -parser.add_argument('--force', action='store_true', help='Replace only conflicting FiveM skill directories; never deletes unrelated skills') -a=parser.parse_args() +version_file = root / 'VERSION' +version = version_file.read_text(encoding='utf-8').strip() if version_file.exists() else 'unknown' + +parser = argparse.ArgumentParser( + description='Install FiveM Agent Skills into a project or globally.', + epilog='Preferred installation method: npx skills add CodeCrafter98/fivem-agent-skills' +) +parser.add_argument('--scope', choices=['project', 'global'], required=True, + help='Install scope: project (into --dest) or global (~/.agents/skills)') +parser.add_argument('--dest', help='Target project root (required for --scope project)') +parser.add_argument('--antigravity-compat', action='store_true', + help='Also install to ~/.gemini/config/skills for Antigravity global discovery') +parser.add_argument('--force', action='store_true', + help='Replace existing FiveM skill directories (never deletes unrelated skills)') +parser.add_argument('--dry-run', action='store_true', + help='Show what would be installed without making changes') +parser.add_argument('--verify', action='store_true', + help='Run post-install validation') +parser.add_argument('--version', action='version', version=f'FiveM Agent Skills v{version}') +args = parser.parse_args() + def iter_skills(): + """Yield each skill directory (contains SKILL.md).""" for skill_md in sorted(src_skills.rglob('SKILL.md')): yield skill_md.parent -def install_skills(target_root: Path): - target_root.mkdir(parents=True, exist_ok=True) - installed=skipped=0 + +def install_skills(target_root: Path) -> tuple[int, int, list[str]]: + """Install skills into target_root. Returns (installed, skipped, skill_names).""" + if not args.dry_run: + target_root.mkdir(parents=True, exist_ok=True) + + installed = 0 + skipped = 0 + names = [] + for skill_dir in iter_skills(): dst = target_root / skill_dir.name + names.append(skill_dir.name) + if dst.exists(): - if not a.force: - print(f'SKIP existing: {dst}') + if not args.force: + if not args.dry_run: + print(f' SKIP {skill_dir.name}') skipped += 1 continue - shutil.rmtree(dst) - shutil.copytree(skill_dir, dst) + if not args.dry_run: + shutil.rmtree(dst) + + if args.dry_run: + print(f' WOULD INSTALL {skill_dir.name} -> {dst}') + else: + shutil.copytree(skill_dir, dst) installed += 1 - print(f'Installed {installed} skills into {target_root}; skipped {skipped}.') - -if a.scope == 'project': - if not a.dest: raise SystemExit('--dest is required for project scope') - dest=Path(a.dest).expanduser().resolve() - install_skills(dest/'.agents'/'skills') - # Antigravity can consume .agents/AGENTS.md; do not overwrite project instructions accidentally. - ag_dir=dest/'.agents'; ag_dir.mkdir(parents=True, exist_ok=True) - ag_target=ag_dir/'AGENTS.md' - if not ag_target.exists() or a.force: - shutil.copy2(root/'.agents'/'AGENTS.md', ag_target) - print(f'Installed FiveM instructions -> {ag_target}') + + action = 'Would install' if args.dry_run else 'Installed' + print(f'\n {action} {installed} skills into {target_root}; skipped {skipped}.') + return installed, skipped, names + + +def write_receipt(target_dir: Path, skill_names: list[str]): + """Write an installation receipt for traceability.""" + if args.dry_run: + return + + receipt_path = target_dir / '.agents' / 'fivem-agent-skills.json' + receipt_path.parent.mkdir(parents=True, exist_ok=True) + receipt = { + 'package': 'fivem-agent-skills', + 'version': version, + 'source': 'https://github.com/CodeCrafter98/fivem-agent-skills', + 'installed_at': datetime.datetime.now(datetime.timezone.utc).isoformat(), + 'skill_count': len(skill_names), + 'skills': sorted(skill_names), + } + receipt_path.write_text(json.dumps(receipt, indent=2) + '\n', encoding='utf-8') + print(f' Receipt -> {receipt_path}') + + +def verify_installation(target_root: Path, expected_count: int): + """Basic post-install verification.""" + found = list(target_root.rglob('SKILL.md')) + fivem_skills = [p for p in found if p.parent.name.startswith('fivem-')] + print(f'\n Verify: {len(fivem_skills)} FiveM skills found in {target_root}') + if len(fivem_skills) < expected_count: + print(f' WARNING: expected at least {expected_count} FiveM skills') + + +# ─── Main ────────────────────────────────────────────────────────────── + +print(f'FiveM Agent Skills v{version}') +print(f'Source: {root}') +print() + +if args.scope == 'project': + if not args.dest: + raise SystemExit('Error: --dest is required for project scope') + + dest = Path(args.dest).expanduser().resolve() + print(f'Installing to project: {dest}') + + installed, skipped, names = install_skills(dest / '.agents' / 'skills') + write_receipt(dest, names) + + # Install .agents/AGENTS.md + ag_dir = dest / '.agents' + if not args.dry_run: + ag_dir.mkdir(parents=True, exist_ok=True) + ag_target = ag_dir / 'AGENTS.md' + if not ag_target.exists() or args.force: + if not args.dry_run: + shutil.copy2(root / '.agents' / 'AGENTS.md', ag_target) + print(f' Installed FiveM instructions -> {ag_target}') + else: + print(f' WOULD INSTALL .agents/AGENTS.md -> {ag_target}') else: - print(f'SKIP existing: {ag_target} (merge {root / ".agents" / "AGENTS.md"} manually if desired)') - root_target=dest/'AGENTS.md' + print(f' SKIP {ag_target} (merge manually if desired)') + + # Install root AGENTS.md only if none exists (do not overwrite project instructions) + root_target = dest / 'AGENTS.md' if not root_target.exists(): - shutil.copy2(root/'AGENTS.md', root_target) - print(f'Installed root instructions -> {root_target}') + if not args.dry_run: + shutil.copy2(root / 'AGENTS.md', root_target) + print(f' Installed root instructions -> {root_target}') + else: + print(f' WOULD INSTALL AGENTS.md -> {root_target}') else: - print(f'SKIP existing: {root_target} (do not overwrite project AGENTS.md automatically)') + print(f' SKIP {root_target} (will not overwrite project AGENTS.md)') + + if args.verify and not args.dry_run: + verify_installation(dest / '.agents' / 'skills', installed) + else: - home=Path.home() - install_skills(home/'.agents'/'skills') - if a.antigravity_compat: - install_skills(home/'.gemini'/'config'/'skills') + home = Path.home() + print(f'Installing globally for user: {home}') + + installed, skipped, names = install_skills(home / '.agents' / 'skills') + + if args.antigravity_compat: + print('\nAntigravity compatibility:') + install_skills(home / '.gemini' / 'config' / 'skills') + + if args.verify and not args.dry_run: + verify_installation(home / '.agents' / 'skills', installed) + +print('\nDone.') diff --git a/scripts/validate_skills.py b/scripts/validate_skills.py index df87b27..1cd8f41 100755 --- a/scripts/validate_skills.py +++ b/scripts/validate_skills.py @@ -1,36 +1,290 @@ #!/usr/bin/env python3 +""" +FiveM Agent Skills — Package Validator v1.0.1 + +Validates skill structure, manifest integrity, version consistency, +portable references, Python syntax, eval cases, and templates. + +Exit code 0 = all checks pass. Non-zero = at least one failure. +""" from pathlib import Path -import re, sys +import json, re, sys, py_compile, tempfile root = Path(__file__).resolve().parents[1] skills_root = root / '.agents' / 'skills' -errors=[]; count=0 -for p in sorted(skills_root.rglob('SKILL.md')): - count += 1 - text=p.read_text(encoding='utf-8') - m=re.match(r'^---\n(.*?)\n---\n', text, re.S) - if not m: - errors.append(f'{p}: missing YAML frontmatter') +errors = [] + + +def err(msg: str): + errors.append(msg) + + +def section(title: str): + print(f'\n--- {title} ---') + + +# ─── 1. Skill Structure ─────────────────────────────────────────────── + +section('Skill structure') + +skill_dirs = [] +skill_names = [] + +for skill_md in sorted(skills_root.rglob('SKILL.md')): + skill_dir = skill_md.parent + skill_dirs.append(skill_dir) + + text = skill_md.read_text(encoding='utf-8') + + # Frontmatter + fm_match = re.match(r'^---\n(.*?)\n---\n', text, re.S) + if not fm_match: + err(f'{skill_md}: missing YAML frontmatter') continue - fm=m.group(1) - name=re.search(r'^name:\s*(.+)$', fm, re.M) - desc=re.search(r'^description:\s*(.+)$', fm, re.M) - if not name or not desc: - errors.append(f'{p}: name/description required') + + fm = fm_match.group(1) + name_match = re.search(r'^name:\s*(.+)$', fm, re.M) + desc_match = re.search(r"^description:\s*['\"]?(.+?)['\"]?\s*$", fm, re.M) + + if not name_match: + err(f'{skill_md}: missing name in frontmatter') + continue + if not desc_match: + err(f'{skill_md}: missing description in frontmatter') continue - n=name.group(1).strip() - d=desc.group(1).strip() - if n != p.parent.name: - errors.append(f'{p}: name {n!r} != parent {p.parent.name!r}') - if not re.fullmatch(r'[a-z0-9-]+', n): - errors.append(f'{p}: invalid skill name') - if len(d) > 1024: - errors.append(f'{p}: description exceeds 1024 characters') - for section in ['## Purpose','## Workflow','## Done criteria','## Output contract']: - if section not in text: - errors.append(f'{p}: missing {section}') + + name = name_match.group(1).strip().strip("'\"") + desc = desc_match.group(1).strip().strip("'\"") + + # Name matches directory + if name != skill_dir.name: + err(f'{skill_md}: name {name!r} != directory {skill_dir.name!r}') + + # Valid characters + if not re.fullmatch(r'[a-z0-9-]+', name): + err(f'{skill_md}: invalid skill name characters: {name!r}') + + # Duplicate names + if name in skill_names: + err(f'{skill_md}: duplicate skill name: {name!r}') + skill_names.append(name) + + # Description length + if len(desc) > 1024: + err(f'{skill_md}: description exceeds 1024 characters ({len(desc)})') + if len(desc) < 20: + err(f'{skill_md}: description suspiciously short ({len(desc)} chars)') + + # YAML quoting — descriptions with colons must be quoted to avoid YAML parse errors + raw_desc_line = re.search(r'^description:\s*(.+)$', fm, re.M) + if raw_desc_line: + raw_val = raw_desc_line.group(1).strip() + # Check if the value contains a colon followed by a space (YAML mapping indicator) + unquoted_val = raw_val.strip("'\"") + if ': ' in unquoted_val and not (raw_val.startswith("'") or raw_val.startswith('"')): + err(f'{skill_md}: description contains ": " but is not quoted — will break strict YAML parsers (skills.sh)') + + # Required sections + for section_name in ['## Purpose', '## Workflow', '## Done criteria', '## Output contract']: + if section_name not in text: + err(f'{skill_md}: missing section {section_name}') + + # Standalone safety or engineering rules + if '## Standalone safety' not in text and '## Non-negotiable engineering rules' not in text: + err(f'{skill_md}: missing standalone safety or engineering rules section') + +skill_count = len(skill_dirs) +print(f'Found {skill_count} skills') + + +# ─── 2. Manifest Integrity ──────────────────────────────────────────── + +section('Manifest integrity') + +manifest_path = root / 'skills-manifest.json' +if not manifest_path.exists(): + err('skills-manifest.json not found') +else: + try: + manifest = json.loads(manifest_path.read_text(encoding='utf-8')) + except json.JSONDecodeError as e: + err(f'skills-manifest.json: invalid JSON: {e}') + manifest = None + + if manifest: + # skill_count + if manifest.get('skill_count') != skill_count: + err(f'skills-manifest.json: skill_count={manifest.get("skill_count")} but found {skill_count} skills') + + manifest_skills = manifest.get('skills', []) + manifest_names = [s['name'] for s in manifest_skills] + + # No duplicates in manifest + if len(manifest_names) != len(set(manifest_names)): + err('skills-manifest.json: duplicate skill names') + + # Match filesystem + fs_names = set(skill_names) + mf_names = set(manifest_names) + missing = fs_names - mf_names + phantom = mf_names - fs_names + if missing: + err(f'skills-manifest.json: missing skills: {", ".join(sorted(missing))}') + if phantom: + err(f'skills-manifest.json: phantom skills (in manifest but not filesystem): {", ".join(sorted(phantom))}') + + # Category validation + for entry in manifest_skills: + cat = entry.get('category', '') + name = entry.get('name', '') + expected_path = skills_root / cat / name + if not expected_path.exists(): + err(f'skills-manifest.json: category path mismatch for {name}: {cat}/{name} does not exist') + + # Exact count for v1.0.1 + if skill_count != 43: + err(f'Expected exactly 43 skills for v1.0.1, found {skill_count}') + + +# ─── 3. Version Integrity ───────────────────────────────────────────── + +section('Version integrity') + +version_file = root / 'VERSION' +if version_file.exists(): + file_version = version_file.read_text(encoding='utf-8').strip() + if manifest and manifest.get('version') != file_version: + err(f'VERSION ({file_version}) != skills-manifest.json version ({manifest.get("version")})') + print(f'VERSION: {file_version}') +else: + err('VERSION file not found') + + +# ─── 4. Local References ────────────────────────────────────────────── + +section('Local references') + +ref_pattern = re.compile(r'`((?:references|scripts|assets)/[^`]+)`') + +for skill_dir in skill_dirs: + skill_md = skill_dir / 'SKILL.md' + text = skill_md.read_text(encoding='utf-8') + for match in ref_pattern.finditer(text): + ref_path = match.group(1) + # Check if the referenced file exists within the skill directory + full_path = skill_dir / ref_path + if not full_path.exists(): + err(f'{skill_md}: references {ref_path!r} but file does not exist in skill package') + +ref_errors_before = len([e for e in errors if 'does not exist in skill package' in e]) +print(f'Checked portable references ({ref_errors_before} broken)') + + +# ─── 5. Python Script Syntax ────────────────────────────────────────── + +section('Python scripts') + +py_files = list(skills_root.rglob('*.py')) + list((root / 'scripts').rglob('*.py')) +py_ok = 0 +for py_file in py_files: + try: + py_compile.compile(str(py_file), doraise=True) + py_ok += 1 + except py_compile.PyCompileError as e: + err(f'{py_file}: Python syntax error: {e}') + +print(f'{py_ok}/{len(py_files)} Python scripts compile OK') + + +# ─── 6. Eval Cases ──────────────────────────────────────────────────── + +section('Eval cases') + +eval_dir = root / 'evals' / 'cases' +eval_names = [] +if eval_dir.exists(): + for eval_file in sorted(eval_dir.glob('*.json')): + try: + case = json.loads(eval_file.read_text(encoding='utf-8')) + except json.JSONDecodeError as e: + err(f'{eval_file}: invalid JSON: {e}') + continue + + # Required fields + for field in ['name', 'prompt', 'expected_skills']: + if field not in case: + err(f'{eval_file}: missing required field {field!r}') + + name = case.get('name', '') + if name in eval_names: + err(f'{eval_file}: duplicate eval name {name!r}') + eval_names.append(name) + + # Expected skills exist + for skill in case.get('expected_skills', []): + if skill not in skill_names: + err(f'{eval_file}: expected skill {skill!r} does not exist') + + # Assertions + assertions = case.get('assertions', []) + if not isinstance(assertions, list): + err(f'{eval_file}: assertions must be a list') + + # Forbidden patterns + forbidden = case.get('forbidden_patterns', []) + if not isinstance(forbidden, list): + err(f'{eval_file}: forbidden_patterns must be a list') + + print(f'{len(eval_names)} eval cases validated') +else: + print('No eval cases directory found') + + +# ─── 7. Templates ───────────────────────────────────────────────────── + +section('Templates') + +templates_dir = root / 'templates' +if templates_dir.exists(): + # Check expected template dirs + for tpl in ['resource-starter', 'nui-bridge', 'framework-adapter']: + tpl_dir = templates_dir / tpl + if not tpl_dir.exists(): + err(f'templates/{tpl}: directory not found') + + # Check fxmanifest.lua does NOT contain deprecated lua54 + for fxm in templates_dir.rglob('fxmanifest.lua'): + text = fxm.read_text(encoding='utf-8') + if "lua54 'yes'" in text or 'lua54 "yes"' in text or "lua54('yes')" in text: + err(f'{fxm}: contains deprecated lua54 directive') + + # resource-starter checks + starter = templates_dir / 'resource-starter' + if starter.exists(): + if not (starter / 'fxmanifest.lua').exists(): + err('templates/resource-starter: missing fxmanifest.lua') + + # nui-bridge checks + nui = templates_dir / 'nui-bridge' + if nui.exists(): + for expected in ['nui.ts', 'client.lua']: + if not (nui / expected).exists(): + err(f'templates/nui-bridge: missing {expected}') + + print('Template checks complete') +else: + print('No templates directory found') + + +# ─── Summary ────────────────────────────────────────────────────────── + +section('Summary') if errors: - print('\n'.join(errors)) + print(f'\nFAILED: {len(errors)} error(s)\n') + for e in errors: + print(f' ✗ {e}') sys.exit(1) -print(f'OK: {count} skills validated.') +else: + print(f'\nOK: {skill_count} skills validated, {len(py_files)} scripts compiled, {len(eval_names)} evals checked.') + sys.exit(0) diff --git a/skills-manifest.json b/skills-manifest.json index 6346d02..2c4260b 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -1,6 +1,6 @@ { "name": "fivem-agent-skills", - "version": "1.0.0", + "version": "1.0.1", "generated": "2026-08-30", "skill_count": 43, "skills": [ diff --git a/templates/nui-bridge/nui.ts b/templates/nui-bridge/nui.ts index 23314f1..804ee4b 100644 --- a/templates/nui-bridge/nui.ts +++ b/templates/nui-bridge/nui.ts @@ -13,7 +13,29 @@ export async function nuiFetch(event: string, payload: TReq, timeout body: JSON.stringify(payload), signal: controller.signal, }); - return await response.json(); + + if (!response.ok) { + return { ok: false, error: { code: 'http_error', message: `HTTP ${response.status}` } }; + } + + let body: unknown; + try { + body = await response.json(); + } catch { + return { ok: false, error: { code: 'invalid_response', message: 'Response is not valid JSON' } }; + } + + // Validate the response matches the expected NuiResult shape + if (typeof body === 'object' && body !== null && 'ok' in body) { + return body as NuiResult; + } + + return { ok: false, error: { code: 'invalid_response', message: 'Unexpected response shape' } }; + } catch (err: unknown) { + if (err instanceof DOMException && err.name === 'AbortError') { + return { ok: false, error: { code: 'timeout', message: `Request timed out after ${timeoutMs}ms` } }; + } + return { ok: false, error: { code: 'network_error', message: 'Network request failed' } }; } finally { clearTimeout(timer); }