myco-author-harness-task

name	myco:author-harness-task
description	Use this skill when designing, writing, configuring, or debugging a new phased executor task for the Myco agent harness — even if the user doesn't explicitly ask for a "task authoring" guide. Applies when adding a new intelligence task, modifying phase structure, tuning turn budgets or model routing, adjusting scheduling triggers or session-gating, designing a tool surface, or debugging silent phase failures or budget exhaustion. Covers: YAML task anatomy and registration; phase decomposition and the judgment/recipe gradient; model selection via the advisor pattern; turn budget calibration including local-model multipliers; scheduling triggers and session-gating; tool surface design and readOnly enforcement; Grove scope iteration patterns; per-project lifecycle management; and observability via the agent_runs audit table.
managed_by	myco
user-invocable	true
allowed-tools	["Read","Edit","Write","Bash","Grep","Glob"]

Myco Agent Harness Task Authoring

The Myco agent harness is a phased executor running inside the daemon. Each task is an ordered sequence of phases — each phase is a single LLM invocation with a bounded tool surface and a turn budget. This skill covers the full authoring lifecycle: designing the phase sequence, writing the task config, selecting models, calibrating budgets, configuring triggers, designing tool surfaces, and debugging when things go wrong.

Prerequisites

• Daemon is running and agent.enabled: true in .myco/myco.yaml.
• You have read at least one existing task YAML (packages/myco/src/agent/definitions/tasks/vault-evolve.yaml) to understand the config shape.
• You can describe the new task's purpose in one sentence and identify which vault state it reads and writes.

Procedure 1: Design the Phase Sequence

Apply the judgment/recipe gradient

Every phase sits on a spectrum from pure-recipe to pure-judgment:

Pole	Characteristics	Typical examples
Recipe (deterministic)	Tight tool allowlist, short budget, script-like	Mark processed, cursor update, dedup gate
Judgment (open-ended)	Broader tool access, longer budget, LLM reasons freely	Extract spores, consolidate, generate skill

Position each phase deliberately. Never blur: a phase that both reasons and writes DB state is hard to debug and hard to retry cleanly.

Data injection between phases

The canonical pattern is read-only discovery → write:

1. Phase 1 (discover): reads vault, assembles context, writes nothing. Emits a structured summary.
2. Phase 2 (write): receives that summary as injected context; writes to vault based on it.

This keeps Phase 2 idempotent — if it fails you can replay it with the same context without re-running discovery.

Multi-tier workflows

Complex tasks may need tiered verification phases, such as the skill lifecycle pattern: inventory → verify → assess → act. The verify phase specifically validates skills against current codebase state and sets watermarks for rotation.

Procedure 1.1: Map-Phase Architecture

Use mode: map for bulk operations with identical per-item logic. The harness owns batch fetch and iteration; the model invokes once per item with constrained tools.

When to use map mode

Ideal for: Bulk operations with identical per-item processing, cost-sensitive batch work. Not suitable for: Cross-item reasoning, operations requiring dynamic tool selection, phases needing full batch context.

Map-phase configuration

{
  name: 'process_items',
  mode: 'map',
  systemPrompt: ITEM_PROCESSING_PROMPT,
  turnBudget: 3,           // Per-item budget, keep tight
  tools: ITEM_TOOLS,       // Constrained surface per item
  fetchConfig: {
    tool: 'canopy_get_entries',
    params: { limit: 20, types: ['file'] },
    itemField: 'entries',  // Array field in tool response
    emptySkip: true,       // Skip phase if no items
  },
}

Advanced debugging and optimization

Contract violations: Map-phase harness strips sink_schema and injects argMap. Phase handlers checking args.sink_schema will fail.

Accelerator configuration:

accelerator:
  strategy: adaptive
  initial_batch_size: 5
  max_batch_size: 20
  ramp_factor: 1.5
  success_threshold: 0.85

Cost optimization: Use provider metadata consolidation (600x+ speedup observed) and cost-aware batch sizing:

