feat: enhance cross-platform subagent adaptation and Codex tool mapping

Author: muhamadgalihsaputra

README.md

@@ -16,11 +16,11 @@ Once it's teased a spec out of the conversation, it shows it to you in chunks sh
 
 After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. 
 
-Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
+Next up, once you say "go", it launches a *subagent-driven-development* process, routing each engineering task through the host's available delegation model while preserving the same review and orchestration workflow. On some hosts this appears as named agent dispatch; on others it is implemented through native subagents using Galyarder role prompts. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
 
 Finally, Galyarder Agent Framework shifts into **Marketing Mode**, triggering skills for SEO, CRO, and Remotion (Video) to ensure what you built actually achieves market fit.
 
-There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Galyarder Agent Framework.
+There's a bunch more to it, but that's the core of the system. The workflow philosophy stays consistent across hosts, while runtime mechanics such as installation, command invocation, and subagent dispatch vary by platform. Once installed correctly for your host, your coding agent can follow the same Galyarder workflow.
 
 ## Sponsorship
 
@@ -32,7 +32,7 @@ Thanks!
 
 ## Installation
 
-Galyarder is a multi-platform plugin system. Installation varies by platform:
+Galyarder is a multi-platform agent framework with host-specific installation and runtime adapters. Installation varies by platform:
 
 ### Claude Code / Copilot CLI
 
@@ -163,6 +163,11 @@ Galyarder Agent Framework provides short-hand commands for rapid execution:
 - **/e2e** - Generate and run end-to-end user journey tests.
 - **/clean** - Remove dead code and refactor for maintainability.
 
+Command UX depends on the host. Some platforms expose these as native slash
+commands or plugin commands, while others map them through host-specific config
+or prompting conventions. Check the platform-specific install docs for the exact
+invocation model.
+
 ### Skills Library
 
 - **Elite Design Collection**: 50+ high-fidelity `DESIGN.md` specifications from industry leaders (Vercel, Stripe, Linear, etc.) located in `rules/design/`.

docs/README.codex.md

@@ -64,6 +64,33 @@ Skills are discovered automatically. Codex activates them when:
 - The task matches a skill's description
 - The `using-galyarder-agent-framework` skill directs Codex to use one
 
+## Subagents and Agent Roles
+
+Codex and Galyarder work together in two layers:
+
+- `skills/` are discovered natively by Codex
+- `agents/*.md` are role definitions, not a native Codex agent registry
+
+When a skill says to dispatch a named agent such as
+`galyarder-agent-framework:code-reviewer`, read that as a cross-platform workflow
+instruction:
+
+1. On hosts with named agent dispatch, use the named agent directly.
+2. On Codex, read the relevant `agents/*.md` file or local prompt template.
+3. Spawn a native Codex subagent with those instructions using `spawn_agent`.
+
+In other words: Codex runs native subagents, while Galyarder supplies the role
+prompt those subagents should follow.
+
+This adaptation layer translates runtime mechanics only. It does not weaken or
+rewrite the framework's core agent constitution. The strict workflow,
+expectations, and foundations defined in `agents/*.md` remain authoritative; the
+Codex adapter is responsible only for mapping those roles onto Codex-native
+subagent capabilities.
+
+For the exact Codex mapping, see
+[`skills/using-galyarder-agent-framework/references/codex-tools.md`](../skills/using-galyarder-agent-framework/references/codex-tools.md).
+
 ### Personal Skills
 
 Create your own skills in `~/.agents/skills/`:

skills/requesting-code-review/SKILL.md

@@ -5,7 +5,13 @@ description: Use when completing tasks, implementing major features, or before m
 
 # Requesting Code Review
 
-Dispatch galyarder-agent-framework:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+Dispatch a code-reviewer subagent to catch issues before they cascade. On hosts
+with named agent dispatch, use `galyarder-agent-framework:code-reviewer`
+directly. On hosts without named agent dispatch, use the platform's native
+subagent mechanism with the reviewer prompt/template. The reviewer gets
+precisely crafted context for evaluation — never your session's history. This
+keeps the reviewer focused on the work product, not your thought process, and
+preserves your own context for continued work.
 
 **Core principle:** Review early, review often.
 
@@ -31,7 +37,12 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 **2. Dispatch code-reviewer subagent:**
 
