gsd-mempalace-recall

name	gsd-mempalace-recall
description	Recall decisions, patterns, and surprises from MemPalace before planning
metadata	{"short-description":"Recall decisions, patterns, and surprises from MemPalace before planning"}

<codex_skill_adapter>

A. Skill Invocation

• This skill is invoked by mentioning $gsd-mempalace-recall.
• Treat all user text after $gsd-mempalace-recall as {{GSD_ARGS}}.
• If no arguments are present, treat {{GSD_ARGS}} as empty.

B. AskUserQuestion → request_user_input Mapping

GSD workflows use AskUserQuestion (Claude Code syntax). Translate to Codex request_user_input:

Parameter mapping:

• header → header
• question → question
• Options formatted as "Label" — description → {label: "Label", description: "description"}
• Generate id from header: lowercase, replace spaces with underscores

Batched calls:

• AskUserQuestion([q1, q2]) → single request_user_input with multiple entries in questions[]

Multi-select workaround:

• Codex has no multiSelect. Use sequential single-selects, or present a numbered freeform list asking the user to enter comma-separated numbers.

Execute mode fallback:

• When request_user_input is rejected or unavailable, activate TEXT_MODE: append --text to {{GSD_ARGS}} so the workflow's built-in text-mode branching takes over. Present every AskUserQuestion call as a plain-text numbered list, then stop and wait for the user's reply. Do NOT pick a default and continue (#3018 / #3808).
• You may only proceed without a user answer when one of these is true: (a) the invocation included an explicit non-interactive flag (--auto or --all), (b) the user has explicitly approved a specific default for this question, or (c) the workflow's documented contract says defaults are safe (e.g. autonomous lifecycle paths).
• Do NOT write workflow artifacts (CONTEXT.md, DISCUSSION-LOG.md, PLAN.md, checkpoint files) until the user has answered the plain-text questions or one of (a)-(c) above applies. Surfacing the questions and waiting is the correct response — silently defaulting and writing artifacts is the #3018 failure mode.

C. Task() → spawn_agent Mapping

GSD workflows use Task(...) (Claude Code syntax). Translate to Codex collaboration tools:

Schema detection (required first step): Codex exposes two spawn_agent schemas:

• agent_type-capable schema (e.g. multi_agent_v2): spawn_agent accepts agent_type, message, reasoning_effort, fork_context, etc. — typed GSD agent dispatch is available.
• Generic schema (multi_agent_v1): spawn_agent accepts only message, items, fork_context — there is no agent_type field. Typed GSD agent dispatch is unavailable in this session.

Before spawning, inspect the spawn_agent tool's visible parameter schema (via tool_search or the tool list) to determine which form is active.

Typed mapping (agent_type-capable schema only):

• Task(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y")
• Agent(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y")
• Task(model="...") → omit. spawn_agent has no inline model parameter; GSD embeds the resolved per-agent model directly into each agent's .toml at install time so model_overrides from .planning/config.json and ~/.gsd/defaults.json are honored automatically by Codex's agent router.
• Resolved reasoning_effort="low|medium|high|xhigh" (xhigh is a GSD/Codex tier, not a generic runtime enum) → pass reasoning_effort to spawn_agent when the runtime/tool supports it. Omit missing, empty, inherited, or unsupported values; do not invent one-off effort literals in workflow prose.
• fork_context: false by default — GSD agents load their own context via <files_to_read> blocks
• Task(isolation="worktree") / Agent(isolation="worktree") → no direct Codex mapping. Codex spawn_agent does not create or bind a git worktree automatically. Workflows that require this isolation must fail closed or use an explicit manual worktree protocol before spawning (#3360).

Generic-agent workaround (multi_agent_v1 schema — NO agent_type field): When only the generic multi_agent_v1 schema is available, typed GSD agent dispatch (gsd-planner, gsd-executor, etc.) is NOT possible. This is a known Codex limitation (openai/codex#15250). This workaround is NOT equivalent to typed gsd-planner/gsd-executor execution — GSD agents carry project-aware prompts, audit logging, and workflow context that a generic subagent lacks. Use the following fallback:

1. Resolve your active Codex config root — the directory that contains your config.toml. This directory is determined in priority order: $CODEX_HOME (if set), the path given by --config-dir (if passed on invocation), a local .codex directory in the current project (if --local was used), or the default global config directory. Read agents/<agent-name>.toml relative to that config root to extract the agent's system instructions.
2. Inject those instructions as a role-preamble into a generic spawn_agent(message=...) call.
3. Label results and logs clearly as "generic-agent workaround" so the orchestrator and user know full typed-agent guarantees are not in effect.
4. Where typed dispatch is mandatory for correctness (e.g. worktree isolation), fail closed and report the schema limitation rather than silently degrading.

Spawn restriction:

• Codex restricts spawn_agent to cases where the user has explicitly requested sub-agents. When automatic spawning is not permitted, do the work inline in the current agent rather than attempting to force a spawn.
• In some Codex sessions, multi-agent tooling can be deferred. If spawn_agent is not currently visible, discover tools first via tool_search before defaulting to inline execution.

Parallel fan-out:

• Spawn multiple agents → collect agent IDs → wait(ids) for all to complete

Result parsing:

• Look for structured markers in agent output: CHECKPOINT, PLAN COMPLETE, SUMMARY, etc.
• close_agent(id) after collecting results from each agent </codex_skill_adapter>

STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.

Step 0 -- Banner

Before ANY tool calls, display this banner:

GSD > MEMPALACE RECALL

Then proceed to Step 1.

Step 1 -- Config Gate

Check whether the MemPalace capability is enabled by reading .planning/config.json directly with the Read tool.

DO NOT use node "$HOME/.codex/gsd-core/bin/gsd-tools.cjs" config get-value -- it hard-exits on missing keys.

1. Read .planning/config.json with the Read tool.
2. If the file does not exist: write the "unavailable" stub (Step 4) and STOP.
3. Parse the JSON. Proceed to Step 2 only if config.mempalace && config.mempalace.enabled === true and config.mempalace.recall_on_plan !== false. Otherwise display the disabled message and STOP (recall_on_plan: false turns plan-time recall off while leaving the rest of the capability enabled).

Disabled message:

GSD > MEMPALACE RECALL

MemPalace memory is disabled. To activate:

  node <runtime-home>/gsd-core/bin/gsd-tools.cjs config-set mempalace.enabled true

Recall is opt-in; the loop proceeds normally without it.

This step is onError: skip at plan:pre -- recall never blocks planning.

Step 2 -- Resolve wing, mode, and transport

1. Wing. Use config.mempalace.wing if non-empty; otherwise derive from config.project_code; otherwise fall back to the repository directory name.
2. Mode. Read config.mempalace.memory_mode (augment | kg_backend | replace, default augment). Only augment is wired today, so recall always treats the palace as additive; kg_backend/replace are forward-declared and behave as augment.
3. Transport. Prefer the MCP tools (mempalace_*) in interactive runs when your MemPalace MCP server is registered and your runtime permits those tools. Otherwise — headless/cron/autonomous runs, or runtimes that don't grant the MemPalace MCP tools — use the CLI (mempalace wake-up, mempalace search), which this skill's Bash allow-tool always covers. If neither is reachable, go to Step 4.
4. Topic. Read the phase CONTEXT.md (the consumed artifact). Derive a short search query from its title, goal, and key decisions.

Step 3 -- Retrieve (read-only)

All calls in this step are side-effect-free. On any error or timeout, stop retrieving and write whatever was gathered (or the stub) -- never raise.

1. Wake up (cheap, ~600--900 tokens):
   • Interactive: read the wing identity/summary, then mempalace_search.
   • Headless: mempalace wake-up --wing <wing>.
2. Targeted search:
   • Interactive: mempalace_search(query=<topic>, wing=<wing>).
   • Headless: mempalace search "<topic>" --wing <wing>.
3. Knowledge-graph facts (when config.mempalace.mirror_kg is true): mempalace_kg_query / mempalace_kg_timeline for decisions relevant to the topic and their validity windows. Only augment is currently wired, so the palace KG supplements GSD's native .planning/graphs/ — do not treat it as the sole source. (kg_backend/replace are forward-declared and behave as augment today.)
4. Dedup the returned drawers/facts; keep the top results.

Step 4 -- Write MEMORY-RECALL.md

Write MEMORY-RECALL.md in the current phase directory. The planner consumes it.

When recall succeeded, structure it as:

# Memory Recall (MemPalace)

_Wing: <wing> · Mode: <mode> · Transport: <mcp|cli>_

## Prior decisions
- <decision> — <provenance: drawer id / kg fact, valid_from>

## Patterns
- <pattern> — <provenance>

## Surprises / gotchas
- <surprise> — <provenance>

When MemPalace is unreachable, write the stub and continue:

# Memory Recall (MemPalace)

_MemPalace unavailable at recall time — proceeding without recalled memory._

Anti-Patterns

1. DO NOT let any MemPalace error fail the step -- recall is onError: skip.
2. DO NOT write to the palace from this skill -- recall is read-only; capture is a separate skill.
3. DO NOT paste raw search output into the file -- distil to decisions/patterns/surprises with provenance.
4. DO NOT skip the config gate.