function calculateOptimalBatchSize(inputSize, costModel) {
  const memoryConstraint = Math.floor(availableMemory / avgItemMemory);
  const costConstraint = Math.floor(maxBatchCost / estimatedItemCost);
  return Math.min(memoryConstraint, costConstraint, inputSize);
}

Runtime optimization: Implement agent instance pooling, tool surface templates, and resource monitoring for long-running operations.

Fault tolerance:

retry:
  max_attempts: 3
  backoff: exponential
  recoverable_errors: ["rate_limit", "timeout", "temporary_failure"]
  permanent_errors: ["auth_error", "invalid_input"]

Procedure 2: Write the Task Config

Tasks live in packages/myco/src/agent/definitions/tasks/. Each task exports a TaskDefinition:

export const myNewTask: TaskDefinition = {
  name: 'my-new-task',          // kebab-case, unique across all tasks
  isDefault: false,              // true = fires on settled session; false = manual/cron only
  phases: [ /* see below */ ],
  triggers: {
    schedule: '0 */4 * * *',    // omit for event-only tasks
    requireSettledSessions: true,
    settledSessionIdleMinutes: 5,
  },
};

Critical: Ensure proper TaskDefinition export. Malformed exports cause silent task failures with no error logs.

Procedure 2.1: Grove Multi-Project Integration

Scope iteration patterns

Grove introduces multi-project management. Tasks must handle scope iteration across registered projects:

import { forEachGrove, forEachRegisteredProject, isProjectActive } from '../../../daemon/scope-iteration';

// Iterate across all groves (highest level)
await forEachGrove(async (grove) => {
  // Grove-level processing
});

// Iterate across registered projects in current grove
await forEachRegisteredProject(async (projectContext) => {
  if (!isProjectActive(projectContext)) return;
  // Per-project task execution
});

Project lifecycle management: Use ProjectPowerStateTracker to respect project sleep/wake state:

import { ProjectPowerStateTracker } from '../../../daemon/project-power-state';

const powerTracker = new ProjectPowerStateTracker();
if (!powerTracker.isProjectAwake(projectId)) {
  // Skip or defer task for sleeping project
}

Handle safety with Grove runtime cache

Use GroveRuntimeCache for safe cross-project state management:

import { GroveRuntimeCache } from '../../../daemon/grove-runtime-cache';

const cache = new GroveRuntimeCache();
const projectHandle = cache.getProjectHandle(projectId);
// Use handle for thread-safe operations across grove

Daemon notification integration

Tasks should emit notifications for multi-project visibility:

// Emit task completion notifications
await notificationService.emit({
  domain: 'agent',
  event: 'task_completed',
  projectId,
  data: { taskName: 'my-new-task', phase: 'completion' }
});

Procedure 3: Select Models with the Advisor Pattern

Use advisor field per-phase for optimal model routing:

Tag	Best for
cloud-reasoning	Open-ended judgment phases (extraction, synthesis)
cloud-fast	Recipe phases where speed matters
local-draft	Cost-sensitive judgment phases

Local model gotcha: Multiply all turn budgets by 3–4× for local Ollama models.

Procedure 4: Calibrate Turn Budgets

Phase type	Cloud budget	Local budget
Discovery / read-only	8–12	25–40
Write / consolidation	10–20	30–60
Map-phase (per item)	2–4	6–12

Fix unbounded input: Cap the input size, not the budget. Use bounded instruction builders with MAX_BATCHES = 20.

Batch optimization: Recent findings show 8–12 items per batch often outperforms 15–20 items for complex reasoning.

Procedure 5: Configure Scheduling and Session Gating

Session State Machine

active  ──(SessionEnd hook or idle threshold)──►  completed
  ▲                                                    │
  └──────────(SessionStart on same session)────────────┘

Settlement conditions: SessionEnd hook OR last_prompt_at older than settledSessionIdleMinutes.

Session gating (critical)

triggers: {
  requireSettledSessions: true,  // Required for transcript-reading tasks
  settledSessionIdleMinutes: 5,
}

Any task reading session transcripts must gate on settled sessions to prevent stale artifacts.

