@iowarp/clio-coder 0.4.6 → 0.4.7

package/library/_authoring/templates/agent/agents/benchmark-scout.md

@@ -0,0 +1,30 @@
+---
+version: 1
+name: Benchmark Scout
+description: Inspect computational benchmarks, scaling configurations, and performance harnesses in research codebases.
+tools:
+  required: [read, context]
+  optional: [grep, find, ls]
+skills: []
+audience: custom
+category: science
+capabilityClass: read-only
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 32, readReserve: 4, synthesis: true}
+resultContract: {kind: scout-report}
+tags: [benchmarks, hpc, performance, science]
+---
+
+# Benchmark Scout
+
+You are Benchmark Scout, a read-only specialist for discovering, analyzing, and characterizing performance benchmarks in scientific computing and research software.
+
+## Mission
+Inspect benchmark harnesses, scaling runs (strong and weak scaling), and measurement scripts without modifying the workspace or executing unverified code.
+
+## Procedure
+1. **Discover harnesses**: Locate benchmark definitions, Slurm job scripts, MPI run configurations, and test inputs.
+2. **Analyze configurations**: Check problem sizes, grid resolutions, thread pinning, and environment variables.
+3. **Document baselines**: Summarize reported metrics (throughput, memory bandwidth, latency, speedup).
+4. **Deliver scout report**: Return structured findings under the scout-report contract.

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

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "benchmark-scout",
+	"version": "1.0.0",
+	"description": "Inspect computational benchmarks, scaling configurations, and performance harnesses.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "agent",
+			"resources": {
+				"agents": "agents"
+			},
+			"components": [
+				{
+					"kind": "agent",
+					"id": "benchmark-scout",
+					"path": "agents/benchmark-scout.md"
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/fleet/README.md

@@ -0,0 +1,29 @@
+# Pipeline Review Fleet Template
+
+This template demonstrates a valid standalone **fleet** package for Clio Coder.
+
+## Package Structure
+
+```text
+pipeline-review/
+  README.md                     # Documentation (outside resource root)
+  plugin.json                   # Portable manifest declaring kind: fleet
+  fleets/
+    pipeline-review.md          # Multi-agent coordination contract
+```
+
+> **Important**: Place `README.md` at the package root, never inside the `fleets/` resource root. Single-kind packages expose exactly one public candidate in their declared resource directory.
+
+## Graph and Step Semantics
+
+- **Version**: Version 1 or higher (v4 introduces strict write boundaries).
+- **Steps**: Each step specifies `id`, `agent`, `scope`, and `dependencies`.
+- **Graph Validity**: Steps must form a directed acyclic graph (DAG) without cycles or unknown dependencies.
+- **Prompt Body**: Uses strict `{{var}}` interpolation; all variables must be supplied at invocation (e.g. `--var pipeline=configs/pipeline.yaml`).
+- **Prerequisites**: Fleets that reference core built-in agents (e.g., `scout`, `verifier`) should clearly document these dependencies in their body.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

package/library/_authoring/templates/fleet/fleets/pipeline-review.md

@@ -0,0 +1,31 @@
+---
+version: 1
+name: pipeline-review
+description: Coordinate a two-stage inspection of scientific pipeline data definitions and validation assertions.
+steps:
+  - id: inspect-pipeline
+    agent: scout
+    scope: readonly
+    dependencies: []
+  - id: verify-invariants
+    agent: verifier
+    scope: readonly
+    dependencies: [inspect-pipeline]
+maxWorkers: 2
+onFailure: stop
+---
+
+Review the scientific pipeline specified at: {{pipeline}}.
+
+## Workflow Stages
+
+1. **inspect-pipeline (`scout`)**:
+   Inspect data schemas, pipeline steps, dependency declarations, and configuration inputs in the target pipeline.
+2. **verify-invariants (`verifier`)**:
+   Independently verify that numerical tolerances, sanity checks, regression tests, and invariant assertions are defined and bounded.
+
+## Prerequisites & Environment Requirements
+
+- **Core Agents**: This fleet coordinates the built-in `scout` and `verifier` recipes provided by Clio (`src/domains/agents/builtins/`).
+- **Configuration**: Requires a configured read-only model target with context support.
+- **Variables**: The caller must supply the `{{pipeline}}` variable naming the pipeline configuration or script path (e.g. `--var pipeline=configs/pipeline.yaml`).

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

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "pipeline-review",
+	"version": "1.0.0",
+	"description": "Multi-agent coordination recipe for reviewing scientific data pipelines.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "fleet",
+			"resources": {
+				"fleets": "fleets"
+			},
+			"components": [
+				{
+					"kind": "fleet",
+					"id": "pipeline-review",
+					"path": "fleets/pipeline-review.md"
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/plugin/README.md

@@ -0,0 +1,37 @@
+# Data Curation Plugin Template
+
+This template demonstrates a valid composite **plugin** bundle for Clio Coder.
+
+## Package Structure
+
+```text
+data-curation/
+  README.md                                 # Documentation
+  plugin.json                               # Manifest declaring bundle resources & components
+  assets/
+    curation-guide.md                       # Supporting reference asset (component:resource:guidelines)
+  skills/
+    dataset-curation/
+      SKILL.md                              # Bound skill
+      evals.md                              # Skill evaluation scenarios
+  agents/
+    data-curator.md                         # Agent binding dataset-curation skill
+  prompts/
+    inspect-dataset.md                      # Prompt requiring data-curator agent
+```
+
+## Manifest Declarations
+
+- **Resources**: Declares ordinary `skills`, `agents`, and `prompts` directories under `extensions["ai.iowarp.clio"]`.
+- **Components**:
+  - `resource:guidelines` -> `assets/curation-guide.md`
+  - `skill:dataset-curation` -> `skills/dataset-curation/SKILL.md` (requires `resource:guidelines`)
+  - `agent:data-curator` -> `agents/data-curator.md` (requires `skill:dataset-curation`)
+  - `prompt:inspect-dataset` -> `prompts/inspect-dataset.md` (requires `agent:data-curator`)
+- **Acyclic References**: Component dependencies form a clean DAG.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

package/library/_authoring/templates/plugin/agents/data-curator.md

@@ -0,0 +1,31 @@
+---
+version: 1
+name: Data Curator
+description: Inspect and curate scientific datasets against FAIR data guidelines and metadata schemas.
+tools:
+  required: [read, context]
+  optional: [grep, find, ls]
+skills: [dataset-curation]
+audience: custom
+category: science
+capabilityClass: read-only
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 32, readReserve: 4, synthesis: true}
+resultContract: {kind: scout-report}
+tags: [data, fair, curation, science]
+---
+
+# Data Curator
+
+You are Data Curator, a read-only specialist for reviewing scientific datasets and confirming compliance with FAIR principles.
+
+Use the bound `dataset-curation` skill to inspect dataset organization, and check the curation reference at ${component:resource:guidelines}.
+
+## Mission
+Inspect dataset layout, format standards (NetCDF, HDF5, CSV, Parquet), metadata schemas, and licensing documentation.
+
+## Procedure
+1. Check for standard dataset metadata descriptors (e.g. README.md, datapackage.json, or CF conventions).
+2. Validate column definitions, units, and missing value encodings against ${component:resource:guidelines}.
+3. Return findings conforming to the scout-report contract.

package/library/_authoring/templates/plugin/assets/curation-guide.md

@@ -0,0 +1,22 @@
+# Dataset Curation Guide
+
+Guidelines for curating and validating scientific research datasets.
+
+## FAIR Principles Checklist
+
+1. **Findable**:
+   - Unique persistent identifier or stable local path.
+   - Comprehensive metadata descriptor (e.g. `datapackage.json` or `README.md`).
+2. **Accessible**:
+   - Clear retrieval instructions and standard open file formats (CSV, Parquet, NetCDF, HDF5, JSON).
+3. **Interoperable**:
+   - Documented vocabulary, standard units (SI), and recognized domain conventions (e.g., Climate and Forecast CF conventions).
+4. **Reusable**:
+   - Explicit license specification (e.g., CC-BY-4.0, CC0, Apache-2.0).
+   - Data provenance and generation parameters recorded.
+
+## Quality Invariants
+
+- No unencoded NaN or infinite values without documented sentinel symbols.
+- Timestamp formats follow ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
+- Geospatial coordinates follow WGS84 with explicit latitude/longitude bounds.

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

@@ -0,0 +1,42 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "data-curation",
+	"version": "1.0.0",
+	"description": "Scientific dataset curation bundle with curation skill, curator agent, and inspection prompt.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"resources": {
+				"skills": "skills",
+				"agents": "agents",
+				"prompts": "prompts"
+			},
+			"components": [
+				{
+					"kind": "resource",
+					"id": "guidelines",
+					"path": "assets/curation-guide.md"
+				},
+				{
+					"kind": "skill",
+					"id": "dataset-curation",
+					"path": "skills/dataset-curation/SKILL.md",
+					"requires": ["resource:guidelines"]
+				},
+				{
+					"kind": "agent",
+					"id": "data-curator",
+					"path": "agents/data-curator.md",
+					"requires": ["skill:dataset-curation"]
+				},
+				{
+					"kind": "prompt",
+					"id": "inspect-dataset",
+					"path": "prompts/inspect-dataset.md",
+					"requires": ["agent:data-curator"]
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/plugin/prompts/inspect-dataset.md

@@ -0,0 +1,15 @@
+---
+description: Prompt to inspect a scientific dataset directory for FAIR compliance and metadata completeness.
+argument-hint: "[dataset-path]"
+---
+
+Inspect the scientific dataset at: $1
+
+Refer to curation guidelines in ${pluginRoot}/assets/curation-guide.md and use the data-curator agent.
+
+Evaluate:
+1. File structure and format consistency.
+2. Presence of required metadata, license, and provenance documentation.
+3. Missing-value encodings and schema clarity.
+
+Additional instructions: $ARGUMENTS

package/library/_authoring/templates/plugin/skills/dataset-curation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: dataset-curation
+description: Guidelines and verification procedures for scientific dataset curation, schema compliance, and FAIR data standards.
+version: 1.0.0
+license: Apache-2.0
+clio-coder:
+  registry-id: dataset-curation
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/_authoring/templates/plugin
+  provenance: designed
+  eval-status: scenarios-recorded
+triggers:
+  - curate dataset
+  - fair data check
+  - validate dataset schema
+  - dataset curation
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+---
+
+# Dataset Curation Skill
+
+Guide for inspecting, curating, and validating scientific datasets against FAIR data standards.
+
+## Reference Guidelines
+
+Consult ${pluginRoot}/assets/curation-guide.md for domain quality invariants and metadata checklists.
+
+## Procedure
+
+1. **Scan Dataset Directory**: Use `ls` and `find` to map all data files and metadata descriptors.
+2. **Review Metadata**: Verify existence of licensing, provenance records, and format declarations.
+3. **Inspect Content**: Verify column names, missing-value sentinels, and unit definitions against the curation guidelines.
+4. **Compile Assessment**: Report missing fields, format violations, and recommendations for FAIR compliance.

package/library/_authoring/templates/plugin/skills/dataset-curation/evals.md

@@ -0,0 +1,17 @@
+# Evals: dataset-curation
+
+Evaluation scenarios for dataset curation skill.
+
+## Scenario: missing-fair-metadata
+
+### Baseline (without skill)
+- Context: Dataset folder containing `data.csv` with no license or column description.
+- Task: Check dataset for publication readiness.
+- Outcome: General observations, omits structured FAIR criteria.
+
+### Treatment (with skill)
+- Prompt: `/skill dataset-curation Check dataset at data/ for FAIR compliance`
+- Expected Evidence:
+  - References FAIR criteria from `assets/curation-guide.md`.
+  - Flags absence of license and schema documentation.
+  - Identifies missing unit definitions in CSV headers.

package/library/_authoring/templates/prompt/README.md

@@ -0,0 +1,28 @@
+# Paper Summary Prompt Template
+
+This template demonstrates a valid standalone **prompt** package for Clio Coder.
+
+## Package Structure
+
+```text
+paper-summary/
+  README.md                     # Documentation (outside resource root)
+  plugin.json                   # Portable manifest declaring kind: prompt
+  prompts/
+    paper-summary.md            # Reusable prompt template
+```
+
+> **Important**: Keep `README.md` at the package root, never inside `prompts/`. Single-kind packages expose exactly one public candidate in their declared resource directory.
+
+## Invocation and Parameters
+
+- **Invocation Name**: Derived from the file path relative to `prompts/`. Here, `prompts/paper-summary.md` exposes `/paper-summary`.
+- **Positional Arguments**: `$1`, `$2`, etc. are replaced by space-separated positional arguments passed to the slash command.
+- **Full Arguments String**: `$ARGUMENTS` expands to the full remainder argument string.
+- **Optional Argument Hint**: The frontmatter `argument-hint: "[paper-path-or-url]"` informs interactive autocomplete of expected inputs.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

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

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "paper-summary",
+	"version": "1.0.0",
+	"description": "Structured prompt template for summarizing scientific papers and research methodologies.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "prompt",
+			"resources": {
+				"prompts": "prompts"
+			},
+			"components": [
+				{
+					"kind": "prompt",
+					"id": "paper-summary",
+					"path": "prompts/paper-summary.md"
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/prompt/prompts/paper-summary.md

@@ -0,0 +1,26 @@
+---
+description: Summarize a scientific paper with research question, methodology, key findings, and threats to validity.
+argument-hint: "[paper-path-or-url]"
+---
+
+Summarize the scientific paper located at: $1
+
+Follow this structured format:
+
+## 1. Research Problem & Objective
+- What specific research question does this work address?
+- Why is this problem significant in scientific or computational practice?
+
+## 2. Methodology & Approach
+- What experimental, computational, or theoretical methodology was employed?
+- What datasets, benchmarks, or HPC hardware environments were evaluated?
+
+## 3. Key Findings & Contributions
+- Summarize the primary quantitative and qualitative results.
+- Highlight measured speedups, accuracy improvements, or scaling limits.
+
+## 4. Threats to Validity & Limitations
+- What are the documented or observed limitations?
+- What replication obstacles exist?
+
+Additional instructions: $ARGUMENTS

package/library/_authoring/templates/skill/README.md

@@ -0,0 +1,24 @@
+# Citation Check Skill Template
+
+This template demonstrates a valid standalone **skill** package for Clio Coder.
+
+## Package Structure
+
+```text
+citation-check/
+  README.md         # Documentation (outside resource root)
+  plugin.json       # Portable manifest declaring kind: skill
+  SKILL.md          # Skill instructions and metadata
+  evals.md          # Evaluation scenarios
+```
+
+## How to Use This Template
+
+1. Copy this directory into your project or repository.
+2. Rename the package in `plugin.json` and `SKILL.md`.
+3. Update the description, triggers, and procedure in `SKILL.md`.
+4. Add baseline/treatment scenarios in `evals.md`.
+5. Validate your package:
+   ```bash
+   clio-coder library validate .
+   ```

package/library/_authoring/templates/skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: citation-check
+description: Verify citation keys, DOIs, and bibliography entries against source files in research software. Load when checking academic references, bibtex formatting, or paper citations.
+version: 1.0.0
+license: Apache-2.0
+clio-coder:
+  registry-id: citation-check
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/_authoring/templates/skill
+  provenance: designed
+  eval-status: scenarios-recorded
+triggers:
+  - citation check
+  - verify citations
+  - check bibliography
+  - validate doi
+allowed-tools:
+  - read
+  - grep
+  - find
+---
+
+# Citation Check
+
+Verify citation keys, Digital Object Identifiers (DOIs), and bibliography entries in research codebases and papers.
+
+## When to load this skill
+
+Load when:
+- Reviewing LaTeX documents, markdown papers, or documentation containing citation keys (e.g. `\cite{...}`, `[@key]`).
+- Validating BibTeX `.bib` files for syntax errors, missing fields, or duplicate keys.
+- Checking that cited DOIs resolve to expected formats.
+
+## Procedure
+
+1. **Locate citation files**: Search for `.bib` files and references in the workspace using `find`.
+2. **Inspect citation keys**: Grep for citation markers in manuscript or documentation source files.
+3. **Cross-reference**: Ensure every cited key exists in the corresponding `.bib` file. Report unreferenced bibliography entries as warnings and missing keys as errors.
+4. **DOI Verification**: Verify DOIs match the standard format `10.XXXX/...` and link to valid literature sources.
+5. **Report findings**: Output a structured summary containing verified keys, missing citations, and formatting issues.

package/library/_authoring/templates/skill/evals.md

@@ -0,0 +1,30 @@
+# Evals: citation-check
+
+Scenarios recorded for the citation-check skill.
+
+## Scenario: missing-citation-key
+
+### Baseline (without skill)
+- Context: Workspace with `paper.tex` citing `\cite{smith2024}` and `references.bib` containing only `doe2023`.
+- Task: Verify citations in `paper.tex`.
+- Outcome: General unstructured commentary, potential hallucination of reference existence.
+
+### Treatment (with skill)
+- Prompt: `/skill citation-check Check citations in paper.tex against references.bib`
+- Expected Evidence:
+  - Identifies missing citation key `smith2024` in `references.bib`.
+  - Reports `doe2023` as an unreferenced entry.
+  - Leaves workspace files unmodified.
+
+## Scenario: doi-format-validation
+
+### Baseline (without skill)
+- Context: `references.bib` with invalid DOI string `doi = {https://dx.doi.org/invalid}`.
+- Task: Validate DOI formatting in `references.bib`.
+- Outcome: Misses malformed DOI format or accepts invalid prefix.
+
+### Treatment (with skill)
+- Prompt: `/skill citation-check Validate DOI formats in references.bib`
+- Expected Evidence:
+  - Flags invalid DOI prefix.
+  - Recommends canonical DOI format `10.XXXX/...`.

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/`.