@yeyuan98/opencode-bioresearcher-plugin 1.3.1 → 1.4.1

package/dist/skills/bioresearcher-core/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: bioresearcher-core
+description: Core patterns and utilities for BioResearcher skills
+allowedTools:
+  - Read
+  - Write
+  - Bash
+  - jsonExtract
+  - jsonValidate
+  - jsonInfer
+  - blockingTimer
+  - calculator
+  - tableCreateFile
+  - tableAppendRows
+  - Question
+  - Task
+---
+
+# BioResearcher Core
+
+This skill provides reusable patterns and utilities for BioResearcher skills.
+
+## Quick Start
+
+### Step 1: Load This Skill
+```
+skill bioresearcher-core
+```
+
+### Step 2: Extract Skill Path
+From the `<skill_files>` section in the skill tool output, extract the `<skill_path>` value.
+
+### Step 3: Use Resources
+- Read pattern: `Read <skill_path>/patterns/retry.md`
+- Run script: `uv run python <skill_path>/python/template.py ...`
+
+## Available Patterns
+
+### Workflow Control
+- `patterns/retry.md` - Retry with backoff using blockingTimer
+- `patterns/progress.md` - Progress tracking
+- `patterns/subagent-waves.md` - Parallel subagent processing
+- `patterns/shell-commands.md` - Unix/Windows command generation
+- `patterns/user-confirmation.md` - User confirmation
+
+### Data Handling
+- `patterns/json-tools.md` - Using jsonExtract/jsonValidate/jsonInfer
+- `patterns/table-tools.md` - Combining outputs with table tools
+- `patterns/data-exchange.md` - Main/subagent data exchange protocol
+- `patterns/calculator.md` - In-workflow calculations
+
+## Python Utilities
+- `python/template.md` - Template generation documentation
+
+## Direct Tools (No Loading Needed)
+
+These tools are always available without loading pattern files:
+
+### JSON Tools
+- `jsonExtract` - Extract JSON from files (handles markdown code blocks, raw JSON)
+- `jsonValidate` - Validate JSON against schemas (Draft-4, Draft-7, Draft-2020-12)
+- `jsonInfer` - Infer schemas from JSON data
+
+### Utility Tools
+- `blockingTimer` - Blocking delays (0-300 seconds)
+- `calculator` - Mathematical expressions (+, -, *, /, ^, brackets)
+
+### Table Tools
+- `tableCreateFile` - Create Excel/CSV files from data
+- `tableAppendRows` - Append rows to existing tables
+
+## Tool Signatures
+
+### jsonExtract
+```
+jsonExtract(file_path: string, return_all: boolean = false)
+Returns: { success, data, metadata: { method, dataType, fileSize } }
+```
+
+### jsonValidate
+```
+jsonValidate(data: string, schema: string)
+Returns: { success, valid, errors?, metadata: { errorCount, schemaFeatures } }
+```
+
+### jsonInfer
+```
+jsonInfer(data: string, strict: boolean = false)
+Returns: { success, data: JSONSchema, metadata: { inferredType, strictMode } }
+```
+
+### blockingTimer
+```
+blockingTimer(delay: number)
+Returns: "Timer completed: waited X seconds (actual elapsed: Ys)"
+```
+
+### calculator
+```
+calculator(formula: string, precision: number = 3)
+Returns: { formula, result }
+```
+
+### tableCreateFile
+```
+tableCreateFile(file_path: string, sheet_name: string = "Sheet1", data: array)
+Returns: { success, file_path, sheet_name, rows_created }
+```
+
+### tableAppendRows
+```
+tableAppendRows(file_path: string, sheet_name: string?, rows: array)
+Returns: { success, rows_appended }
+```
+
+## When to Use Each Pattern
+
+| Use Case | Pattern File |
+|----------|-------------|
+| Network/API failures | `patterns/retry.md` |
+| Batch processing progress | `patterns/progress.md` |
+| Parallel subagent execution | `patterns/subagent-waves.md` |
+| Cross-platform commands | `patterns/shell-commands.md` |
+| Destructive operations | `patterns/user-confirmation.md` |
+| JSON data extraction | `patterns/json-tools.md` |
+| Combining batch outputs | `patterns/table-tools.md` |
+| Subagent communication | `patterns/data-exchange.md` |
+| Progress calculations | `patterns/calculator.md` |

package/dist/skills/bioresearcher-core/examples/contexts.json

