Skip to content

PLATFORM_SPEC.md — gald3r (native harness)

gald3r itself — a user driving gald3r run / gald3r chat directly as their harness, without any external IDE/agent tool in front of it. Today the platform roster has 37 EXTERNAL targets (Claude Code, Cursor, Codex, ...) and gald3r is the one harness NOT on its own roster: run/chat load CRASH from the compiled binary (gald3r_engine/crash) but expose no user-extensible overlay the way an installed .claude//.cursor/ tree does for those platforms. This work makes gald3r the 38th roster entry, closing that strange loop.

Authoring path: NEW. There is no prior spec for this platform — it did not exist on the roster before this. Unlike every other spec in this tree, docs_url is internal: there is no external product page to crawl: the "documentation" IS this repo's own source (gald3r_engine/, gald3r_platforms/) and the task's own Agent/Status History record. crawl_max_age_days: 0 signals "not a live-docs-crawl candidate" rather than "always stale" — @g-platform-scan-docs has nothing external to re-check here.

Status: ❌ across the board — by decision, not by absence of a mechanism. This is the gald3r/astrbot distinction from subq's ❌: subq has no native surface of its own, ever (a plugin, host owns everything). gald3r has a real, already-built runtime surface — see §3–8 below — but WHERE that surface should be exposed as a user-extensible overlay (root dirs vs .gald3r/platform/) is an explicit open owner decision this task's own description defers to Friday ratification (owner ask, 2026-08-12). Filling in a guessed placement here would repeat the exact mistake layout_map.yaml's own header exists to prevent ("a missing LayoutMap entry is an explicit gap, never a silent guessed placement") — so every cell below stays ❌ until that ratification happens and a follow-up task wires the runtime.

1. Folder Hierarchy

Status: ❓ undecided — the Friday ratification question itself.

Two candidate overlay locations, both structurally viable today:

Option Shape Tradeoffs
A. Root dirs (mirrors every other platform) A gald3r-specific dot-directory tree at the project root, e.g. .gald3r-agent/{commands,rules,hooks,agents,skills}/, sibling to .claude//.cursor//etc. For: identical shape to every other layout_map.yaml entry — generate_overlay needs zero special-casing, CheckPlatformSpec/ResolveSpecPath/GenerateOverlay all already work generically over dir/file layout entries. Against: gald3r already owns .gald3r/ at the project root for coordination state (tasks/bugs/plans) — a second dot-directory reads as two competing "the gald3r folder" concepts to a new user, and risks the exact ambiguous-naming collision g-rl-42 warns about.
B. Nested under .gald3r/platform/ .gald3r/platform/{commands,rules,hooks,agents,skills}/, inside the SAME folder gald3r already writes coordination state to. For: one folder, one mental model — "everything gald3r-owned is under .gald3r/" (matches this repo's own g-rl-33 doctrine that .gald3r/ is the coordination surface of record). No new dot-directory to explain. Against: .gald3r/ is already governed by the .gald3r/ Folder Gate (agent-selection required before any read/write) and the .gald3r/ Gitignore Gate (controller/WPAC repos must NOT gitignore it) — a platform overlay living inside it inherits those gates whether or not they make sense for "my personal hook scripts", and a controller/WPAC repo's .gald3r/ is coordination-owned board state, not a place individual contributors expect to drop their own commands/rules.

No default is asserted here. layout_map.yaml's gald3r: {} entry stays empty (§ this file's own header) until one of these is ratified.

<project-root>/
└── (no gald3r-native overlay tree yet -- pending ratification, see table above)

2. AI Instruction File

