threnody-workflow

Threnody workflow orchestration

Runs fan-out work as a tier-aware Dynamic Workflow (each agent() on its Threnody tier model, not one session model), with multi-queen consensus and learning — then lets you save a permanent, documented, zero-config /<slug> command teammates run with no setup.

This is Claude Code-only. Other hosts use host_spawn_waves through threnody-swarm; all shared behavior must work there first.

Fast-start contract

Workflow-emitting skills must produce a runnable workflow_script quickly: target under 5 seconds to handoff and under 30 seconds to first worker spawn. The emitted script must start same-wave workers in a batch, for example with parallel([...]), before waiting on the wave barrier.

Do not block initial workflow emission on optional refinement, consensus, learning aggregation, or permanent-workflow export. Run those after the first worker wave has started or after the workflow returns.

For review workflows, use the nested cheap shape: the Workflow script performs medium-tier orchestration, launches file reviewers in parallel, and returns a compact synthesis to the main session. Keep high-tier judgment for explicit deep/security-critical review or validated high/critical findings.

Prerequisite (claude-code only)

This path needs routing_policy.shells.claude-code.workflow_emit: true in ~/.local/lib/threnody/config.yaml. If it is off (or the host is not Claude Code), the response will not include workflow_script — fall back to /threnody-swarm. Requires Claude Code v2.1.154+ (Workflow tool).

Workflow

1. execute_swarm(task, topology="star"|"auto").
2. Inspect the response:
   • workflow_emit: true + workflow_script — the tier-aware script. Launch it via the Workflow tool (paste/run workflow_script). It runs in the background, keeps intermediate results out of your context, and routes each agent to its model. Same-wave agents must be represented as a batch in the script, not as a sequential loop.
   • No workflow_script — emission is off; use /threnody-swarm instead.
3. When the workflow returns, call report_workflow_result(workflow_name, agents) with the agents array the workflow returned (report_workflow_result records per-agent learning telemetry).
4. Consensus:
   • Hybrid (default): the response also has a consensus_wave. After the workflow finishes, spawn each read-only queen in it as a host Agent (one parallel message), then report_host_wave(swarm_id, wave, workspace_root, agents=[...]) with each queen's JSON verdict as output_excerpt. If the response returns consensus_followup, spawn the single judge Agent it provides and report again.
   • Opt-in (consensus_in_workflow): queens run inside the workflow; pass the workflow's returned consensus array to report_workflow_result(..., consensus=[...]). If it returns consensus_followup, spawn one judge Agent and re-call with consensus set to just the selected queen's proposal.
   • For ordinary reviews, prefer a targeted verifier pass for synthesized HIGH/CRITICAL findings instead of running consensus over every file.
5. Save a permanent workflow (the payoff): once a shape recurs across successful runs, report_workflow_result returns workflow_draft.enqueued: true. Then:
   • approval_queue_approve(<queue_id>, operator=<you>) to approve the learned workflow.
   • Export it with tuning + documentation:

     python3 -c "import shared.workflow_export as wx, shared.db as d; \
       wx.export_workflow(<approved_draft_dict>, project_path='.', db=d.Database(), tune=True)"
     

     This re-tunes per-tier models from recorded outcomes ("what model did task X well"), writes a documented header (tier→model map, persona roster + roles, related learned agents), and saves .claude/workflows/<slug>.js.
   • Commit .claude/workflows/<slug>.js to the repo → teammates run /<slug> with zero config.