@iowarp/clio-coder 0.4.5 → 0.4.7

package/library/plugins/materio/assets/actions/execute-task.md

@@ -0,0 +1,290 @@
+# Action: execute-task
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.
+
+
+Use the assigned role skill with complete research context and exact permitted outputs. Return structured checkpoints and inspect actual files after writing.
+
+<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 applying the task-executor skill 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, apply the materio-task-executor skill 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.
+
+
+An optional native fleet may require an existing Git worktree to enforce its
+write boundary. Clio's v4 fleet does. If absent, keep the boundary and use direct
+role execution with the selected task output grant followed by a separate read-only
+review. Never initialize git to enable the fleet. If the host lacks worker
+delegation, perform labeled artifact readback in the main conversation and disclose
+that no independent worker review occurred.
+
+## 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. When general search is unavailable: 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 define-research-tasks using the materio-workflow-planner skill first."
+cat .research/WORKFLOW.md
+cat .research/STATE.md 2>/dev/null
+cat .research/DATA-INDEX.md 2>/dev/null
+python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" config
+```
+
+## 2. Resolve Target Task
+
+**If $ARGUMENTS is empty:** Run `python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" 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 "${PACKAGE_ROOT}/assets/scripts/research_state.py" 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 the host conversation facility: 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 the host conversation facility:
+- 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; Run upload-data using the materio-research-explorer skill" | "Skip this task"
+
+If assumptions are updated, write them back to the task entry in WORKFLOW.md before applying the role.
+
+## 5. Handle Task Type Routing
+
+**If type = `writing`:**
+- Tell user: "This task involves writing. Use `Run wtfp using the materio-research-explorer skill` 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 `Run upload-data using the materio-research-explorer skill` → analysis code + results summary + figure descriptions
+
+**If type = `analytical`:** theoretical mode → derivation, validation, optional implementation
+
+## 6. apply the materio-task-executor skill
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► EXECUTING TASK [NN]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply the materio-task-executor role skill using the assignment and full context; delegate if supported. 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 the host URL-fetch capability 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, apply the role again naming the missing file; do not mark the task complete.
+
+1b. Apply the materio-task-verifier skill to the approved task,
+   assumptions, dependency context, actual output inventory and summary. Use a
+   separate read-only worker with no write grant when available; otherwise perform
+   labeled main-conversation readback and disclose that independent worker review
+   was unavailable. Resolve every returned researcher checkpoint. Read/ls findings
+   are artifact inspection, not command-backed scientific validation. Preserve
+   host grounding diagnostics; a rejected receipt remains incomplete and cannot
+   be promoted to completion. Advisory commands 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 "${PACKAGE_ROOT}/assets/scripts/research_state.py" config --key web_search)" = true ] || citation_flags=(--offline)
+     if ((${#physics_files[@]})); then
+       if python3 "${PACKAGE_ROOT}/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 "${PACKAGE_ROOT}/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 "${PACKAGE_ROOT}/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 the host conversation facility:
+   - 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"
+   Apply the task-executor skill again 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 "${PACKAGE_ROOT}/assets/scripts/research_state.py" config --key auto_checkpoint)" = true ]; then
+  python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" checkpoint save after-task-NN
+fi
+   ```
+
+5. Optional git record:
+   ```bash
+   python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" 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 the host conversation facility
+- Apply the task-executor skill again with a `<resume>` block containing the answer (or continue with the full context plus `<resume>`)
+
+**`task_blocked:`:**
+- Show blocker clearly
+- Offer via the host conversation facility: 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**
+`Run execute-task using the materio-task-executor skill `
+
+**Or check progress**
+`Run progress using the materio-research-explorer skill`
+
+<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/assets/actions/help.md

@@ -0,0 +1,140 @@
+# Action: help
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+<objective>
+Display the Materio action reference with the actual skill invocation vocabulary. No tools needed.
+</objective>
+
+<process>
+
+Display the following:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio; materials research system
+ Plan and automate your research with your coding agent
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CORE RESEARCH LOOP
+─────────────────────────────────────────
+ 1. Run identify-research using the materio-research-explorer skill
+       Guided interview → select domain, sub-field,
+       scope, and confirm a research prompt
+
+ 2. Run literature-review using the materio-literature-reviewer skill
+       Review literature, identify gaps, refine keywords
+       (loops back to identify-research if needed)
+
+ 3. Run define-virtual-lab using the materio-lab-definer skill
+       Map available resources: experimental equipment,
+       HPC systems, software licenses, collaborations
+       Questions are targeted to your research domain
+
+ 4. Run define-research-tasks using the materio-workflow-planner skill
+       Choose from traditional research workflows or
+       build from scratch; interview per task for assumptions
+       (resource-aware: flags tasks requiring unavailable equipment)
+
+ 5. Run execute-task using the materio-task-executor skill [N | all]
+       Execute a specific task or the full workflow
+       Types: literature, experimental, computational,
+              data-analysis, analytical, writing
+
+ 6. Run wtfp using the materio-research-explorer skill
+       Bridge to wtf-p; translate research into a paper
+       project with include/exclude control
+
+TASK MANAGEMENT
+─────────────────────────────────────────
+ Run add-task using the materio-research-explorer skill          Add a task to the workflow
+ Run remove-task using the materio-research-explorer skill [N]   Remove a task permanently
+ Run archive-task using the materio-research-explorer skill [N]  Archive (preserve but deactivate)
+
+DATA
+─────────────────────────────────────────
+ Run upload-data using the materio-research-explorer skill [file] Register data files, papers,
+                           and datasets for task use
+
+PROGRESS & CONTROL
+─────────────────────────────────────────
+ Run status using the materio-research-explorer skill             Full project dashboard
+ Run progress using the materio-research-explorer skill           Statusline + smart routing
+ Run pause-research using the materio-research-explorer skill     Pause + auto-checkpoint
+ Run resume-research using the materio-research-explorer skill    Resume from paused state
+ Run checkpoint using the materio-research-explorer skill save [label]   Save state snapshot
+ Run checkpoint using the materio-research-explorer skill restore [name]  Restore snapshot
+ Run checkpoint using the materio-research-explorer skill list           List snapshots
+
+META
+─────────────────────────────────────────
+ Run help using the materio-research-explorer skill               This help
+ Run settings using the materio-research-explorer skill           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 Run wtfp using the materio-research-explorer skill
+
+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
+─────────────────────────────────────────
+ Run wtfp using the materio-research-explorer skill prepares reviewed import briefs.
+ 0.6+: writes .research/handoff/ blocks you paste into
+       wtf-p action 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
+ • Run upload-data using the materio-research-explorer skill papers BEFORE literature-review:
+   supplied papers first, provided URLs second
+ • Materio never initializes git. Set commit_research=true in
+   Run settings using the materio-research-explorer skill if you want optional named-file commits. Checkpoints use archives.
+ • Run checkpoint using the materio-research-explorer skill save before long tasks
+ • Run literature-review using the materio-literature-reviewer skill can loop back to
+   identify-research if your prompt needs revision
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</process>

package/library/plugins/materio/assets/actions/identify-research.md

@@ -0,0 +1,204 @@
+# Action: identify-research
+
+This guide is linked from an installed portable skill. Action requests use the
+actual installed skill names; this standard package registers no slash commands.
+The interactive assistant applies a role inline or assigns its skill to a generic
+worker if the host supports delegation. No named worker registration is presumed.
+If a native peer package supplies command or agent bindings, follow its binding
+section below while preserving the same researcher gates and return checkpoints.
+
+This guide is linked from an installed portable skill. Determine the package root
+from that skill's directory. Before executing a shell example, bind PACKAGE_ROOT
+to that actual root in the same command. Treat $ARGUMENTS as validated user input;
+these are examples to fill with actual paths, not automatic host substitutions.
+
+
+
+Use the host's file reading/editing and local command execution capabilities. Read
+assets/references/research-policy.md, resolved from this package. If this task
+needs researcher answers, the interactive assistant asks them through the host's
+conversation facility before gated writes. Workers return questions with their
+checkpoint kind. Use the named role's portable skill for the scientific work;
+if the host does not support delegation, the interactive assistant performs that
+role with the same input/output and decision boundaries. Do not invent worker,
+search, fleet, or interactive capabilities. Inspect actual files before completion.
+Use package scripts by resolving their links from the installed skill directory.
+For an optional commit, set CHANGED_FILES to only the named files actually changed
+and read back during this action. The research-state helper rejects directory staging.
+
+
+Use the assigned role skill with complete research context and exact permitted outputs. Return structured checkpoints and inspect actual files after writing.
+
+<execution_context>
+@${PACKAGE_ROOT}/assets/templates/RESEARCH.md
+@${PACKAGE_ROOT}/assets/templates/config.json
+@${PACKAGE_ROOT}/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), apply the materio-research-explorer skill for synthesis, present its candidate prompts, collect the choice, apply the role again to write the files, verify, record.
+
+**Why the interview lives here:** These worker roles return questions to the orchestrator (worker roles cannot interview the researcher). 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 Run progress using the materio-research-explorer skill to see current state, or continue to refine."
+python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" 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 the host conversation facility whether to base the research framing on existing files, and suggest `Run upload-data using the materio-research-explorer skill` afterwards so the literature review can read them.
+
+## 3. Gather Research Foundation (Batched)
+
+Use the host conversation facility; 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 the host conversation facility 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 the host conversation facility:
+- 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. Apply the materio-research-explorer skill
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► EXPLORING RESEARCH SPACE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply the materio-research-explorer role skill using the assignment and full context; delegate if supported. 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
+any write authorization and state 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 the host conversation facility, 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"
+
+Apply the research-explorer skill again with a `<selection>` block containing the choice and any corrections. Apply the materio-research-explorer skill 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 the host conversation facility, append the answers to the transcript, and apply the role again.
+
+**`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 "${PACKAGE_ROOT}/assets/scripts/research_state.py" 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; apply the role again and tell it exactly which file is absent.
+
+Optional git record, only if the researcher enabled it:
+```bash
+python3 "${PACKAGE_ROOT}/assets/scripts/research_state.py" 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**
+
+`Run upload-data using the materio-research-explorer skill` (optional, but the review is only as good as its corpus)
+`Run literature-review using the materio-literature-reviewer skill`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+**Also available:**
+- `Run define-research-tasks using the materio-workflow-planner skill`; 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>