Status: ❌ not yet wired, same reasoning as §1: root_instructions in layout_map.yaml needs a file: target, and that target's location is gated on the same overlay-location decision. Once ratified, gald3r's own generic AGENTS.md template (the same package-embedded body every other root_instructions platform already emits, per layout_map.yaml's own root_instructions documentation) is the obvious candidate — gald3r has no reason to invent a second convention here.

3. Agents Support — ❌ not yet wired (execution layer exists: the recursive agent primitive)

  • What already exists: gald3r_engine/agent is the harness's own agent-loop package (act_halting.go, context.go, ...) — the runtime that runs a session at all. The recursive agent primitive is the layer that makes a subagent invocation possible from inside that loop — i.e. the mechanism a g-agnt-*.md persona would actually execute through, the same way Claude Code's Agent tool or Cursor's subagent dispatch does today.
  • What's missing: a rendered agents: overlay location (§1) PLUS the actual wiring from a discovered g-agnt-*.md persona file to a recursive-agent invocation. Neither exists yet. This depends on the recursive agent primitive landing first — do not build a parallel, competing agent-dispatch mechanism here.
  • Relationship: the recursive agent primitive is the execution primitive; this platform's agents: layout entry is the discovery/placement convention that would point at personas for it to run. Two different, sequenced pieces of work.

4. Skills Support — ❌ not yet wired

  • gald3r already has a skill-authoring convention (g-skl-*/SKILL.md, this very file's sibling) and a skill-pack install mechanism (g-skill-pack-add et al.) for EXTERNAL platforms. Making gald3r itself a skill-consuming platform means deciding whether gald3r chat reads SKILL.md frontmatter/discovery the same way, and from where (§1). Lower priority than hooks/commands per the owner's suggested sequencing (§9) — no runtime skill-discovery loader exists in gald3r_engine today.

5. Commands / Workflows — ❌ not yet wired (dispatch exists: chat verb dispatch)

  • What already exists: gald3r chat already dispatches slash-style verbs inside a chat session ("chat verb dispatch exists"). This is the SAME class of mechanism a @g-*//g-* command needs to hook into.
  • What's missing: a rendered commands: overlay location (§1) that projects g-*.md/g-command-new-authored command files into something the existing chat-verb dispatcher actually discovers and routes to. The dispatcher itself is not gated on the ratification — only the "where do USER-authored command files live on disk" question is.
  • Named by the owner as one of the two components to wire first (§9), alongside hooks, because this runtime hook already exists and needs the least new engine work.

6. Hooks System — ❌ not yet wired (engine events exist: gald3r_engine/hooks + stream)

  • What already exists: gald3r_engine/hooks is the native lifecycle hook system — session/compact/tool-use events already fire user-configured command/http/llm_prompt hooks, optionally blocking the guarded operation on failure (see that package's own doc comment). gald3r_engine/stream independently folds the harness's fine-grained event stream into render-ready blocks (text/reasoning/tool_group/error/lifecycle) tagged with agent/depth/turn — hook-shaped events per the stream protocol.
  • What's missing: gald3r_engine/hooks' loader currently reads hook CONFIG from wherever the engine's own caller points it (not yet a platform-overlay convention), and there is no hooks: layout_map.yaml entry projecting g-hk-*.py-style neutral hook scripts into that loader's discovery path. Named by the owner as one of the two components to wire first (§9) — the mechanism to hang a hooks: layout entry off of is the closest to "already built" of every component type here.

7. Rules / Memory — ❌ not yet wired

  • gald3r has no system-prompt-injection convention today for user-authored g-rl-*.md rule files the way Claude Code's .claude/rules/ or Cursor's .cursor/rules/ do. This needs new engine work (a rules-injection point in the session/context-assembly path, gald3r_engine/contextassembly is the closest existing package) beyond the ratification question alone — lowest priority per the owner's suggested sequencing (§9).

8. MCP Support — ❌ not applicable in the usual sense

  • gald3r-the-harness is not itself an MCP client target the way an IDE is (a user's own MCP servers are configured for whatever harness they run, and gald3r_mcp/gald3r_sdk_plugins already exist as gald3r's own MCP-adjacent packages for other purposes). This cell tracks "does a gald3r-platform overlay register an MCP server the same way other platforms' mcp: layout entries do" — undecided, not prioritized in the owner's suggested first wave (§9).

9. Owner's Suggested Sequencing

"which components the runtime can actually honor first (suggest hooks + commands first -- engine events exist, chat verb dispatch exists)"

Ranked by "how much of the runtime seam already exists, independent of the ratification question":

  1. Hooks — gald3r_engine/hooks + gald3r_engine/stream already exist; needs a hooks: layout entry projecting scripts into the existing loader, once §1 is ratified.
  2. Commands — chat verb dispatch already exists; needs a commands: layout entry projecting g-*.md files into the existing dispatcher, once §1 is ratified.
  3. CRASH folders — gald3r_engine/crash already loads CRASH from the compiled binary; extending it to also load a user overlay is a natural next step once §1 lands, since the mechanism (dispatch/activation) already exists.
  4. Agents — blocked on the recursive-agent execution primitive landing; the agents: layout entry alone does not make subagents runnable.
  5. Rules — needs new context-assembly injection work beyond the ratification question.
  6. Skills — lowest priority; no runtime skill-discovery loader exists yet.

10. Relationship to the Self-Coordinator Provider and the Recursive Agent Primitive

  • The self-coordinator provider — a different feature with the same self-hosting theme as this one: gald3r acting as its own coordinator/provider. This platform work is about gald3r users getting the CRASH/Commands/Rules/Agents/Skills/Hooks component surface; the self-coordinator provider is about gald3r coordinating itself as a provider. Related in spirit, not a dependency in either direction as currently scoped — flag for the owner if Friday's ratification reveals a real shared mechanism (e.g. both wanting the same overlay-location decision).
  • The recursive agent primitive — a real dependency for §3 (Agents Support) only: it is the execution layer a discovered g-agnt-*.md persona would run through. Every other component (hooks, commands, rules, skills, CRASH) is independent of it.

Atypical Handling

  • No external docs to crawl. Unlike every other platform in this roster, gald3r's own "documentation" is its own source tree + this task's Agent/Status History. @g-platform-scan-docs gald3r has nothing external to diff against — re-verification here means re-reading gald3r_engine/{hooks,stream,crash,agent} for drift, not re-crawling a URL.
  • layout_map.yaml entry stays gald3r: {} (deliberately empty, mirroring subq's precedent) until the Friday ratification lands. Do not fill it in speculatively.

gald3r Integration Notes

  • There is nothing to "install" for this platform in the usual gald3r platform install --platform gald3r sense yet — the compiled binary already ships CRASH natively for run/ chat; what's missing is the user-EXTENSIBLE overlay this spec is scoping.
  • Once §1 is ratified, follow-up implementation work should land a real layout_map.yaml hooks: and commands: entry (per §9's sequencing), then extend selftest.CheckPlatformSpec and this repo's roster-driven test suite the same way every other platform's real entries are already covered (see gald3r_platforms/generate/hooks_roster_test.go for the pattern every JSON-hooks-shaped platform already goes through).

Capability Summary

Hooks Rules Skills Commands MCP Docs Fresh
❌ ❌ ❌ ❌ ❌ ✅

Legend: ✅ verified working · ⚠️ partial / Cursor-generic · ❌ not supported yet · ❓ untested.

Overall platform status: ❌ — honest, decision-gated, not fabricated. gald3r has real runtime seams for hooks and commands (§6, §5) and a real execution-primitive dependency for agents (§3) — none are wired to a user-extensible overlay yet because WHERE that overlay lives (§1) is an explicit open owner decision, not an oversight.

Verification Evidence (internal source read, 2026-08-22)

Capability How verified
Roster today is 37, not 38 gald3r_platforms/registry/registry.go FallbackPlatforms (before this spec) enumerated exactly 37 canonical names
Hook events exist gald3r_engine/hooks/doc.go — native lifecycle hook system (session/compact/tool-use)
Stream protocol exists gald3r_engine/stream/doc.go — folds harness event stream into render-ready blocks tagged agent/depth/turn
CRASH loads from compiled binary gald3r_engine/crash/cli_dispatch.go — RecordActivation/DispatchLoad/dispatch.BuildDefaultEngine
Chat verb dispatch exists owner-asserted 2026-08-12; not independently re-verified by this session (out of this session's declared scope)
The recursive agent primitive is the agents execution layer this spec's own framing: "agents (subagent personas via the recursive primitive)"
No prior layout_map.yaml/roster entry for gald3r git log on gald3r_platforms/assets/layout_map.yaml / registry.go before this task's commit

Reference page — canonical source: g-skl-platform-gald3r/PLATFORM_SPEC.md in the engine repo, generated by scripts/generate_platform_support_docs.py. Pages marked curated are hand-assessed and not yet live-verified.