Maa Workflow Build

Maa Workflow Build

Own an end-to-end Maa automation request from ambiguous intent through evidence-backed completion. Treat the other Maa skills as specialist capabilities; keep this skill responsible for goal compilation, phase state, routing, recovery, and acceptance.

Operating contract

• Do not jump from a vague request directly to Pipeline nodes.
• Maintain one task contract and one current run state throughout the task.
• Separate observed facts, user decisions, working assumptions, and unresolved questions.
• Ask only about choices that materially change behavior, safety, or acceptance. Make reversible, low-risk assumptions explicit and continue.
• Define verification before implementation. Do not declare completion because files were written or a single smoke test passed.

Read references/task-contract.md before finalizing the goal. Read references/run-state.md before the first action and at every phase transition.

Specialist roles

• Keep this orchestrator responsible for the task contract, state-machine design, failure routing, and final acceptance. The orchestrator owns state-machine assembly and integration; specialist outputs do not become a finished workflow until they are connected and verified against the contract.
• Treat $maa-pipeline-guide as a reference and constraint source, not a sequential execution phase or node producer. Load only the sections needed to design, edit, or review the current control flow.
• Treat $maa-pipeline-generate as the primary producer for recognition and action nodes, especially OCR, TemplateMatch, ColorMatch, ROI selection, and screenshot-derived snippets. Integrate its output into the designed state machine instead of treating generated nodes as task completion.
• Invoke $maa-pipeline-option only when the task contract requires a user-facing toggle, selector, checkbox, switch, or input. Do not create options merely because the skill is available.
• Run $maa-pipeline-testing after each coherent implementation increment and again against the integrated end-to-end flow. Use its evidence to route a failure back to the specialist or orchestrator phase that owns the defect.
• Treat $maa-cli-operate as an execution backend for repeatable checks or guarded runtime operations, not a mandatory business phase.
• Treat $maa-wiki as an official-knowledge reference provider. Use it when the task contract, design, or acceptance criteria depend on MaaFramework documentation, schema, API, binding, release, or semantic-change facts; navigate to original sources before treating those facts as authoritative.

Do not treat the specialists as a fixed guide -> generate -> option -> testing sequence. Call only the capability required by the current task state, then return its artifacts and evidence to this control loop.

Control loop

1. SPECIFY

Compile the request into a task contract. Define the goal, non-goals, observable start states, success and failure states, constraints, allowed and forbidden side effects, assumptions, and acceptance criteria.

Treat start state as a set of observable states, not one ideal screen. Include safe behavior for an unknown or unexpected state. Resolve project-independent product choices before editing, such as whether paid currency, purchases, repeated consumptions, or destructive actions are allowed.

2. DISCOVER

Locate the target project and check for optional project-level context artifacts before broad discovery:

• If basic_info.md exists and is current enough for the task, read its routed sections as a cache and verify every touched fact against current source.
• If an ignored graph output such as pipeline_overview.html, pipeline_external_entries.html, or its index.html exists and is current enough, use it for orientation and verify affected edges against current Pipeline and Python files.
• If either artifact is missing, incomplete, or stale, continue with targeted source discovery and record the optional context gap. Do not block the workflow or regenerate the artifact.

Never invoke $maa-project-init or $maa-pipeline-graph automatically. Use those one-time or low-frequency project tools only when the user explicitly requests initialization, refresh, visualization, or graph regeneration. Confirm current Pipeline files, task entries, resource groups, public return/recovery nodes, option surfaces, Python entries, device availability, and current UI evidence directly from the project and environment.