Vault read surfaces: All surfaces (vault_unprocessed, vault_spores, vault_sessions, vault_search_fts, vault_search_semantic) automatically honor the gate.

Procedure 6: Design the Tool Surface

Recipe vs. Judgment surfaces

Recipe phases: Explicit allowlists for predictable behavior.

const DISCOVER_TOOLS = {
  bash: { allowed: ['cat', 'grep'] },
  vault: ['vault_unprocessed', 'vault_spores'],
};

Judgment phases: Broader access but scoped writes.

const CONSOLIDATE_TOOLS = {
  vault: ['vault_spores', 'vault_search_fts', 'vault_create_spore'],
};

readOnly annotation: Set readOnly: true on non-writing phases for MCP enforcement and safe concurrent execution.

Procedure 7: Observe and Debug

agent_runs audit table

Every phase execution writes to agent_runs:

Column	What it tells you
exit_reason	budget_exhausted / short_circuit / complete / error
turn_count	LLM turns used
tool_output_summary	Concatenated tool outputs (truncated)

Silent failure patterns

Symptom	Likely cause
exit_reason = 'complete' but no state change	Sentinel triggered incorrectly
turn_count = 1, empty tool_output_summary	Malformed prompt or injected context
Task never appears in agent_runs	TaskDefinition export malformed

Procedure 8: Advanced Harness Integration

Pi integration patterns

• Design agent implementations for central harness registry
• Use durable state contracts for reliable lifecycle management
• Implement proper agent scoping and resource cleanup
• Follow Pi conceptual framework for architecture consistency

Harness-ready architecture

• Register in central harness for discoverability
• Use registry-based agent resolution for dynamic assignment
• Implement config caching patterns (reduce initialization overhead)
• Design for minimal resource consumption during idle periods

Procedure 9: Cost Models and Performance Optimization

Cost-aware strategies

• Monitor token consumption patterns across iterations
• Implement circuit breakers for expensive operations
• Use consolidated provider metadata for model selection optimization
• Design adaptive pricing strategies with cost efficiency feedback

Performance patterns

• Agent instance pooling: Reuse instances across iterations when safe
• Tool surface optimization: Strip unnecessary tools, implement lazy loading
• Batch sizing strategies: Balance memory, cost, and latency constraints
• Resource monitoring: Track memory/CPU usage, alert on exhaustion

Procedure 10: Fault Tolerance and State Management

Robust operation patterns

• Implement checkpoint/resume for large operations
• Design idempotent operations where possible
• Use failure isolation to contain iteration failures
• Preserve partial results for manual recovery

State management

• Persist intermediate state at logical boundaries
• Enable resumption from last successful checkpoint
• Design state contracts that survive restarts
• Implement state validation and migration patterns

Cross-Cutting Gotchas

• TaskDefinition export malformed → task never runs, no error. Verify export structure and check agent_runs.
• No session gate on transcript-reading task → stale artifacts. Always set requireSettledSessions: true.
• Static turn budget on unbounded input → unpredictable runtime. Cap input size, not budget.
• Single model for all phases → overpaying or underperforming. Use per-phase advisor field.
• Local model without budget multiplier → phase exhausts. Multiply budgets by 3–4× for Ollama.
• Map-phase sink schema expectation → args.sink_schema doesn't exist in map mode. Use argMap instead.
• Abort controller propagation → Thread controllers through all iterations to prevent resource leaks.
• Tool surface wrapping → Each iteration gets wrapped surface. Stateful tools may behave unexpectedly.
• Accelerator counter overflow → Implement bounds checking and counter resets for long operations.
• Rate limit amplification → Map phases hit limits faster. Implement backoff and consider API quotas.
• Provider metadata staleness → Implement refresh mechanisms and validate availability.
• State contract violations → Strict adherence required. Violations cascade through harness system.
• Grove scope iteration without project state check → Processing inactive projects. Always check isProjectActive().
• Cross-project state corruption → Use GroveRuntimeCache for thread-safe handle management.
• Missing daemon notifications → Grove multi-project visibility requires notification emission.
• Migration path reference error → Migrations are in single file packages/myco/src/db/migrations.ts, not directory.