@yeyuan98/opencode-bioresearcher-plugin 1.3.1 → 1.4.0

package/dist/skills/bioresearcher-core/patterns/subagent-waves.md

@@ -0,0 +1,186 @@
+# Subagent Waves Pattern
+
+Process multiple items with parallel subagents organized in waves.
+
+## Overview
+
+Use this pattern when you need to process many items in parallel while controlling concurrency.
+
+## Requirements
+
+> **CRITICAL:** This pattern requires the `Task` tool to be available in your environment.
+> 
+> - If the Task tool is not available, **subagent waves are not possible**
+> - Alternative: Process items sequentially or use external batch processing
+> - Check tool availability before implementing this pattern
+> 
+> To verify Task tool availability, check your environment's tool list.
+
+## Pattern Algorithm
+
+```
+1. Calculate total items and wave_size
+2. Group items into waves of wave_size items each
+3. For each wave:
+   a. Launch wave_size subagents in parallel via Task tool
+   b. Wait for all subagents to complete
+   c. Track progress (use progress pattern)
+   d. Validate outputs using jsonExtract + jsonValidate
+   e. Collect validated outputs
+4. Handle failed items (use retry pattern)
+5. Combine all outputs using jsonExtract or table tools
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `wave_size` | 3 | Number of parallel subagents per wave |
+| `subagent_type` | "general" | Type of subagent to launch |
+
+## Key Principles
+
+1. **File-based prompts**: Subagents read prompt files, not inline prompts
+2. **File-based outputs**: Subagents write to output files as JSON
+3. **Schema validation**: Every output validated before processing
+4. **Wave coordination**: Wait for entire wave before starting next
+5. **Progress tracking**: Report after each wave completes
+
+## Tool: Task
+
+```
+task(
+  subagent_type: string,
+  description: string,
+  prompt: string
+)
+```
+
+## Example: Launch Wave of 3 Subagents
+
+```typescript
+// Wave 1 - Launch 3 subagents in parallel
+task(
+  subagent_type="general",
+  description="Process batch 001",
+  prompt="Read your prompt from ./.work/batch001.md and perform the task described there exactly as written."
+)
+task(
+  subagent_type="general",
+  description="Process batch 002",
+  prompt="Read your prompt from ./.work/batch002.md and perform the task described there exactly as written."
+)
+task(
+  subagent_type="general",
+  description="Process batch 003",
+  prompt="Read your prompt from ./.work/batch003.md and perform the task described there exactly as written."
+)
+// Wait for all 3 to complete before Wave 2
+```
+
+## Example: Full Wave Processing Workflow
+
+```
+# Configuration
+total_items = 12
+wave_size = 3
+total_waves = ceil(total_items / wave_size)  # 4 waves
+
+# Create prompt files first (using template.py)
+uv run python <skill_path>/python/template.py generate-batches \
+  --template template.md \
+  --contexts contexts.json \
+  --output-dir ./prompts
+
+# Process in waves
+for wave_num in range(1, total_waves + 1):
+    # Launch wave
+    start_idx = (wave_num - 1) * wave_size + 1
+    end_idx = min(wave_num * wave_size, total_items)
+    
+    for batch_num in range(start_idx, end_idx + 1):
+        task(
+            subagent_type="general",
+            description=f"Process batch {batch_num:03d}",
+            prompt=f"Read your prompt from ./prompts/batch{batch_num:03d}.md and perform the task."
+        )
+    
+    # Wait for wave completion
+    # (Task tool handles this - next task call waits)
+    
+    # Report progress
+    completed = end_idx
+    percent = calculator(formula=f"({completed} / {total_items}) * 100")
+    report(f"Progress: {completed}/{total_items} batches ({percent}%)")
+```
+
+## Output Validation
+
+After each wave, validate outputs:
+
+```
+# For each output file
+result = jsonExtract(file_path="./outputs/batch001.md")
+if not result.success:
+    log_error("Failed to extract JSON from batch001.md")
+    continue
+
+# Validate against schema
+validation = jsonValidate(
+    data=json.dumps(result.data),
+    schema=expected_schema
+)
+if not validation.valid:
+    log_error(f"Schema validation failed for batch001.md: {validation.errors}")
+    continue
+
+# Collect valid output
+valid_outputs.append(result.data)
+```
+
+## Handling Failed Batches
+
+After all waves complete:
+
+```
+# Check for missing outputs
+expected_files = [f"batch{i:03d}.md" for i in range(1, total_items + 1)]
+missing = [f for f in expected_files if not exists(f"./outputs/{f}")]
+
+if missing:
+    # Use retry pattern
+    for batch_file in missing:
+        retry_subagent(batch_file, max_attempts=3, delay=2)
+```
+
+## Combining Outputs
+
+For small batches (<10 files), use table tools:
+
+```
+# Extract all JSON
+all_data = []
+for file in output_files:
+    result = jsonExtract(file_path=file)
+    if result.success:
+        all_data.extend(result.data["summaries"])
+
+# Create combined Excel
+tableCreateFile(
+    file_path="./combined.xlsx",
+    sheet_name="Results",
+    data=all_data
+)
+```
+
+For large batches (>10 files), use Python script for efficiency.
+
+## Best Practices
+
+1. **Verify Task tool availability** before implementing this pattern
+2. **Keep wave_size reasonable**: 3-5 subagents per wave
+3. **Use descriptive descriptions**: "Process batch 001" not "Batch 1"
+4. **Always use file-based prompts**: Never inline large prompts
+5. **Validate every output**: Don't skip schema validation
+6. **Report progress after waves**: Not during individual completions
+7. **Have fallback plan**: If Task tool unavailable, use sequential processing

package/dist/skills/bioresearcher-core/patterns/table-tools.md

@@ -0,0 +1,260 @@
+# Table Tools Pattern
+
+Guide for combining subagent outputs using table tools.
+
+## Overview
+
+Table tools can be used to combine JSON outputs into Excel/CSV files without Python scripts for small batches.
+
+## When to Use Table Tools vs Python
+
+| Scenario | Use Table Tools | Use Python Script |
+|----------|-----------------|-------------------|
+| Files to combine | <10 files | >=10 files |
+| Data size | Small (<1000 rows total) | Large (>1000 rows) |
+| Complexity | Simple merge | Complex transformations |
+| Performance | Acceptable overhead | Need efficiency |
+
+## Tool: tableCreateFile
+
+Create a new Excel/CSV file from data.
+
+### Signature
+```
+tableCreateFile(
+  file_path: string,
+  sheet_name: string = "Sheet1",
+  data: array  // Array of arrays OR array of objects
+)
+```
+
+### Return Format
+```json
+{
+  "success": true,
+  "file_path": "./output.xlsx",
+  "sheet_name": "Sheet1",
+  "rows_created": 100,
+  "message": "Successfully created Excel file with 100 rows"
+}
+```
+
+### Examples
+
+```
+# Create from array of objects
+tableCreateFile(
+  file_path="./output.xlsx",
+  sheet_name="Results",
+  data=[
+    {"row_number": 1, "name": "Alice", "score": 95},
+    {"row_number": 2, "name": "Bob", "score": 87}
+  ]
+)
+
+# Create from array of arrays
+tableCreateFile(
+  file_path="./output.csv",
+  sheet_name="Sheet1",
+  data=[
+    ["row_number", "name", "score"],
+    [1, "Alice", 95],
+    [2, "Bob", 87]
+  ]
+)
+```
+
+## Tool: tableAppendRows
+
+Append rows to an existing table file.
+
+### Signature
+```
+tableAppendRows(
+  file_path: string,
+  sheet_name: string?,  // Optional, uses first sheet
+  rows: array  // Array of arrays OR array of objects
+)
+```
+
+### Return Format
+```json
+{
+  "success": true,
+  "file_path": "./output.xlsx",
+  "sheet_name": "Sheet1",
+  "rows_appended": 50,
+  "message": "Successfully appended 50 rows"
+}
+```
+
+### Examples
+
+**RECOMMENDED: Append using array-of-arrays format (no header duplication):**
+```
+tableAppendRows(
+  file_path="./output.xlsx",
+  rows=[
+    [3, "Charlie", 92],
+    [4, "Diana", 88]
+  ]
+)
+```
+
+**Alternative: Append using objects (may duplicate headers):**
+```
+tableAppendRows(
+  file_path="./output.xlsx",
+  rows=[
+    {"row_number": 3, "name": "Charlie", "score": 92}
+  ]
+)
+```
+
+> **Note:** When appending object-format data, some implementations may insert a duplicate header row. For reliable results, use array-of-arrays format for append operations.
+
+## Combining JSON Outputs Workflow
+
+### Step 1: Extract All JSON
+
+```
+# Extract JSON from each output file
+all_rows = []
+
+for batch_num in range(1, num_batches + 1):
+    file_path = f"./outputs/batch{batch_num:03d}.md"
+    result = jsonExtract(file_path=file_path)
+    
+    if result.success:
+        # Assuming data has "summaries" array
+        summaries = result.data.get("summaries", [])
+        all_rows.extend(summaries)
+    else:
+        log_error(f"Failed to extract from {file_path}")
+```
+
+### Step 2: Create Combined File
+
+```
+# Create Excel file with all rows
+tableCreateFile(
+  file_path="./combined_summary.xlsx",
+  sheet_name="Summary",
+  data=all_rows
+)
+```
+
+### Step 3: Append Additional Data (Optional)
+
+```
+# If processing in chunks, append to existing file using array format
+# First, get headers from the created file
+headers = list(all_rows[0].keys()) if all_rows else []
+
+for chunk in chunks:
+    rows = extract_rows(chunk)
+    # Convert to arrays to avoid header duplication
+    rows_as_arrays = [[item.get(h) for h in headers] for item in rows]
+    tableAppendRows(
+      file_path="./combined_summary.xlsx",
+      rows=rows_as_arrays
+    )
+```
+
+## Complete Example: Combining Batch Outputs
+
+```
+# Configuration
+output_dir = "./outputs"
+num_batches = 9
+combined_file = "./combined_summary.xlsx"
+
+# Collect all rows
+all_rows = []
+failed_batches = []
+
+for batch_num in range(1, num_batches + 1):
+    file_path = f"{output_dir}/batch{batch_num:03d}.md"
+    
+    # Extract JSON
+    result = jsonExtract(file_path=file_path)
+    
+    if not result.success:
+        failed_batches.append(batch_num)
+        continue
+    
+    # Get summaries from batch output
+    summaries = result.data.get("summaries", [])
+    all_rows.extend(summaries)
+
+# Report failures
+if failed_batches:
+    log_error(f"Failed batches: {failed_batches}")
+
+# Sort by row_number
+all_rows.sort(key=lambda x: x.get("row_number", 0))
+
+# Create combined Excel
+result = tableCreateFile(
+  file_path=combined_file,
+  sheet_name="Combined",
+  data=all_rows
+)
+
+# Report result
+report(f"Created {combined_file} with {result.rows_created} rows")
+```
+
+## Incremental Append Strategy
+
+For large datasets, append incrementally using array-of-arrays format:
+
+```
+# Get column headers from first batch
+first_batch = jsonExtract(file_path="./outputs/batch001.md")
+headers = ["row_number", "field1", "field2"]  # Define your headers
+
+# Create file with first batch (using objects for auto-headers)
+tableCreateFile(
+  file_path="./combined.xlsx",
+  sheet_name="Data",
+  data=first_batch.data.get("summaries", [])
+)
+
+# Get header order for array format
+headers = list(first_batch.data.get("summaries", [{}])[0].keys())
+
+# Append remaining batches using array format
+for batch_num in range(2, num_batches + 1):
+    file_path = f"./outputs/batch{batch_num:03d}.md"
+    result = jsonExtract(file_path=file_path)
+    
+    if result.success:
+        # Convert objects to arrays to avoid header duplication
+        rows_as_arrays = [
+            [item.get(h) for h in headers]
+            for item in result.data.get("summaries", [])
+        ]
+        tableAppendRows(
+          file_path="./combined.xlsx",
+          rows=rows_as_arrays
+        )
+```
+
+## Supported File Formats
+
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| Excel | .xlsx | Recommended |
+| Excel (Legacy) | .xls | Limited support |
+| ODS | .ods | OpenDocument Spreadsheet |
+| CSV | .csv | Text-based, no sheets |
+
+## Best Practices
+
+1. **Sort before writing**: Sort rows by key field before creating file
+2. **Handle failures gracefully**: Log failed extractions, continue with others
+3. **Use object format for creation**: Array of objects auto-generates headers
+4. **Use array format for appends**: Prefer array-of-arrays when using tableAppendRows to avoid potential header duplication
+5. **Check row counts**: Verify expected vs actual row counts
+6. **For large batches**: Use Python script for better performance

package/dist/skills/bioresearcher-core/patterns/user-confirmation.md

@@ -0,0 +1,187 @@
+# User Confirmation Pattern
+
+Request user confirmation before destructive or significant operations.
+
+## Overview
+
+Use this pattern before operations that:
+- Delete or modify files
+- Make network requests
+- Incur costs (API calls, cloud resources)
+- Take significant time
+- Cannot be easily undone
+
+## Tool: question
+
+> **Note:** The tool is invoked as `question` (lowercase). Some documentation may reference `Question` (capitalized) but both refer to the same tool.
+
+```
+question(questions: [{
+  header: string,      // Short label (max 30 chars)
+  question: string,    // Complete question
+  options: [{
+    label: string,     // Display text (1-5 words)
+    description: string // Explanation of choice
+  }],
+  multiple: boolean    // Allow multiple selections (default: false)
+}])
+```
+
+## Example: Before Destructive Operation
+
+```
+question(questions=[{
+  "header": "Delete files",
+  "question": "This will delete 15 files in ./temp/. Continue?",
+  "options": [
+    {"label": "Yes, delete", "description": "Permanently delete all 15 files"},
+    {"label": "No, cancel", "description": "Keep files and stop this operation"}
+  ]
+}])
+```
+
+## Example: Continue After Failures
+
+```
+question(questions=[{
+  "header": "Retry failed",
+  "question": "3 batches failed after all retry attempts. How would you like to proceed?",
+  "options": [
+    {"label": "Continue", "description": "Skip failed batches and continue with remaining"},
+    {"label": "Retry now", "description": "Try failed batches one more time"},
+    {"label": "Abort", "description": "Stop the entire workflow"}
+  ]
+}])
+```
+
+## Example: Configuration Choice
+
+```
+question(questions=[{
+  "header": "Batch size",
+  "question": "How many rows should each batch contain?",
+  "options": [
+    {"label": "30 rows (Recommended)", "description": "Balanced for most use cases"},
+    {"label": "50 rows", "description": "Fewer batches, larger context per subagent"},
+    {"label": "10 rows", "description": "More batches, smaller context per subagent"}
+  ]
+}])
+```
+
+## Example: Multiple Selection
+
+```
+question(questions=[{
+  "header": "Select sheets",
+  "question": "Which sheets should be processed?",
+  "options": [
+    {"label": "Sheet1", "description": "Main data sheet (1000 rows)"},
+    {"label": "Sheet2", "description": "Secondary data (500 rows)"},
+    {"label": "Summary", "description": "Pre-computed summaries (50 rows)"}
+  ],
+  "multiple": true
+}])
+```
+
+## When to Ask for Confirmation
+
+| Operation Type | Confirmation Needed |
+|---------------|---------------------|
+| Read file | No |
+| Write new file | No |
+| Overwrite existing file | Yes |
+| Delete file | Yes |
+| Delete directory | Yes |
+| API call (free) | No |
+| API call (paid) | Yes |
+| Long operation (>5 min) | Yes |
+| Network upload | Yes |
+| Network download | No (usually) |
+
+## Response Handling
+
+The question tool returns selected option labels as an array:
+
+```
+# Single selection
+response = question(...)
+if response[0] == "Yes, delete":
+    proceed_with_deletion()
+else:
+    cancel_operation()
+
+# Multiple selection
+response = question(..., multiple=true)
+selected_sheets = response  # ["Sheet1", "Sheet2"]
+```
+
+## Example: Conditional Logic Flow
+
+```
+# Ask for confirmation
+response = question(questions=[{
+  "header": "Overwrite",
+  "question": "File 'output.xlsx' already exists. Overwrite?",
+  "options": [
+    {"label": "Overwrite", "description": "Replace existing file"},
+    {"label": "Append", "description": "Add to existing file"},
+    {"label": "Cancel", "description": "Don't modify the file"}
+  ]
+}])
+
+# Handle response
+if response[0] == "Overwrite":
+    write_file(mode="write")
+elif response[0] == "Append":
+    write_file(mode="append")
+else:
+    report("Operation cancelled by user")
+```
+
+## Best Practices
+
+1. **Clear header**: Max 30 chars, summarize the decision
+2. **Descriptive question**: Explain what will happen
+3. **Helpful options**: Include descriptions that guide the user
+4. **Recommended option**: Mark with "(Recommended)" in label
+5. **Safe default**: Put safer option first
+6. **Cancel option**: Always include a way to abort
+
+## Timeout and No-Response Handling
+
+When users don't respond to confirmation prompts, implement a default behavior:
+
+### Default After Timeout
+
+```python
+# If no response after reasonable time, default to safe option
+# Most patterns should default to "cancel" for safety
+
+if no_response_after(timeout=60):
+    log("No user response, defaulting to cancel")
+    cancel_operation()
+```
+
+### Integration with Retry Pattern
+
+For critical operations requiring user input:
+1. Ask for confirmation
+2. If no response, wait and retry with `blockingTimer`
+3. After N attempts, use safe default or abort
+
+```python
+attempts = 0
+max_attempts = 3
+while attempts < max_attempts:
+    response = question(...)
+    if response:
+        handle_response(response)
+        break
+    attempts += 1
+    if attempts < max_attempts:
+        blockingTimer(delay=10)  # Wait before re-prompting
+
+# Default to safe option if no response
+if attempts >= max_attempts:
+    cancel_operation()
+```