Gpd Map Research

Each agent has fresh context, explores a specific focus area, and writes documents directly. The orchestrator only receives confirmation + line counts, then writes a summary.

Output: .gpd/research-map/ folder with 7 structured documents covering theoretical content, computational methods, data artifacts, conventions, and open questions. </purpose>

Document quality over length: Include enough detail to be useful as reference. Prioritize practical examples (key equations, code patterns, data formats) over arbitrary brevity.

Document templates: Mapper agents load templates from ./.codex/get-physics-done/references/templates/research-mapper/ (FORMALISM.md, CONVENTIONS.md, CONCERNS.md, etc.). These paths are deterministic across runtimes after install; if they are missing, treat that as a broken install and fall back to the agent's built-in structural guidance rather than searching alternate runtime-specific locations.

Always include file paths: Documents are reference material for the AI when planning/executing. Always include actual file paths formatted with backticks: src/hamiltonian.py, notebooks/convergence_test.ipynb, latex/main.tex.

Map all project artifacts: A physics research project typically contains:

• Theoretical derivations (LaTeX, markdown, handwritten-note scans)
• Computational code (Python, Julia, C++, Fortran scripts and libraries)
• Data files (HDF5, CSV, NumPy arrays, simulation outputs)
• Notebooks (Jupyter/Mathematica/Maple for exploratory calculations)
• Figures and plots (generated or hand-drawn)
• Configuration files (input decks, parameter files, job scripts)
• References (BibTeX, downloaded papers, annotated PDFs) </philosophy>

# Research-mapping initialization.
INIT=$(/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init map-research)
if [ $? -ne 0 ]; then
  echo "ERROR: gpd initialization failed: $INIT"
  # STOP — display the error to the user and do not proceed.
fi

Extract from init JSON: mapper_model, commit_docs, research_map_dir, existing_maps, has_maps, research_map_dir_exists, project_contract, contract_intake, effective_reference_intake, active_reference_context, reference_artifacts_content.

Read mode settings:

RESEARCH_MODE=$(/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw config get research_mode 2>/dev/null | /home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .value --default balanced 2>/dev/null || echo "balanced")

Mode-aware behavior:

• research_mode=explore: Map broadly — include alternative theoretical frameworks, speculative connections, open questions across related domains.
• research_mode=exploit: Map narrowly — focus on primary formalism, established results, direct computational needs.
• research_mode=adaptive: Start with primary framework, expand mapping if connections to other domains appear.
• Regardless of mode, do not drop contract-critical anchors, prior baselines, or user-mandated references.
• Treat effective_reference_intake as the machine-readable carry-forward registry for anchors, prior outputs, baselines, and unresolved gaps. Use active_reference_context to render and explain it, not to replace it.
• Use reference_artifacts_content when the existing literature/research-map artifacts already contain stable citations, prior-output paths, or benchmark wording that should be preserved verbatim.
• Preserve stable anchor identity when you rewrite or merge references: every durable anchor in REFERENCES.md should carry a reusable Anchor ID and a concrete Source / Locator.
• Keep workflow carry-forward scope separate from canonical contract subject linkage. Carry Forward To names workflow stages; if exact claim/deliverable IDs are known, record them in a dedicated Contract Subject IDs field instead of overloading the stage field. </step>

If research_map_dir_exists is true:

ls -la .gpd/research-map/

If exists:

.gpd/research-map/ already exists with these documents:
[List files found]

What's next?
1. Refresh - Delete existing and remap research project
2. Update - Keep existing, only update specific documents
3. Skip - Use existing research map as-is

Wait for user response.

If "Refresh": Delete .gpd/research-map/, continue to create_structure If "Update": Ask which documents to update, continue to spawn_agents (filtered) If "Skip": Exit workflow

If doesn't exist: Continue to create_structure. </step>

mkdir -p .gpd/research-map

Expected output files:

• FORMALISM.md (from theory mapper)
• REFERENCES.md (from theory mapper)
• ARCHITECTURE.md (from computation mapper)
• STRUCTURE.md (from computation mapper)
• CONVENTIONS.md (from methodology mapper)
• VALIDATION.md (from methodology mapper)
• CONCERNS.md (from status mapper)

Continue to spawn_agents. </step>

Use task tool with subagent_type="gpd-research-mapper", model="{mapper_model}", readonly=false, and run_in_background=true for parallel execution.

Runtime delegation: Spawn a subagent for the task below. Adapt the task() call to your runtime's agent spawning mechanism. If model resolves to null or an empty string, omit it so the runtime uses its default model. Always pass readonly=false for file-producing agents. If subagent spawning is unavailable, execute these steps sequentially in the main context.

CRITICAL: Use the dedicated gpd-research-mapper agent, NOT Explore. The mapper agent writes documents directly.

Agent 1: Theory Focus

task tool parameters:

subagent_type="gpd-research-mapper"