@@ -0,0 +1,29 @@
+[
+  {
+    "file_path": "/absolute/path/to/data.xlsx",
+    "sheet_name": "Sheet1",
+    "batch_number": 1,
+    "row_start": 2,
+    "row_end": 31,
+    "output_file": "./outputs/batch001.md",
+    "instructions_json": "{\n  \"species\": \"Species classification: Tier1/Tier2/NA\",\n  \"topic\": \"Main topic: Oncology/Immunology/General Biology/Others\"\n}"
+  },
+  {
+    "file_path": "/absolute/path/to/data.xlsx",
+    "sheet_name": "Sheet1",
+    "batch_number": 2,
+    "row_start": 32,
+    "row_end": 61,
+    "output_file": "./outputs/batch002.md",
+    "instructions_json": "{\n  \"species\": \"Species classification: Tier1/Tier2/NA\",\n  \"topic\": \"Main topic: Oncology/Immunology/General Biology/Others\"\n}"
+  },
+  {
+    "file_path": "/absolute/path/to/data.xlsx",
+    "sheet_name": "Sheet1",
+    "batch_number": 3,
+    "row_start": 62,
+    "row_end": 91,
+    "output_file": "./outputs/batch003.md",
+    "instructions_json": "{\n  \"species\": \"Species classification: Tier1/Tier2/NA\",\n  \"topic\": \"Main topic: Oncology/Immunology/General Biology/Others\"\n}"
+  }
+]

package/dist/skills/bioresearcher-core/examples/data-exchange-example.md

