@iowarp/clio-coder 0.4.5 → 0.4.7

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

@@ -0,0 +1,230 @@
+---
+description: "Build a research workflow; select from traditional templates or create from scratch, with assumption interviews per task"
+---
+
+<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/RESEARCH.md
+@.research/LITERATURE.md
+@.research/VIRTUAL-LAB.md
+@${pluginRoot}/assets/references/traditional-workflows.md
+@${pluginRoot}/assets/templates/WORKFLOW.md
+</execution_context>
+
+<objective>
+Create the research workflow for the project. Either select a traditional workflow template and customize it, or build from scratch. Each task gets an assumption interview. Outputs WORKFLOW.md.
+
+**Orchestrator role:** Load research context, present workflow options, gather customizations and scope, run the per-task assumption interview, spawn the materio-workflow-planner agent to generate WORKFLOW.md, present resource flags and planner defaults for decision, re-dispatch the agent with revisions, create task directories, record.
+
+**Why the interview lives here:** These worker roles return questions to the orchestrator. Assumptions are research decisions and only the researcher can make them, so this command collects them before the planner runs. The planner gets a fresh context for the reasoning that benefits from it: feasibility against VIRTUAL-LAB.md, dependency ordering, and writing a WORKFLOW.md the executor can run without interpretation.
+</objective>
+
+<context>
+No arguments. Requires RESEARCH.md to exist.
+</context>
+
+<process>
+
+Worker write scope: .research/WORKFLOW.md.
+
+
+## 1. Validate Environment
+
+```bash
+test -f .research/RESEARCH.md || echo "ERROR: No RESEARCH.md. Run /materio:identify-research first."
+[ -f .research/WORKFLOW.md ] && echo "WARN: WORKFLOW.md exists; running again will replace it."
+cat .research/RESEARCH.md
+[ -f .research/LITERATURE.md ] && cat .research/LITERATURE.md | head -60
+```
+
+Check for VIRTUAL-LAB.md and warn if missing:
+```bash
+if [ ! -f .research/VIRTUAL-LAB.md ]; then
+  echo "NOTE: No VIRTUAL-LAB.md found. Run /materio:define-virtual-lab to map your resources first."
+  echo "Proceeding without resource constraints; tasks may be planned that require unavailable equipment."
+fi
+[ -f .research/VIRTUAL-LAB.md ] && cat .research/VIRTUAL-LAB.md
+```
+
+## 2. Present Workflow Template Options
+
+Based on the research type from RESEARCH.md (experimental / computational / mixed / literature-only), present the relevant traditional workflow templates from traditional-workflows.md.
+
+Use ask_user:
+- header: "Research Workflow Design"
+- question: "Based on your research (**[research prompt]**), I suggest one of these workflow templates:\n\n**A. [Template name]**; [1-line description, N tasks]\n**B. [Template name]**; [1-line description, N tasks]\n**C. Build from scratch**; I'll define each step\n\nWhich fits best?"
+- options: "Template A" | "Template B" | "Template C; Build from scratch" | "Show me all templates"
+
+## 3. Gather Customizations
+
+After template selection, ask about modifications:
+Use ask_user:
+- header: "Workflow Customization"
+- question: "Template **[selected]** has these tasks:\n\n[numbered list of tasks from template]\n\nWhat changes?\n1. **Add tasks**: Any steps missing for your specific research?\n2. **Remove tasks**: Any steps you'll skip (and why)?\n3. **Reorder**: Any dependencies that differ from the template?"
+- options: "Use as-is" | "I have changes" | "Add one task" | "Remove one task"
+
+## 4. Confirm Scope and Exclusions
+
+Use ask_user:
+- header: "Scope & Exclusions"
+- question: "Before planning assumptions, confirm:\n1. **Hard constraints**: Which tasks are definitely IN scope?\n2. **Out of scope**: Which standard steps will you skip?\n3. **First milestone**: Which task marks the first major checkpoint?\n4. **Data availability**: Do you have any existing data that eliminates early tasks?"
+- options: "Confirmed; proceed to assumptions" | "Let me adjust"
+
+## 5. Assumption Interview, Per Task
+
+You now hold the final task list. For each task, ask the question block for its type. Batch tasks of the same type into one ask_user when there are three or fewer; otherwise one question per task. Use the "Key assumptions to interview about" hints in traditional-workflows.md for the selected template to sharpen the prompts. Every question offers "Use planner defaults for this task" so the researcher can skip and confirm later.
+
+**For experimental tasks:**
+- header: "Assumptions: Task [NN]; [name]"
+- question: "For '[task description]', I need to understand your assumptions:\n1. **Sample preparation**: What processing route? What contamination risks?\n2. **Characterization**: Which tools are available? What resolution/sensitivity?\n3. **Test conditions**: Temperature, strain rate, environment, standards (ASTM/ISO)?\n4. **Sample size/replicates**: How many samples? What's statistically sufficient?\n5. **Success criteria**: What result would confirm or disprove your hypothesis?"
+- options: "Provided details" | "Use planner defaults for this task"
+
+**For computational tasks:**
+- header: "Assumptions: Task [NN]; [name]"
+- question: "For '[task description]':\n1. **Method**: DFT, MD, phase-field, CALPHAD; which and why?\n2. **Software**: VASP, LAMMPS, Thermo-Calc, etc.?\n3. **Functional/force field**: Exchange-correlation functional or interatomic potential?\n4. **System size and timescale**: Feasible with available resources?\n5. **Validation benchmark**: What experimental data exists to validate against?"
+- options: "Provided details" | "Use planner defaults for this task"
+
+**For data-analysis tasks:**
+- header: "Assumptions: Task [NN]; [name]"
+- question: "For '[task description]':\n1. **Data source**: Which uploaded files? Which task outputs?\n2. **Statistical approach**: What statistical tests are appropriate?\n3. **Outlier handling**: Expected outliers? How to treat them?\n4. **Visualization**: What plots are needed for the paper?\n5. **Software**: Python/MATLAB/R? Which libraries?"
+- options: "Provided details" | "Use planner defaults for this task"
+
+**For literature tasks:**
+- header: "Assumptions: Task [NN]; [name]"
+- question: "For '[task description]':\n1. **Scope**: Which sub-topics to cover?\n2. **Inclusion criteria**: Year range, journal type, minimum citation count?\n3. **Key authors/groups**: Anyone to prioritize?\n4. **Output format**: Structured table? Narrative summary? BibTeX file?"
+- options: "Provided details" | "Use planner defaults for this task"
+
+**For analytical tasks:**
+- header: "Assumptions: Task [NN]; [name]"
+- question: "For '[task description]':\n1. **Governing model**: Which physical model or theory?\n2. **Boundary conditions and simplifications**: What is held fixed or neglected?\n3. **Validation**: Which limiting cases or data will the model be checked against?\n4. **Implementation**: Analytical only, or numerical (Python/MATLAB)?"
+- options: "Provided details" | "Use planner defaults for this task"
+
+Writing tasks need no interview; they bridge to `/materio:wtfp`.
+
+Collect every answer verbatim into `<assumptions>`, keyed by task name, with "planner defaults requested" where the researcher skipped.
+
+## 6. Spawn materio-workflow-planner Agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► PLANNING RESEARCH WORKFLOW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use dispatch with `agent: "materio-workflow-planner"` and a task containing the assignment and full context. The prompt carries:
+- `<research>`; full RESEARCH.md
+- `<literature>`; LITERATURE.md gaps and methods landscape
+- `<virtual_lab>`; full VIRTUAL-LAB.md (or "not defined" if missing)
+- `<selected_template>`; the chosen template tasks
+- `<customizations>`; additions, removals, reorderings
+- `<scope_decisions>`; inclusions, exclusions, first milestone, existing data
+- `<assumptions>`; the per-task answers from Step 5
+- `<workflow_path>`; `.research/WORKFLOW.md`
+
+## 7. Decide on Flags and Defaults
+
+**`workflow_complete:`:**
+
+```bash
+test -s .research/WORKFLOW.md && echo OK || echo "ERROR: WORKFLOW.md missing"
+grep -c "^### Task" .research/WORKFLOW.md
+```
+If missing, re-dispatch the agent and say so.
+
+Present the planner's return and ask via ask_user, one turn:
+- header: "Workflow Review"
+- question: "[N] tasks planned. Critical path: [A → B → C]. First checkpoint after Task [NN].\n\n**Resource flags** ([N]):\n- ⚠ Task [NN]: [gap] → applied: [alternative]\n- BLOCKED Task [NN]: [gap] → proposed: [remove/replace]\n\n**Planner defaults to confirm** ([N]):\n- Task [NN]: [assumption]\n\nDoes this order make sense? Decide on each flag and default, or accept as written."
+- options: "Accept as written" | "I have decisions on the flags" | "Confirm defaults with edits" | "Change the task order"
+
+If anything changes: re-dispatch the planner with a `<revisions>` block (or re-spawn with the full context plus `<revisions>`), then re-verify the file.
+
+**`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, or `needs_input: checkpoint:human-verify`:** Present the question via ask_user, collect the domain-expert answer, re-dispatch the agent.
+
+## 8. Create Task Directories and State
+
+```bash
+python3 "${component:script:research-state}" validate-workflow
+python3 "${component:script:research-state}" task-dirs
+ls .research/tasks/
+```
+
+Update STATE.md: current phase = executing, current task = first eligible active task in dependency order, status = planning. Keep the Decisions Made list and append the workflow decisions.
+
+Optional git record:
+```bash
+python3 "${component:script:research-state}" record --message "research: workflow defined; [N] tasks, [research type]" --files "${CHANGED_FILES[@]}"
+```
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► WORKFLOW DEFINED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Workflow: .research/WORKFLOW.md
+Tasks:    [N] tasks ([type])
+
+| # | Task | Type | Depends On |
+|---|------|------|------------|
+[table from WORKFLOW.md]
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Execute the first task**
+
+`/materio:execute-task 1`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+**Task management:**
+- `/materio:add-task`; add a task to the workflow
+- `/materio:remove-task [N]`; remove a task
+- `/materio:archive-task [N]`; archive without deleting
+
+</offer_next>
+
+<success_criteria>
+- [ ] Every question to the researcher was asked by this command, not by the agent
+- [ ] Traditional workflow template presented as starting point
+- [ ] User customizations captured (add/remove/reorder)
+- [ ] Scope and exclusions explicitly confirmed
+- [ ] Assumption interview run per task before planning; skips recorded as planner defaults
+- [ ] Resource flags and planner defaults decided by the researcher
+- [ ] Each task has: type, description, assumptions, inputs, outputs, dependencies
+- [ ] Task directories created with at least two-digit numbering for every task count
+- [ ] WORKFLOW.md verified on disk; commit only if commit_research is true
+</success_criteria>

package/library/plugins/materio/ai.iowarp.clio/prompts/materio/define-virtual-lab.md

@@ -0,0 +1,181 @@
+---
+description: "Interview to map all available lab resources; equipment, HPC, software, collaborations; into a VIRTUAL-LAB.md that guides feasible task planning"
+---
+
+<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/RESEARCH.md
+@.research/LITERATURE.md
+@${pluginRoot}/assets/templates/VIRTUAL-LAB.md
+@${pluginRoot}/assets/references/research-domains.md
+</execution_context>
+
+<objective>
+Build a complete map of the researcher's available resources. The resulting VIRTUAL-LAB.md is used by define-research-tasks and execute-task to ensure workflow steps are feasible and protocols match available equipment.
+
+**Orchestrator role:** Load research context, run the resource interview (quick dump or guided by category, with questions targeted to the methods the field uses), spawn the materio-lab-definer agent to structure and gap-analyze, present the summary and gaps for verification, re-dispatch the agent with corrections, record.
+
+**Why the interview lives here:** These worker roles return questions to the orchestrator. The agent gets a fresh context for the cross-referencing that benefits from it: matching what the researcher has against what the literature says the field uses, and building the resource-to-task mapping.
+</objective>
+
+<context>
+No arguments. Reads .research/RESEARCH.md and LITERATURE.md to ask targeted resource questions.
+</context>
+
+<process>
+
+Worker write scope: .research/VIRTUAL-LAB.md.
+
+
+## 1. Validate Environment
+
+```bash
+test -f .research/RESEARCH.md || echo "ERROR: No RESEARCH.md. Run /materio:identify-research first."
+[ -f .research/VIRTUAL-LAB.md ] && echo "WARN: VIRTUAL-LAB.md already exists; running again will update it."
+cat .research/RESEARCH.md
+grep -A 12 "Methodological Landscape" .research/LITERATURE.md 2>/dev/null
+```
+
+Extract the methods the field uses from the Methodological Landscape table (or, if LITERATURE.md is missing, from the domain's common methods in research-domains.md). These drive which equipment and software you ask about.
+
+## 2. Quick Mode vs Guided Interview
+
+Use ask_user:
+- header: "Virtual Lab Setup"
+- question: "I'll map your available research resources. How would you like to proceed?\n\n**Quick**: Paste or describe all your resources in one response (I'll structure it)\n**Guided**: I'll interview you by category (equipment, computing, software, collaborations)\n\nI'll cross-reference with the methods commonly used in your field ([domain from RESEARCH.md]: [methods]) to make sure I ask about the most relevant tools."
+- options: "Quick; I'll describe everything at once" | "Guided interview by category"
+
+## 3. Run the Interview
+
+**Quick mode:** If the researcher's answer already contains the description, use it. Otherwise ask one free-form ask_user ("Describe your equipment, computing, software licenses, external facilities, budget, and people. Anything goes; I'll structure it.").
+
+**Guided mode:** Three batched questions. Fill the bracketed lists from the field's methods so the researcher only sees relevant instruments.
+
+Category 1:
+- header: "Experimental Equipment"
+- question: "What experimental equipment do you have access to?\n\nBased on your field ([domain/sub-field]), the most relevant categories are:\n\n**Characterization** (common in your field: [e.g., XRD, SEM, TEM]):\nFor each: in-house or external? Booking required? Key limitations?\n\n**Mechanical/Physical Testing** (if applicable):\n[tensile testing, fatigue, hardness, DMA; as relevant to domain]\n\n**Processing/Synthesis** (if applicable):\n[furnaces, deposition, arc melting, electrochemistry; as relevant]\n\n**Other**: Any specialized equipment not in these categories?"
+- options: "Provided details" | "Mostly computational; minimal experimental equipment" | "External facilities only"
+
+Category 2:
+- header: "Computational Resources"
+- question: "What computational resources do you have?\n\n1. **HPC systems**: Cluster name, cores available per job, scheduler (SLURM/PBS), key software installed ([VASP, LAMMPS, Abaqus; as relevant]), queue wait times?\n2. **Local machines**: CPU/GPU specs for smaller calculations?\n3. **Cloud compute**: AWS, GCP, Google Colab, XSEDE/ACCESS allocation?\n4. **Software licenses** (beyond HPC): VASP, Thermo-Calc, Abaqus, MATLAB, OriginPro; which do you have?\n\nNote: Open-source tools (LAMMPS, QE, Python, VESTA) assumed available; only mention if there are access issues."
+- options: "Provided details" | "No computational resources; experimental only" | "Primarily computational"
+
+Category 3:
+- header: "External Facilities & Collaborations"
+- question: "Do you have access to resources outside your direct lab?\n\n1. **User facilities**: National labs (APS, NSLS-II, ORNL, etc.), synchrotron access, neutron sources; proposal-based or through collaborator?\n2. **Core facilities**: University-level shared equipment (TEM center, nanofab, etc.); fee-for-service?\n3. **Industry/national lab collaborators**: Anyone providing materials, measurements, or compute?\n4. **Budget**: Rough estimate for experiments ($/month or total project)?\n5. **Timeline constraints**: Any equipment booking backlogs, seasonal access issues, or certifications not yet held?"
+- options: "Provided details" | "No external access" | "Primarily internal resources"
+
+Assemble all answers verbatim into `<resource_input>`.
+
+## 4. Spawn materio-lab-definer Agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► DEFINING VIRTUAL LAB
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use dispatch with `agent: "materio-lab-definer"` and a task containing the assignment and full context. The prompt carries:
+- `<research>`; full RESEARCH.md (domain, prompt, scope)
+- `<literature>`; LITERATURE.md methodological landscape section, or "not available"
+- `<resource_input>`; the interview transcript from Step 3
+- `<lab_path>`; `.research/VIRTUAL-LAB.md`
+
+## 5. Verify with the Researcher
+
+**`virtual_lab_defined:`:**
+
+```bash
+test -s .research/VIRTUAL-LAB.md && echo OK || echo "ERROR: VIRTUAL-LAB.md missing"
+```
+If missing, re-dispatch the agent and say so.
+
+Use ask_user:
+- header: "Verify Virtual Lab"
+- question: "Here's your lab profile summary:\n\n**Experimental**: [N items; key equipment list]\n**Computational**: [HPC + local + cloud summary]\n**Software**: [key licenses]\n**External**: [N facilities]\n\n**Gaps flagged** ([N]):\n- [method]: [reason] → [alternative]\n\n**Details that would sharpen feasibility** (optional):\n- [equipment]: [missing detail]\n\nLook accurate? Anything to correct or add?"
+- options: "Looks good; save it" | "I need to correct something" | "I have answers to the follow-ups"
+
+If corrections or follow-up answers: re-dispatch the agent with a `<corrections>` block (or re-spawn with the full `<resource_input>` plus `<corrections>`), then re-verify the file.
+
+**`needs_input: checkpoint:decision`, `needs_input: checkpoint:human-action`, or `needs_input: checkpoint:human-verify`:** A gap makes the current prompt infeasible. Present the options via ask_user, then re-dispatch the agent with the decision. If the researcher narrows the prompt, note the decision in STATE.md.
+
+## 6. Record
+
+```bash
+python3 "${component:script:research-state}" record --message "research: virtual lab defined; [N] equipment, [N] compute resources" --files "${CHANGED_FILES[@]}"
+```
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Materio ► VIRTUAL LAB DEFINED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Lab profile: .research/VIRTUAL-LAB.md
+
+Experimental:  [N] equipment items ([key ones])
+Computational: [HPC systems] + [local/cloud]
+Software:      [key licenses]
+External:      [N] facilities/collaborations
+Gaps flagged:  [N] → [e.g., "No TEM access; external core lab, 2–3 weeks"]
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Build your research workflow**
+(now resource-aware; tasks will only use available equipment)
+
+`/materio:define-research-tasks`
+
+<sub>Each dispatch starts with fresh worker context.</sub>
+
+───────────────────────────────────────────
+
+**Also available:**
+- `/materio:upload-data`; register existing datasets before planning tasks
+- `/materio:literature-review`; continue reviewing if not complete
+
+</offer_next>
+
+<success_criteria>
+- [ ] Every question to the researcher was asked by this command, not by the agent
+- [ ] Questions targeted to the field's methods (from LITERATURE.md), not a generic checklist
+- [ ] Both experimental AND computational resources captured
+- [ ] Software licenses documented
+- [ ] External facilities and collaborations recorded
+- [ ] Gaps and follow-up details presented for verification before saving
+- [ ] Resource-to-task mapping table populated
+- [ ] VIRTUAL-LAB.md verified on disk; commit only if commit_research is true
+</success_criteria>