maestro-handoff

To resume an AI agent workflow with prior context, you read handoff envelopes left on disk in the .maestro/handoffs directory. This passive discovery mechanism ensures the next agent picks up the exact task state and continuity left by the previous lifecycle event.

Task claim and task block continuity works by using trigger_verb-aware handling to verify prior agent actions on a specific task_id. The receiving agent reads the JSON envelope to check whether the task was claimed or blocked and follows the referenced reason to resume correctly.

The best way to pass task state between agents is using on-disk JSON contracts emitted during lifecycle events. This passive handoff approach allows any subsequent agent to directly read the prior context and task state without requiring active inter-agent communication.

Yes, you can route a handoff envelope to a specific AI tool by using the optional to_agent field or the intra-tool tool argument during task claim or block events. This strict filtering ensures continuity remains within the same tool environment.

Yes, you need a maestro project structure because the Skill discovers envelopes passively within the .maestro/handoffs directory. It targets session start, task pickup, and debugging missed continuity specifically for tasks identified by a task_id in that environment.

An agent misses prior context when picking up a blocked task if the handoff envelope is stale or missing from the .maestro/handoffs directory. Debugging missed continuity requires locating the correct envelope by task_id to retrieve the referenced block reason.