@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/execute-task.md

@@ -0,0 +1,292 @@
+---
+description: "Execute a specific research task or the entire workflow"
+argument-hint: "[task number N, or 'all' for full workflow]"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<clio_dispatch>
+Select the named recipe with dispatch({agent:"materio-...", task:"assignment with
+full context and exact permitted outputs", intent:{write_roots:["exact/output"]}}).
+Replace the illustrative recipe/path with those stated in this command. Use the
+registered dispatch fields shown here.
+Read the recipe's bound skill references and inline required templates, domain
+sections, answers and selected state into the worker task. Each dispatch starts
+fresh: re-dispatch with the full original context, prior candidates/outputs and
+the new selection, corrections, revisions or resume answer. Use monitor if the
+returned run is still active. Do not infer a resumed transcript from a run ID.
+Honor admission refusals instead of broadening write scope.
+
+Agent returns are mutation-report JSON. Route on the beginning of summary using
+the status branches below. For checkpoints, distinguish
+`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, and `needs_input: checkpoint:human-verify`;
+ask the exact question(s), collect the answer and re-dispatch. No new top-level
+status fields are allowed. A conforming JSON result is not proof of completion.
+After EVERY dispatch that wrote, use ls and read on every reported output and on
+the command's required files, including loop_back and partial checkpoint returns.
+Verify nonempty content and the promised changes before presenting success or
+continuing; re-dispatch with any missing/incorrect file named. Treat actual failed
+validation or execution as failure even when summary claims completion.
+</clio_dispatch>
+
+<execution_context>
+@.research/WORKFLOW.md
+@.research/RESEARCH.md
+@.research/LITERATURE.md
+@.research/STATE.md
+@.research/config.json
+</execution_context>
+
+<objective>
+Execute a specific research task (or the full workflow sequentially) by spawning the task executor with the task's type and context. Verifies outputs on disk, runs advisory guardrails, updates task status, and creates outputs in .research/tasks/task-NN/.
+
+**Orchestrator role:** Resolve target task, check dependencies, gate-confirm assumptions, spawn materio-task-executor with full task context, verify outputs exist, run guardrails and surface findings, update WORKFLOW.md and STATE.md, checkpoint, record.
+
+**Why subagent:** Each task type (literature, computational, data-analysis, experimental-protocol) requires different reasoning depth. Fresh context per task = focused execution. The executor never asks the researcher anything; checkpoints come back here.
+</objective>
+
+<context>
+Target: $ARGUMENTS (task number, or "all")
+</context>
+
+<process>
+
+Worker write scope: the selected .research/tasks/task-NN/; include .research/LITERATURE.md only for an approved literature update.
+
+
+The optional v4 fleet requires an existing Git worktree for its write boundary.
+Check that prerequisite read-only if considering the fleet. In a fresh research
+folder use direct dispatch: run the registered task-executor with only the exact
+selected task output grant, then run the registered read-only task-verifier with
+no write grant. Do not initialize git or weaken a boundary to enable the fleet.
+The direct path below remains available without a repository.
+
+## 1. Inspect Supplied Materials First
+
+Use ls on `.research/data/` and read `.research/DATA-INDEX.md` before other
+research inputs. For literature tasks, inspect these registered materials before
+fetching anything. Clio has no web search tool: build literature work from
+supplied materials plus specific researcher-provided URLs. Request URLs with the
+task confirmation if more coverage is needed. Honor web_search false by staying
+with supplied materials and record coverage in Sources Reviewed in each summary
+and any LITERATURE.md update.
+
+### Validate Environment
+
+```bash
+test -f .research/WORKFLOW.md || echo "ERROR: No WORKFLOW.md. Run /materio:define-research-tasks first."
+cat .research/WORKFLOW.md
+cat .research/STATE.md 2>/dev/null
+cat .research/DATA-INDEX.md 2>/dev/null
+python3 "${component:script:research-state}" config
+```
+
+## 2. Resolve Target Task
+
+**If $ARGUMENTS is empty:** Run `python3 "${component:script:research-state}" next-task`.
+Use its actual dependency-ready pending/in-progress task ID in workflow order.
+If id is null, show the blocked dependencies or that no pending task is ready;
+do not invent a task number. Preserve the task confirmation and assumption gate.
+
+**If $ARGUMENTS = "all":** Resolve the next eligible task with the same next-task helper after each completed task; preserve all interview/checkpoint gates.
+
+**If $ARGUMENTS = number:** Find that specific task. Verify status and dependencies.
+
+Always derive the two-digit form and the output directory:
+```bash
+# Bind N to the validated decimal task number in this call.
+NN=$(printf '%02d' "$((10#$N))"); OUT=".research/tasks/task-$NN"; echo "$OUT"
+# Validate the actual active workflow IDs before creating their directories.
+python3 "${component:script:research-state}" task-dirs
+```
+
+**Dependency check:** If the target task has `Dependencies: Task XX`, verify Task XX is `☑ complete`. If not:
+- Warn the user: "Task [N] depends on Task [XX] which is not complete."
+- Ask via ask_user: proceed anyway, or execute Task XX first?
+
+## 3. Show Task Summary
+
+Display the target task entry from WORKFLOW.md:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Task [NN]: [name]
+ Type:     [literature | computational | experimental | data-analysis | analytical | writing]
+ Inputs:   [what's needed]
+ Outputs:  [what this produces]
+ Assumptions: [list]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 4. Gate Check; Confirm Before Executing
+
+Use ask_user:
+- header: "Execute Task [NN]: [name]"
+- question: "Ready to execute this task?\n\n**Assumptions being made:**\n[list assumptions, marking any planner defaults not yet confirmed]\n\n**Expected output:**\n[expected outputs]\n\nAny assumptions wrong or missing data?"
+- options: "Proceed" | "Update assumptions first" | "I need to upload data first; /materio:upload-data" | "Skip this task"
+
+If assumptions are updated, write them back to the task entry in WORKFLOW.md before spawning.
+
+## 5. Handle Task Type Routing
+
+**If type = `writing`:**
+- Tell user: "This task involves writing. Use `/materio:wtfp` to bridge into wtf-p for paper writing."
+- Exit gracefully.
+
+**If type = `experimental`:** protocol-generation mode → protocol document + data recording template + checklist
+
+**If type = `literature`:** supplied-corpus and provided-URL review mode → summary + BibTeX + LITERATURE.md updates; supplied materials first, provided-URL fetching only if allowed
+
+**If type = `computational`:** script-generation mode → input files + submission script + analysis script + README
+
+**If type = `data-analysis`:** check for registered data in DATA-INDEX.md and `.research/data/`; if none, stop and offer `/materio:upload-data` → analysis code + results summary + figure descriptions
+
+**If type = `analytical`:** theoretical mode → derivation, validation, optional implementation
+
+## 6. Spawn materio-task-executor Agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► EXECUTING TASK [NN]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use dispatch with `agent: "materio-task-executor"` and a task containing the assignment and full context. The prompt carries:
+- `<task>`; full task entry from WORKFLOW.md (with any updated assumptions)
+- `<research>`; full RESEARCH.md
+- `<literature>`; relevant LITERATURE.md sections
+- `<virtual_lab>`; the relevant equipment and software rows from VIRTUAL-LAB.md, if it exists
+- `<prior_outputs>`; outputs from dependency tasks (paths and SUMMARY.md contents)
+- `<data_files>`; DATA-INDEX.md entries and paths under `.research/data/`
+- `<web_allowed>`; true only when config permits URL fetching and web_fetch is available
+- `<provided_urls>`; the researcher's specific URLs, or none
+- `<output_dir>`; `.research/tasks/task-[NN]/`
+
+## 7. Handle Executor Return
+
+**`task_complete:`:**
+
+1. Use ls and read on every reported output and task-NN-SUMMARY.md. Verify outputs on disk. Self-report is not completion:
+   ```bash
+   ls -la .research/tasks/task-[NN]/
+   test -s .research/tasks/task-[NN]/task-[NN]-SUMMARY.md && echo "SUMMARY OK" || echo "ERROR: no summary"
+   ```
+   Every file the executor listed under Outputs must exist and be non-empty. If any is missing, re-dispatch the agent naming the missing file; do not mark the task complete.
+
+1b. Dispatch `materio-task-verifier` separately with the approved
+   task entry, assumptions, dependency context, actual output inventory and summary.
+   Its recipe is read-only; grant no write roots. Inspect its receipt and resolve
+   any decision, human-action, or human-verify checkpoint with the researcher.
+   Treat read/ls findings as artifact review, not command-backed scientific
+   validation. Preserve host grounding diagnostics and stop on a rejected receipt
+   without claiming completion; the advisory commands below have separate evidence.
+
+2. Advisory guardrails. Run what applies, read the findings and exit status, and surface them; nothing here deletes or rewrites on its own. Record a skipped check if a script or python3 is missing.
+   Use bash to collect only existing files and keep stderr visible. The scripts
+   accept files, not directory arguments; never mistake a skipped file for a
+   successful scan. All findings remain advisory. Run these shell blocks only
+   after deriving OUT as the selected task directory:
+   ```bash
+   if command -v python3 >/dev/null 2>&1; then
+     shopt -s nullglob globstar
+     physics_files=("$OUT"/**/*.md)
+     citation_files=("$OUT"/**/*.bib "$OUT"/**/*summary*.md "$OUT"/**/*SUMMARY*.md)
+     script_files=("$OUT"/**/*.py "$OUT"/**/*.sh)
+     citation_flags=()
+     [ "$(python3 "${component:script:research-state}" config --key web_search)" = true ] || citation_flags=(--offline)
+     if ((${#physics_files[@]})); then
+       if python3 "${pluginRoot}/assets/scripts/check_physics.py" "${physics_files[@]}"; then echo "CHECK EXIT: 0"; else echo "CHECK EXIT: $? (findings or incomplete coverage)"; fi
+     else echo "CHECK SKIPPED: no applicable files"; fi
+     if ((${#citation_files[@]})); then
+       if python3 "${pluginRoot}/assets/scripts/verify_citations.py" "${citation_flags[@]}" "${citation_files[@]}"; then echo "CHECK EXIT: 0"; else echo "CHECK EXIT: $? (findings or incomplete coverage)"; fi
+     else echo "CHECK SKIPPED: no applicable files"; fi
+     if ((${#script_files[@]})); then
+       if python3 "${pluginRoot}/assets/scripts/check_scripts.py" "${script_files[@]}"; then echo "CHECK EXIT: 0"; else echo "CHECK EXIT: $? (findings or incomplete coverage)"; fi
+     else echo "CHECK SKIPPED: no applicable files"; fi
+   fi
+   ```
+   Include any other actual reference-list files in citation_files after reading
+   them. If a literature task updated `.research/LITERATURE.md`, read it back and
+   include it in citation_files too. A nonzero checker exit records findings;
+   it never authorizes deletion, edits or an automatic task rejection.
+   If any finding is **IMPOSSIBLE** (physics), **NOT_FOUND** / **MISMATCH** (citations), or **WILL NOT RUN** (scripts): show the findings to the researcher and ask via ask_user:
+   - header: "Guardrail Findings; Task [NN]"
+   - question: "[N] findings:\n\n1. [file:line] [finding] → [suggested fix or closest Crossref match]\n2. ...\n\nHow should I handle them?"
+   - options: "Fix them; resume the executor" | "They're fine; note and continue" | "I'll decide per finding"
+   Re-dispatch the executor with the accepted fixes when asked, then read all changed files back and rerun the applicable advisory checks before completing. Warnings (IMPLAUSIBLE, UNVERIFIABLE, SUSPECT) are listed in the completion output and noted in the task SUMMARY, not gated.
+
+3. After the researcher has resolved every gated finding and the outputs have been read back, mark task as `☑ complete` in WORKFLOW.md. Update STATE.md: current task = next pending, last completed = [NN].
+
+4. Checkpoint if `auto_checkpoint` is true (default):
+   ```bash
+   if [ "$(python3 "${component:script:research-state}" config --key auto_checkpoint)" = true ]; then
+  python3 "${component:script:research-state}" checkpoint save after-task-NN
+fi
+   ```
+
+5. Optional git record:
+   ```bash
+   python3 "${component:script:research-state}" record --message "research(task-[NN]): [task name]; complete" --files "${CHANGED_FILES[@]}"
+   ```
+
+**`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, or `needs_input: checkpoint:human-verify`:**
+- Present what's needed (data, decision, domain knowledge) via ask_user
+- Re-dispatch the executor with a `<resume>` block containing the answer (or re-spawn with the full context plus `<resume>`)
+
+**`task_blocked:`:**
+- Show blocker clearly
+- Offer via ask_user: upload missing data, revise assumptions, execute the blocking task first, or skip this task
+
+**If $ARGUMENTS = "all":** After each task completes, loop to the next pending task. Stop the loop at any needs_input: checkpoint or task_blocked: return and at the first `writing` task.
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► TASK [NN] COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Task:    [NN]; [name]
+Status:  [N]/[total] tasks complete
+
+Evidence ladder (report each rung with its actual value; never promote a rung):
+  Artifacts inspected:     [N] files under .research/tasks/task-[NN]/ read back; verifier
+                           receipt [task_complete | task_blocked | checkpoint] (read/ls only)
+  Prepared, not executed:  [list scripts, input decks, submission files, proposed experiments]
+  Executed computation:    [none | the exact commands the researcher or orchestrator actually
+                           ran in this session, with exit status and output paths]
+  Advisory checks:         physics [exit N | skipped], citations [exit N | skipped, offline?],
+                           scripts [exit N | skipped]; [N] findings resolved, [N] warnings noted
+  Scientific validation:   not performed by this workflow; the researcher owns physical,
+                           statistical and experimental validation of these outputs
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Execute the next dependency-ready task**
+`/materio:execute-task `
+
+**Or check progress**
+`/materio:progress`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+</offer_next>
+
+<success_criteria>
+- [ ] Target task resolved (from argument or next pending); at least two-digit directory used
+- [ ] Dependency check completed
+- [ ] Gate confirmation always shown with assumptions listed
+- [ ] Task type correctly routed; web availability passed explicitly
+- [ ] Outputs read back on disk with ls and test -s before marking complete
+- [ ] Completion output states the evidence ladder honestly: inspected, prepared, executed, advisory, validation not performed
+- [ ] Guardrail findings surfaced to the researcher; nothing auto-removed
+- [ ] WORKFLOW.md and STATE.md updated
+- [ ] Checkpoint saved if auto_checkpoint; commit only if commit_research is true
+</success_criteria>

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/help.md

@@ -0,0 +1,129 @@
+---
+description: "Overview of Materio commands, workflow, and philosophy"
+display-only: true
+---
+
+<objective>
+Display the Materio command reference. No tools needed.
+</objective>
+
+<process>
+
+Display the following:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio; materials research system
+ Plan and automate your research with Clio Coder
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CORE RESEARCH LOOP
+─────────────────────────────────────────
+ 1. /materio:identify-research
+       Guided interview → select domain, sub-field,
+       scope, and confirm a research prompt
+
+ 2. /materio:literature-review
+       Review literature, identify gaps, refine keywords
+       (loops back to identify-research if needed)
+
+ 3. /materio:define-virtual-lab
+       Map available resources: experimental equipment,
+       HPC systems, software licenses, collaborations
+       Questions are targeted to your research domain
+
+ 4. /materio:define-research-tasks
+       Choose from traditional research workflows or
+       build from scratch; interview per task for assumptions
+       (resource-aware: flags tasks requiring unavailable equipment)
+
+ 5. /materio:execute-task [N | all]
+       Execute a specific task or the full workflow
+       Types: literature, experimental, computational,
+              data-analysis, analytical, writing
+
+ 6. /materio:wtfp
+       Bridge to wtf-p; translate research into a paper
+       project with include/exclude control
+
+TASK MANAGEMENT
+─────────────────────────────────────────
+ /materio:add-task          Add a task to the workflow
+ /materio:remove-task [N]   Remove a task permanently
+ /materio:archive-task [N]  Archive (preserve but deactivate)
+
+DATA
+─────────────────────────────────────────
+ /materio:upload-data [file] Register data files, papers,
+                           and datasets for task use
+
+PROGRESS & CONTROL
+─────────────────────────────────────────
+ /materio:status             Full project dashboard
+ /materio:progress           Statusline + smart routing
+ /materio:pause-research     Pause + auto-checkpoint
+ /materio:resume-research    Resume from paused state
+ /materio:checkpoint save [label]   Save state snapshot
+ /materio:checkpoint restore [name]  Restore snapshot
+ /materio:checkpoint list           List snapshots
+
+META
+─────────────────────────────────────────
+ /materio:help               This help
+ /materio:settings           View/edit project config
+
+PROJECT STATE (.research/)
+─────────────────────────────────────────
+ RESEARCH.md     Research identity, prompt, scope
+ LITERATURE.md   Review results, gaps, keywords
+ VIRTUAL-LAB.md  Equipment, HPC, software, gaps
+ WORKFLOW.md     Tasks with status and assumptions
+ STATE.md        Current position, phase, decisions
+ DATA-INDEX.md   Registered data files
+ config.json     Settings (web_search, commit_research…)
+ data/           Uploaded datasets and papers
+ tasks/          Task-by-task outputs (task-NN/)
+ checkpoints/    State snapshot archives
+ handoff/        Paste-ready blocks for wtf-p 0.6
+
+TASK TYPES
+─────────────────────────────────────────
+ literature    → Read supplied papers and provided URLs, synthesize
+ experimental  → Generate protocol + data templates
+ computational → Generate simulation/analysis scripts
+ data-analysis → Analyze uploaded data, produce figures
+ analytical    → Mathematical modeling, derivations
+ writing       → Bridge to /materio:wtfp
+
+GUARDRAILS (after each task, advisory)
+─────────────────────────────────────────
+ check_physics     impossible values (T < 0 K, ρ ≤ 0…)
+ verify_citations  Crossref check on quoted titles/DOIs
+ check_scripts     syntax + hallucinated imports
+ Findings are shown to you; nothing is auto-removed.
+
+INTEGRATION WITH WTF-P
+─────────────────────────────────────────
+ /materio:wtfp prepares reviewed import briefs.
+ 0.6+: writes .research/handoff/ blocks you paste into
+       /wtfp:new-paper → map-project → create-outline
+ Existing paper state: inspect/reuse/repair first.
+ The bridge never writes paper state. Reuse answers already
+ answered during research planning.
+
+TIPS
+─────────────────────────────────────────
+ • Each dispatch receives fresh worker context
+ • Interviews happen in the command; agents only
+   synthesize and write, and report back checkpoints
+ • /materio:upload-data papers BEFORE literature-review:
+   supplied papers first, provided URLs second
+ • Materio never initializes git. Set commit_research=true in
+   /materio:settings if you want optional named-file commits. Checkpoints use archives.
+ • /materio:checkpoint save before long tasks
+ • /materio:literature-review can loop back to
+   identify-research if your prompt needs revision
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</process>

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/identify-research.md

@@ -0,0 +1,206 @@
+---
+description: "Start exploring a research subject; guided interview to select fields, define scope, and generate a research prompt"
+---
+
+<clio_execution>
+Read ${component:resource:clio-execution} before acting. It defines argument parsing,
+research state helpers, interview ownership, readback, and optional recording.
+</clio_execution>
+
+<clio_dispatch>
+Select the named recipe with dispatch({agent:"materio-...", task:"assignment with
+full context and exact permitted outputs", intent:{write_roots:["exact/output"]}}).
+Replace the illustrative recipe/path with those stated in this command. Use the
+registered dispatch fields shown here.
+Read the recipe's bound skill references and inline required templates, domain
+sections, answers and selected state into the worker task. Each dispatch starts
+fresh: re-dispatch with the full original context, prior candidates/outputs and
+the new selection, corrections, revisions or resume answer. Use monitor if the
+returned run is still active. Do not infer a resumed transcript from a run ID.
+Honor admission refusals instead of broadening write scope.
+
+Agent returns are mutation-report JSON. Route on the beginning of summary using
+the status branches below. For checkpoints, distinguish
+`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, and `needs_input: checkpoint:human-verify`;
+ask the exact question(s), collect the answer and re-dispatch. No new top-level
+status fields are allowed. A conforming JSON result is not proof of completion.
+After EVERY dispatch that wrote, use ls and read on every reported output and on
+the command's required files, including loop_back and partial checkpoint returns.
+Verify nonempty content and the promised changes before presenting success or
+continuing; re-dispatch with any missing/incorrect file named. Treat actual failed
+validation or execution as failure even when summary claims completion.
+</clio_dispatch>
+
+<execution_context>
+@${pluginRoot}/assets/templates/RESEARCH.md
+@${pluginRoot}/assets/templates/config.json
+@${pluginRoot}/assets/references/research-domains.md
+</execution_context>
+
+<objective>
+Initialize a new material science research project through a deep guided interview. Creates `.research/` and populates RESEARCH.md with domain, sub-field, scope, researcher profile, and a confirmed research prompt.
+
+**Orchestrator role:** Check preconditions, detect existing research context, run the whole researcher interview (foundation, profile, and Socratic drilling), spawn the materio-research-explorer agent for synthesis, present its candidate prompts, collect the choice, re-dispatch the agent to write the files, verify, record.
+
+**Why the interview lives here:** These worker roles return questions to the orchestrator (Clio forbids ask_user in agent recipes). The orchestrator owns every question. The agent gets a fresh context window for the reasoning that benefits from it: turning the transcript into sharp, calibrated candidate prompts.
+</objective>
+
+<context>
+No arguments. Runs in current directory.
+</context>
+
+<process>
+
+Worker write scope: .research/RESEARCH.md and .research/STATE.md, only after selection.
+
+
+## 1. Validate Environment
+
+```bash
+[ -f .research/RESEARCH.md ] && echo "WARN: Research already initialized. Use /materio:progress to see current state, or continue to refine."
+python3 "${component:script:research-state}" config
+# Read-only before researcher selection; initialize at the approved write step.
+```
+
+Materio never runs `git init`. Version control of `.research/` is the researcher's choice, controlled by `commit_research` in `.research/config.json` (default false).
+
+## 2. Detect Existing Context
+
+```bash
+find . -name "*.pdf" -o -name "*.csv" -o -name "*.bib" -o -name "*.txt" 2>/dev/null | grep -v ".research" | grep -v ".claude" | grep -v ".git" | head -10
+```
+
+If data files found: ask via ask_user whether to base the research framing on existing files, and suggest `/materio:upload-data` afterwards so the literature review can read them.
+
+## 3. Gather Research Foundation (Batched)
+
+Use ask_user; collect core framing in one turn:
+- header: "Research Exploration; Material Science"
+- question: "Let's explore your research direction.\n\n1. **Domain**: Which area of material science? (e.g., Structural, Energy, Biomaterials, Computational, Nanomaterials, Functional, Polymers, Characterization)\n2. **Driving question**: What phenomenon, material, or problem interests you? (free-form, even vague is fine)\n3. **Motivation**: Fundamental understanding, application/device, optimization, or review/synthesis?\n4. **Resources available**: Experimental lab, computational cluster, literature only, or combination?"
+- options: "Provided details" | "I'm not sure yet; help me explore" | "I have a specific topic already"
+
+**If "I'm not sure yet":** Ask about domain first, then walk through sub-fields in that domain using research-domains.md as reference, one ask_user per level, before continuing.
+
+**If "I have a specific topic already":** Capture it verbatim, then go to Step 4 and run only Round 3 of Step 5.
+
+## 4. Gather Researcher Profile
+
+Use ask_user:
+- header: "Researcher Context"
+- question: "Help me understand your context:\n1. **Career stage**: Undergrad / Grad student / Postdoc / PI / Industry researcher\n2. **Timeline**: How long for this research? (months)\n3. **Prior work**: Have you already read papers in this area? Any specific authors or groups you follow?\n4. **Constraints**: Any materials, methods, or approaches you CANNOT use?"
+- options: "Provided details" | "Skip; use reasonable defaults"
+
+## 5. Socratic Drilling (as needed)
+
+Narrow in up to three rounds. Skip any round whose answers the transcript already contains. Use the domain's sub-fields, key phenomena, and common methods from research-domains.md to make the examples concrete for this researcher.
+
+**Round 1; Narrow the sub-field:**
+- header: "Narrowing Your Research Focus"
+- question: "You mentioned [topic]. Let's narrow it down:\n\n1. What specific aspect? (e.g., for batteries: anode material? electrolyte? capacity fade mechanism? cycling stability?)\n2. What material system specifically? (e.g., Li-S, Na-ion, solid-state with sulfide electrolyte)\n3. What scale? (atomic/nano/micro/device level)"
+- options: "Provided details" | "Help me choose; show sub-fields"
+
+**Round 2; Identify the gap:**
+- header: "Finding the Angle"
+- question: "For [narrowed topic]:\n1. What do you think is currently UNKNOWN or UNSOLVED?\n2. What would change if you answered your question? (better battery? new understanding? design rule?)\n3. What's your hypothesis or intuition about the answer?"
+- options: "Provided details" | "I don't know yet; the literature review should tell me"
+
+**Round 3; Scope confirmation:**
+- header: "Scoping the Research"
+- question: "Final scoping:\n1. What methods will you use? (synthesis, characterization, simulation; be specific)\n2. What will you NOT study? (even if related and interesting)\n3. What's the minimum result that would make this a successful research project?"
+- options: "Provided details" | "Let the candidates propose scope"
+
+Assemble every answer from Steps 2 through 5, verbatim, into the `<researcher_input>` transcript.
+
+## 6. Dispatch materio-research-explorer
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► EXPLORING RESEARCH SPACE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use dispatch with `agent: "materio-research-explorer"` and a task containing the assignment and full context. The prompt carries the full inlined context:
+- `<researcher_input>`; the complete interview transcript from Steps 2–5
+- `<domains_ref>`; the relevant section of research-domains.md
+- `<research_path>`; `.research/RESEARCH.md`
+
+Before selection, request candidates only and authorize no writes; omit
+write_roots and say explicitly that this is the no-write candidate phase.
+On selection, authorize exactly `.research/RESEARCH.md` and `.research/STATE.md`.
+Include all three original candidates, the verbatim selection, scope corrections,
+and the complete RESEARCH template in the writing dispatch.
+
+## 7. Present Candidates and Collect the Choice
+
+**`candidates_ready:`:**
+
+Use ask_user, one turn:
+- header: "Your Research Prompts"
+- question: "Based on our conversation, here are 3 research prompts:\n\n**A (Focused):** [prompt A]\n  In: [scope] · Out: [scope] · Keywords: [list]\n\n**B (Standard):** [prompt B]\n  In / Out / Keywords\n\n**C (Ambitious):** [prompt C]\n  In / Out / Keywords\n\nRecommended: [X] because [reason].\n\nWhich fits your goals? If you pick one, also say whether its scope and keywords need any correction."
+- options: "Prompt A" | "Prompt B" | "Prompt C" | "Combine or edit; I'll describe"
+
+Re-dispatch the explorer with a `<selection>` block containing the choice and any corrections. Always spawn a fresh materio-research-explorer with the full `<researcher_input>` transcript plus `<selection>`.
+
+**`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, or `needs_input: checkpoint:human-verify`:** Ask the batched questions it lists via ask_user, append the answers to the transcript, and re-dispatch the agent.
+
+**`exploration_inconclusive:`:** Show what's missing and what it suggested. Offer to re-run with more guidance.
+
+After the researcher selects a candidate and confirms scope, run
+`python3 "${component:script:research-state}" init` before the writing dispatch.
+
+## 8. Verify and Record
+
+**`research_identified:`:**
+
+```bash
+test -s .research/RESEARCH.md && test -s .research/STATE.md && echo "OK: files on disk" || echo "ERROR: agent reported files it did not write"
+grep -n "Selected Prompt" -A 2 .research/RESEARCH.md
+```
+
+If either file is missing, do not report success; re-dispatch the agent and tell it exactly which file is absent.
+
+Optional git record, only if the researcher enabled it:
+```bash
+python3 "${component:script:research-state}" record --message "research: initialize; [research prompt one-liner]" --files "${CHANGED_FILES[@]}"
+```
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► RESEARCH IDENTIFIED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Prompt:  [selected research prompt]
+Domain:  [field + sub-field]
+Profile: .research/RESEARCH.md
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Register the papers you already have, then review the literature**
+
+`/materio:upload-data` (optional, but the review is only as good as its corpus)
+`/materio:literature-review`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+**Also available:**
+- `/materio:define-research-tasks`; skip literature review if already done
+
+</offer_next>
+
+<success_criteria>
+- [ ] Every question to the researcher was asked by this command, not by the agent
+- [ ] Domain and sub-field clearly identified
+- [ ] Research prompt is a single answerable question
+- [ ] Scope (in/out) explicitly defined
+- [ ] Researcher profile captured (career stage, resources, timeline)
+- [ ] Three candidate prompts presented before final selection
+- [ ] RESEARCH.md and STATE.md verified on disk with test -s
+- [ ] config.json created from template; no git init; commit only if commit_research is true
+</success_criteria>