@@ -0,0 +1,303 @@
+# Data Exchange Example
+
+This example demonstrates the complete main/subagent data exchange workflow.
+
+## Scenario
+
+Main agent needs to process a large table (90 rows) in 3 batches of 30 rows each.
+
+## Step 1: Main Agent Creates Prompt Files
+
+### Template (subagent_template.md)
+
+```markdown
+# Batch Processing Task
+
+## Input
+- File: {file_path}
+- Sheet: {sheet_name}
+- Rows: {row_start} to {row_end}
+
+## Output Format
+Write JSON to: {output_file}
+
+```json
+{
+  "batch_number": {batch_number},
+  "row_count": <integer>,
+  "summaries": [
+    {
+      "row_number": <integer>,
+      "status": "<success/failure>",
+      "result": "<string>"
+    }
+  ]
+}
+```
+```
+
+### Generate Prompts
+
+```bash
+uv run python <skill_path>/python/template.py generate-batches \
+  --template subagent_template.md \
+  --contexts batch_contexts.json \
+  --output-dir ./prompts \
+  --filename-pattern "batch{index:03d}.md"
+```
+
+### Contexts (batch_contexts.json)
+
+```json
+[
+  {
+    "file_path": "/data/table.xlsx",
+    "sheet_name": "Data",
+    "batch_number": 1,
+    "row_start": 2,
+    "row_end": 31,
+    "output_file": "./outputs/batch001.md"
+  },
+  {
+    "file_path": "/data/table.xlsx",
+    "sheet_name": "Data",
+    "batch_number": 2,
+    "row_start": 32,
+    "row_end": 61,
+    "output_file": "./outputs/batch002.md"
+  },
+  {
+    "file_path": "/data/table.xlsx",
+    "sheet_name": "Data",
+    "batch_number": 3,
+    "row_start": 62,
+    "row_end": 91,
+    "output_file": "./outputs/batch003.md"
+  }
+]
+```
+
+## Step 2: Main Agent Launches Subagents
+
+### Wave 1 (All 3 batches)
+
+```
+task(
+  subagent_type="general",
+  description="Process batch 001",
+  prompt="Read your prompt from ./prompts/batch001.md and perform the task exactly as written."
+)
+
+task(
+  subagent_type="general",
+  description="Process batch 002",
+  prompt="Read your prompt from ./prompts/batch002.md and perform the task exactly as written."
+)
+
+task(
+  subagent_type="general",
+  description="Process batch 003",
+  prompt="Read your prompt from ./prompts/batch003.md and perform the task exactly as written."
+)
+```
+
+## Step 3: Subagent Processes and Writes Output
+
+### Subagent reads prompt
+```
+Read ./prompts/batch001.md
+```
+
+### Subagent processes data
+```
+tableGetRange(file_path="/data/table.xlsx", sheet_name="Data", range="A2:Z31")
+```
+
+### Subagent writes output (./outputs/batch001.md)
+
+```json
+{
+  "batch_number": 1,
+  "row_count": 30,
+  "summaries": [
+    {"row_number": 2, "status": "success", "result": "Processed OK"},
+    {"row_number": 3, "status": "success", "result": "Processed OK"},
+    {"row_number": 4, "status": "failure", "result": "Missing data"},
+    "..."
+  ]
+}
+```
+
+## Step 4: Main Agent Validates Outputs
+
+### Extract JSON
+
+```
+jsonExtract(file_path="./outputs/batch001.md")
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "data": {
+    "batch_number": 1,
+    "row_count": 30,
+    "summaries": [...]
+  },
+  "metadata": {
+    "method": "object",
+    "dataType": "object"
+  }
+}
+```
+
+### Infer Schema from First Output
+
+```
+jsonInfer(
+  data='{"batch_number": 1, "row_count": 30, "summaries": [{"row_number": 2, "status": "success", "result": "OK"}]}',
+  strict=true
+)
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "data": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "batch_number": {"type": "integer"},
+      "row_count": {"type": "integer"},
+      "summaries": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "row_number": {"type": "integer"},
+            "status": {"type": "string"},
+            "result": {"type": "string"}
+          },
+          "required": ["row_number", "status", "result"]
+        }
+      }
+    },
+    "required": ["batch_number", "row_count", "summaries"]
+  }
+}
+```
+
+### Validate Other Outputs
+
+```
+jsonValidate(
+  data='{"batch_number": 2, "row_count": 30, "summaries": [...]}',
+  schema='<inferred_schema>'
+)
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "valid": true,
+  "data": {...}
+}
+```
+
+## Step 5: Main Agent Combines Outputs
+
+### Collect All Summaries
+
+```
+all_rows = []
+
+for batch in [1, 2, 3]:
+    result = jsonExtract(file_path=f"./outputs/batch{batch:03d}.md")
+    if result.success:
+        all_rows.extend(result.data["summaries"])
+```
+
+### Create Combined Excel
+
+```
+tableCreateFile(
+  file_path="./combined_results.xlsx",
+  sheet_name="Results",
+  data=all_rows
+)
+```
+
+## Complete Workflow Summary
+
+1. **Template**: Defines output format with schema
+2. **Contexts**: Provides batch-specific values
+3. **Generation**: Creates prompt files from template + contexts
+4. **Subagents**: Read prompts, process, write JSON outputs
+5. **Extraction**: jsonExtract parses JSON from outputs
+6. **Validation**: jsonValidate ensures schema compliance
+7. **Combination**: tableCreateFile merges all results
+
+## Error Handling Examples
+
+### Missing Output File
+
+```
+jsonExtract(file_path="./outputs/batch002.md")
+```
+
+Returns:
+```json
+{
+  "success": false,
+  "error": {
+    "code": "FILE_NOT_FOUND",
+    "message": "File not found: ./outputs/batch002.md"
+  }
+}
+```
+
+### Invalid JSON in Output
+
+```
+jsonExtract(file_path="./outputs/batch003.md")
+```
+
+Returns:
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NO_JSON_FOUND",
+    "message": "No valid JSON found in file"
+  }
+}
+```
+
+### Schema Validation Failure
+
+```
+jsonValidate(
+  data='{"batch_number": "one", "summaries": []}',
+  schema='{"properties": {"batch_number": {"type": "integer"}}}'
+)
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "valid": false,
+  "errors": [
+    {
+      "path": "batch_number",
+      "message": "Expected number, received string",
+      "code": "invalid_type",
+      "expected": "number",
+      "received": "string"
+    }
+  ]
+}
+```

package/dist/skills/bioresearcher-core/examples/template.md

@@ -0,0 +1,49 @@
+# Batch Data Summarization Task
+
+## Input File
+- Full path: `{file_path}`
+- Sheet name: `{sheet_name}`
+
+## Row Range
+- Batch number: {batch_number}
+- Start row: {row_start}
+- End row: {row_end}
+
+## Summarization Instructions
+
+Extract the following fields from each row:
+
+{instructions_json}
+
+## Output Format
+
+Your output must be a valid JSON file with this structure:
+
+```json
+{
+  "batch_number": {batch_number},
+  "row_count": <number_of_rows_processed>,
+  "summaries": [
+    {
+      "row_number": <row_number>,
+      <field_1>: "<extracted_value>",
+      <field_2>: "<extracted_value>"
+    }
+  ]
+}
+```
+
+**Important:** The JSON keys for extracted values must match the field names specified in the Summarization Instructions.
+
+## Instructions
+
+1. Read the specified row range from the input file using the `tableGetRange` tool
+2. For each row, extract the requested fields according to the instructions above
+3. Map the extracted values to the JSON keys specified in the instructions
+4. Generate concise summaries based on the extracted data
+5. Save your output to: `{output_file}`
+
+## Output File Path
+Full path: `{output_file}`
+
+**CRITICAL:** Write your final output as a markdown file (.md) containing ONLY the JSON object (no additional text or explanation).