-Use Task tool with galyarder-agent-framework:code-reviewer type, fill template at `code-reviewer.md`
+Use the host's subagent mechanism and fill the template at
+`requesting-code-review/code-reviewer.md`.
+
+- Hosts with named agent dispatch: use `galyarder-agent-framework:code-reviewer`
+- Hosts without named agent dispatch: read the template, fill placeholders, and
+  dispatch a native subagent with that content
 
 **Placeholders:**
 - `{WHAT_WAS_IMPLEMENTED}` - What you just built
@@ -56,7 +67,7 @@ You: Let me request code review before proceeding.
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[Dispatch galyarder-agent-framework:code-reviewer subagent]
+[Dispatch code-reviewer subagent using the host's native mechanism]
   WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
   PLAN_OR_REQUIREMENTS: Task 2 from docs/galyarder-agent-framework/plans/deployment-plan.md
   BASE_SHA: a7981ec

skills/subagent-driven-development/SKILL.md

@@ -123,6 +123,20 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 - `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
 - `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
 
+## Platform Adaptation
+
+This skill is written in cross-platform terms.
+
+- Hosts with named agent dispatch can call the named agent directly.
+- Hosts without named agent dispatch must translate agent names into native
+  subagent calls using either `agents/*.md` role files or the local prompt
+  templates listed above.
+- On Codex specifically, follow
+  `using-galyarder-agent-framework/references/codex-tools.md`:
+  `Task` means `spawn_agent`, `TodoWrite` means `update_plan`, and named agent
+  references are implemented by spawning a native Codex agent with the filled
+  role prompt.
+
 ## Example Workflow
 
 ```

skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -7,8 +7,10 @@ Use this template when dispatching a code quality reviewer subagent.
 **Only dispatch after spec compliance review passes.**
 
 ```
-Task tool (galyarder-agent-framework:code-reviewer):
-  Use template at requesting-code-review/code-reviewer.md
+Dispatch code-reviewer subagent:
+  On hosts with named agent dispatch, use `galyarder-agent-framework:code-reviewer`
+  On hosts without named agent dispatch, use the native subagent mechanism with
+  the filled template at requesting-code-review/code-reviewer.md
 
   WHAT_WAS_IMPLEMENTED: [from implementer's report]
   PLAN_OR_REQUIREMENTS: Task N from [plan-file]

skills/using-galyarder-agent-framework/references/codex-tools.md

@@ -6,7 +6,7 @@ Skills use Claude Code tool names. When you encounter these in a skill, use your
 |-----------------|------------------|
 | `Task` tool (dispatch subagent) | `spawn_agent` (see [Named agent dispatch](#named-agent-dispatch)) |
 | Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
-| Task returns result | `wait` |
+| Task returns result | `wait_agent` |
 | Task completes automatically | `close_agent` to free slot |
 | `TodoWrite` (task tracking) | `update_plan` |
 | `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
@@ -22,7 +22,7 @@ Add to your Codex config (`~/.codex/config.toml`):
 multi_agent = true
 ```
 
-This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
+This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
 
 ## Named agent dispatch
 
@@ -43,6 +43,26 @@ When a skill says to dispatch a named agent type:
 | `Task tool (galyarder-agent-framework:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content |
 | `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt |
 
+## Cross-platform dispatch rule
+
+Write skills so the workflow is portable:
+
+1. If the host supports named agent dispatch, use the named agent directly.
+2. If the host does not support named agents, treat `agents/*.md` as role prompt
+   sources and dispatch a native subagent with those instructions.
+3. If the skill includes a local prompt template, prefer that template over a
+   generic agent file because it already captures task-specific placeholders.
+
+For Codex specifically, this means:
+- `agents/*.md` are not a runtime registry
+- they are role definitions used to construct `spawn_agent(...)` messages
+- the spawned runtime agent is still one of Codex's built-in agent types
+
+This is an adapter layer, not a policy rewrite. Keep the strict workflow and
+expectations defined by the framework's agent and skill content intact. The
+Codex-specific responsibility is to translate dispatch and tool mechanics into
+Codex-native operations without softening the underlying protocol.
+
 ### Message framing
 
 The `message` parameter is user-level input, not a system prompt. Structure it