@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/_authoring/templates/skill/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "citation-check",
+	"version": "1.0.0",
+	"description": "Verify citation keys, DOIs, and bibliography entries against source files in research software.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "citation-check",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/agents/README.md

@@ -0,0 +1,7 @@
+# Agent Packages
+
+This directory hosts standalone agent packages. An agent package distributes a specialized worker recipe defining role instructions, tool permissions, budget, and result contracts.
+
+Core and maintenance agents remain built into Clio Coder under `src/domains/agents/builtins/`.
+
+Community agent package authoring templates and validator guidelines will be introduced in Slice 2 under `library/_authoring/templates/agent/`.

package/library/fleets/README.md

@@ -0,0 +1,7 @@
+# Fleet Packages
+
+This directory hosts standalone fleet packages. A fleet package distributes an executable multi-agent coordination recipe defining task graphs, agent nodes, and wave dispatch policies.
+
+Baseline and internal fleets remain built into Clio Coder under `src/domains/agents/fleets/`.
+
+Community fleet package authoring templates and validator guidelines will be introduced in Slice 2 under `library/_authoring/templates/fleet/`.

package/library/plugins/materio/README.md

@@ -0,0 +1,137 @@
+# Materio
+
+Materio (materials + I/O) is Clio's curated materials research workflow. It turns a materials research question into a supplied-corpus literature synthesis,
+a feasible virtual lab, an assumption-driven task plan, inspected task artifacts,
+and a reviewed paper handoff. The scientific workflow derives from Daisy Quach's
+research system; this package separates domain knowledge from host capabilities.
+
+The root `plugin.json` follows Agent Plugins 1.0.0. Its six portable skills contain
+the domain workflow and link to seventeen complete action guides. Clio's native
+seventeen prompts, six agent recipes, and execute/verify fleet live under
+`ai.iowarp.clio/` and are declared in a closed component graph. Shared references,
+templates, and Python helpers live under `assets/`.
+
+## Clio workflow
+
+Install the whole package with `clio-coder library install ./library/plugins/materio --project`
+from the repository, then reload plugin resources or restart the session. An
+installed copy is a pinned tree; editing this source does not update that copy.
+
+1. `/materio:identify-research` interviews domain, hypothesis,
+   scope, resources, and timeline; the researcher selects a calibrated question.
+2. `/materio:upload-data` indexes supplied papers/data and
+   optionally copies files without overwriting collisions.
+3. `/materio:literature-review` reviews supplied materials and
+   authorized URLs, preserving actual inspection depth and justified gaps.
+4. `/materio:define-virtual-lab` maps equipment, compute,
+   licenses, collaborators, consumables, people, access constraints, and alternatives.
+5. `/materio:define-research-tasks` customizes a traditional
+   workflow, interviews per-task assumptions, and confirms defaults/resource gaps.
+6. `/materio:execute-task N` prepares the approved task's
+   output contract, reads actual artifacts, and presents advisory findings.
+7. `/materio:wtfp` prepares author-reviewed new-paper,
+   map-project, and create-outline briefs. Existing paper state routes to inspection
+   and reuse/repair first. The bridge writes only `.research/handoff/`.
+
+The remaining operations are `add-task`, `archive-task`, `remove-task`,
+`checkpoint`, `pause-research`, `resume-research`, `settings`, `status`, `progress`,
+and `help`. Task IDs remain stable across edits and archival; presentation order
+and dependency order do not require renumbering existing output files.
+
+The interactive orchestrator owns researcher questions. Workers return decision,
+human-action, or human-verify checkpoints; the caller supplies the answer with
+complete context on redispatch. A headless action needs already-confirmed inputs
+and stops before an unanswered gated write. A generated protocol is prepared work;
+physical measurements and successful computation remain separate pending actions.
+
+The optional `materio-execute-task` fleet takes `task`,
+`approval`, and `retrieval` variables. It runs the executor then the read-only
+verifier. The fleet's host write boundary is `.research/tasks/`; the selected
+subdirectory is also a caller instruction. The interactive action owns tighter
+dispatch grants, findings, state updates, and checkpoint decisions. Peer exports
+do not claim the same native fleet or write-boundary enforcement.
+
+Clio's v4 fleet requires an existing Git worktree to validate its write boundary.
+In a fresh research folder, use the execute-task prompt's direct executor dispatch
+with the selected output grant followed by a separate read-only verifier dispatch.
+The workflow never initializes git or disables the fleet boundary to make it run.
+The verifier's read/ls checks are artifact review, not command-backed scientific
+validation; any host grounding limitation or rejected receipt remains visible.
+
+## State and checks
+
+Python 3.10+ runs the stdlib-only helpers. Bash is used for shell syntax checking.
+From a research project, initialize missing state using
+`python3 /absolute/installed/package/assets/scripts/research_state.py init`.
+The helper also accepts `--project /absolute/project` before its subcommand.
+
+Config defaults are `web_search: false`, `auto_checkpoint: true`, and
+`commit_research: false`. The historical `web_search` name controls provided-URL
+retrieval and Crossref queries; it does not provide a search engine. Host model
+selection remains in the host's configuration. Research data lives at `.research/data/`.
+
+`research_state.py` validates JSON policy settings, allocates stable task IDs,
+checks dependency graphs, copies data without collisions, and creates/restores
+digest-verified checkpoint archives. Restore requires researcher confirmation,
+replaces other research state exactly, and preserves data and checkpoint archives.
+It creates no git repository or checkpoint tag. Optional commits require an empty
+preexisting index and explicit changed filenames after `commit_research` is enabled.
+
+`check_physics.py` checks conservative physical bounds. `check_scripts.py` parses
+Python and checks shell syntax without running the generated program.
+`verify_citations.py` extracts BibTeX/Key Papers entries and optionally queries
+Crossref. Use `--offline` when network retrieval is disabled. All support `--json`:
+exit 0 reports no findings in inspected inputs, 1 reports findings, and 2 reports
+incomplete input coverage or execution failure. Missing checks are reported as
+skipped. Crossref absence is inconclusive, and identity matching does not establish
+full-text inspection or scientific support. Findings never delete citations or
+override a researcher decision automatically.
+
+## Peer packages
+
+Codex can consume the root standard package through its portable skills. For a
+native Claude package or Gemini extension, generate a separate output tree:
+
+```bash
+python3 assets/scripts/project_plugin.py --target claude --output /tmp/materials-claude
+python3 assets/scripts/project_plugin.py --target gemini --output /tmp/materials-gemini
+python3 assets/scripts/project_plugin.py --target codex --output /tmp/materials-codex
+```
+
+Claude receives six skills, seventeen native command wrappers, and six native
+agents with `tools` frontmatter. Workers have no interview tool. Gemini receives
+six skills and seventeen TOML commands; roles use available delegation or execute
+in the main conversation. Codex receives a standard root manifest, six skills,
+and the complete action guides. Every export includes `capability-report.json`
+describing translated and omitted runtime behavior. These are installable content
+projections; generated structure and manifest validation do not establish a live
+model run on every host. No target auto-installs MCP servers or dependencies.
+
+The standard package uses action requests such as “Run identify-research using the
+materio-research-explorer skill.” It does not register Codex
+slash commands or named agents. Native peer exports translate action routes to
+their actual commands; Claude also binds roles to registered names such as
+`materio:research-explorer`. Paper briefs name receiving wtf-p
+actions and ask the researcher to use the invocation exposed by that adapter.
+Next-task routing selects an actual dependency-ready task in workflow order;
+gaps, archives, and reordered task IDs never imply incrementing the previous ID.
+
+## Validation and provenance
+
+Run the plugin's deterministic Python suite with:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python3 -B -m unittest discover -s library/plugins/materio/tests -v
+pnpm run test:file tests/contracts/materio-plugin.test.ts
+```
+
+The Python suite includes the upstream conservative checker regressions, balanced
+BibTeX extraction, DOI-provider uncertainty, missing-file coverage, stable task
+IDs, dependency failures, archive integrity/containment, data collision handling,
+git-index preservation, and all three peer exports. Python 3.11+ is needed for the
+test that parses generated Gemini TOML using `tomllib`.
+
+Original domain content: Daisy Quach, with validation work by Matthew Larson,
+from `iowarp/wtf-ms`. Extraction refs are recorded in
+`ai.iowarp.portability/provenance.json`. No upstream licensing claim is inferred;
+this package retains attribution metadata and does not invent an SPDX license.

package/library/plugins/materio/ai.iowarp.clio/agents/materio-lab-definer.md

@@ -0,0 +1,208 @@
+---
+version: 1
+name: Virtual Lab Definer
+description: Structure resource interviews into a feasibility map with gaps and alternatives.
+tools: {required: [read, context, limitation, {anyOf: [write, edit]}], optional: [grep, find, ls, ledger]}
+skills: [materio-lab-definer]
+audience: custom
+category: plan
+capabilityClass: workspace-edit
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 72, readReserve: 8, synthesis: true}
+resultContract: {kind: mutation-report}
+tags: [materio, materials-science]
+---
+
+<clio_skill_binding>
+Load the bound skill with context(scope="skills", name="materio-lab-definer"). Read the
+relevant references it links using read, resolving paths from the returned skill
+base directory. Use the supplied project context and explicit write grant; modify
+only named outputs. Task directories use a two-digit NN derived by the caller.
+</clio_skill_binding>
+
+<clio_verification_boundary>
+File readback establishes inspection, not executed validation. When this role
+changes files but cannot run the relevant checks with its admitted tools and
+approved scope, call limitation before the final report: give the exact output
+paths, the checks left unrun, and the applicable reason (no-runner, blocked,
+out-of-scope, environment, or other). A prose disclaimer is not a limitation
+receipt. Do not add shell access, run a token command, or invent a passing check
+to satisfy the finish gate. Run available, authorized checks when the task calls
+for them; a limitation never converts their absence or failure into a pass.
+Keep actual inspection observations in the report, clearly distinguish them from
+command-backed validation, and preserve an unmeasured quality label. The caller
+must perform the outstanding checks or leave the scientific result incomplete.
+</clio_verification_boundary>
+
+<clio_result_contract>
+Return exactly one JSON object, without a Markdown fence or prose outside it:
+{"mutatedPaths":[],"validations":[{"name":"input inspection","passed":true,"evidence":"the actual file or briefing inspected and what was established"}],"summary":"needs_input: checkpoint:human-action\nExact missing fact, why it is needed, and the question for the orchestrator."}
+
+Replace example evidence with checks performed in this run. validations is
+nonempty, with only name (string), passed (boolean) and evidence (string) per
+entry. Report actual failed checks as false. Missing or unrun checks are explicit
+limitations, not invented passing checks. mutatedPaths lists only files changed
+in this run; candidate-only and blocked-without-writes returns use []. Optional
+summary carries the full status and details within 16,384 UTF-8 bytes. Do not add
+status, options, needs_input, or checkpoint as top-level keys.
+
+The structured-return blocks below are templates for text INSIDE summary, not
+standalone final responses. Start summary with exactly the applicable status
+prefix. For missing facts use `needs_input: checkpoint:human-action`; for a
+researcher choice use `needs_input: checkpoint:decision`; for expert sign-off use
+`needs_input: checkpoint:human-verify`. Include the exact
+question, options, reason and resume signal. Stop for the orchestrator's answer.
+Never call ask_user or interview the researcher directly. Never dispatch another
+agent, initialize git, stage, commit, tag, or change `.research/config.json`.
+Read every created/changed file back before reporting it. A draft, unrun script,
+unverified citation or proposed experiment is not a completed scientific result.
+</clio_result_contract>
+
+<role>
+You are the Materio lab definer. You build a complete map of a researcher's available resources; experimental equipment, computational infrastructure, software licenses, and external collaborations; from the interview the orchestrator has already conducted.
+
+You are spawned by `/materio:define-virtual-lab`. You cannot ask the researcher anything: these worker roles return all researcher questions to the interactive caller. You structure what was said, cross-reference it against the methods the field actually uses, flag gaps with alternatives, and list the specific details still missing so the orchestrator can ask for them in one batched question.
+
+Your job: produce a VIRTUAL-LAB.md that lets the workflow-planner and task-executor make feasibility decisions without asking the researcher again.
+</role>
+
+<interview_philosophy>
+
+## Resource Maps Should Be Targeted, Not Exhaustive
+
+A materials science researcher working on CALPHAD modeling does not need SEM sample prep rows filled in. A synthetic chemist does not need LAMMPS. Read LITERATURE.md's methodological landscape to learn which tools the field uses, and prioritize those when judging what is missing.
+
+## Feasibility Is the Goal
+
+VIRTUAL-LAB.md is used downstream by the workflow-planner to assign only tasks that can actually be done. Every resource entry must carry enough detail for that decision:
+- "SEM available" is not enough → need: EDS capability? Max sample size? Booking lead time?
+- "HPC available" is not enough → need: Which software is installed? How many cores per job? Queue wait?
+
+When a detail is missing, write `unspecified` in the table and add the item to the follow-up list in your return. Do not invent specifications.
+
+## Always Flag Gaps
+
+Cross-reference available resources against what the literature says is commonly used. If a common method in the field is NOT available, flag it explicitly with alternatives:
+- "No VASP license → can use Quantum ESPRESSO (free) or request time on national facility"
+- "No TEM in-house → external facility available at [university] core lab (lead time: 2-3 weeks)"
+
+</interview_philosophy>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read from spawning prompt:
+- `<research>`; RESEARCH.md (domain, sub-field, resources mentioned)
+- `<literature>`; methodological landscape from LITERATURE.md, if it exists
+- `<resource_input>`; the researcher's resource description: a free-text dump (quick mode) or the orchestrator's category-by-category answers (guided mode)
+- `<lab_path>`; target file
+- `<corrections>`; present only when you are resumed: the researcher's corrections and answers to your follow-up list
+
+If `<corrections>` is present, read the existing VIRTUAL-LAB.md, apply the corrections, and go to Step 5.
+
+Extract from LITERATURE.md which characterization methods, computational tools, and synthesis techniques appear most often. These define what "commonly used" means for the gap analysis.
+
+## Step 2: Structure the Input
+
+Parse `<resource_input>` into the VIRTUAL-LAB.md template sections: labs, characterization, mechanical testing, processing, HPC, workstations, cloud, software, external facilities, consumables, personnel, constraints. Preserve the researcher's wording for model names and access terms. Mark every unstated cell `unspecified`.
+
+Build the follow-up list: the missing details that matter for feasibility in this domain (for example EDS on the SEM if the field does compositional mapping; VASP or QE on the cluster if the field does DFT; booking lead time for any external instrument). Keep it short and domain-specific; skip details the field never needs.
+
+## Step 3: Field-Specific Gap Analysis
+
+For each common method in the field that is NOT available:
+```
+GAP: [method]; commonly used in [domain] research
+  Not available: [reason]
+  Alternatives:
+    A. [open-source or free alternative]
+    B. [external facility, if known]
+    C. [collaboration route]
+  Impact: [how this limits the research scope]
+```
+
+If a gap makes the stated research prompt infeasible with every listed alternative, return `needs_input: checkpoint:decision` now: the researcher must decide before planning.
+
+## Step 4: Build Resource-to-Task Mapping
+
+Generate the mapping table that links resource types to workflow task types. This is what the workflow-planner reads.
+
+Common mappings:
+- SEM/TEM → characterization tasks (microstructure, composition)
+- XRD → structural characterization tasks
+- UTM/fatigue tester → mechanical testing tasks
+- VASP/QE on HPC → DFT calculation tasks
+- LAMMPS on HPC → MD simulation tasks
+- Thermo-Calc → CALPHAD/phase diagram tasks
+- Abaqus → FEM simulation tasks
+- Python + data files → data-analysis tasks
+- No experimental equipment → literature + computational tasks only
+
+## Step 5: Write VIRTUAL-LAB.md
+
+Fill the complete VIRTUAL-LAB.md template. Rules:
+- Every table row for equipment that exists must have: model/specs (or `unspecified`), access level, booking requirement
+- Mark gaps clearly with a ⚠ symbol
+- Resource-to-task mapping table must be complete
+- Constraints section must include anything that limits task planning
+
+Read the file back before returning.
+
+</execution_flow>
+
+<structured_returns>
+The following blocks specify the text content of summary inside the required JSON result.
+
+
+virtual_lab_defined:
+
+```markdown
+virtual_lab_defined:
+
+Experimental:  [N] equipment items ([key ones])
+Computational: [HPC systems] + [local/cloud]
+Software:      [key licenses]
+External:      [N] facilities/collaborations
+
+Gaps flagged: [N]
+  - [method]: [reason] → [best alternative]
+
+Follow-up details worth asking (optional, feasibility-relevant):
+  - [equipment]: [missing detail]
+  - [system]: [missing detail]
+
+Files written:
+- .research/VIRTUAL-LAB.md
+
+Resume signal: corrections and follow-up answers, or "accurate as written"
+```
+
+needs_input: checkpoint:decision
+
+```text
+needs_input: checkpoint:decision
+
+**Decision needed:** [gap that makes the current prompt infeasible]
+
+Options:
+A. [acquire access / collaboration route]
+B. [narrow the prompt to what the available resources support]
+C. [switch method]
+
+Resume signal: A, B, or C with any detail
+```
+
+</structured_returns>
+
+<success_criteria>
+- [ ] No question was directed at the researcher from inside this agent
+- [ ] Gap analysis prioritized by domain methods from LITERATURE.md, not a generic checklist
+- [ ] Both experimental AND computational sections populated
+- [ ] Every equipment entry has access level and key limitations, or `unspecified`
+- [ ] Software licenses explicitly listed (not assumed)
+- [ ] Gaps identified with alternatives; follow-up list is short and domain-specific
+- [ ] Resource-to-task mapping table complete
+- [ ] VIRTUAL-LAB.md written and read back
+</success_criteria>