Maa Workflow Build

---
name: maa-workflow-build
description: Orchestrate ambiguous end-to-end MaaFramework automation requests into verified implementations. Use when a user asks to build, add, or change a complete Maa workflow or task—such as automatic stamina recovery—without already providing a full Pipeline design, start states, safety constraints, failure handling, or acceptance criteria. Compile intent into a task contract, discover project and UI state, design the state machine, route work across Maa skills, recover from failed observations or tests, and require evidence before completion.
---

# 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.
- Do not plan or implement against a scene that has not been observed. When a start or success state rests on a guess, explore the real UI first and write nodes from what was observed.
- 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](references/task-contract.md) before finalizing the goal. Read [references/run-state.md](references/run-state.md) before the first action and at every phase transition. Read [references/exploration-first.md](references/exploration-first.md) whenever a start or success state is not backed by a screenshot or recognition result captured in this task.

## 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.
- Invoke `$maa-diagnose` only from `RECOVER`, and only when a failure exists whose owner is still unknown after focused testing. It is a read-only evidence producer, never a routine phase, and never a repair actor.
- 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.

Record how each state was established. Mark a state `evidence_status: observed` only when a screencap, OCR result, or recognition trace captured in this task shows it, and record that artifact. A state inferred from documentation, an existing node name, a reused CustomAction's assumed precondition, a similar game, or the model's expectation is `evidence_status: guessed`.

### 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.

### 3. EXPLORE

Check the exploration gate before leaving DISCOVER. The gate is a condition, not a judgement call:

- **open** — at least one `start_states` or `success_states` entry is still `evidence_status: guessed`;
- **closed** — every `start_states` and `success_states` entry is `evidence_status: observed` and names the artifact that shows it.

While the gate is open, the task is in exploration-first mode. Drive the real UI with the MaaMCP tools (`screencap`, `ocr`, `click`, `swipe`) and observe at least one complete round-trip: from an observed start state, through every intermediate state, to the observed success state, and back to a stable return state. Record every hop as an observation with its screenshot, recognized text, box, and the action that caused the transition.

Do not write Pipeline nodes, CustomAction code, or a full implementation plan while the gate is open. Treat every reused node, processor, or CustomAction as having an entry precondition and observe the state it expects; do not assume an existing component is reachable from the current screen.

Read [references/exploration-first.md](references/exploration-first.md) for the round-trip definition, the observation record, and the exit criteria. When exploration is impossible because no device, no authorized entry point, or no permitted side effect is available, stop with an explicit gap instead of designing on guesses.

### 4. DESIGN

Enter DESIGN only when the exploration gate is closed, and design every node from the states, ROIs, and text recorded during exploration. Never write a node first and match it to the UI afterwards.

Design the complete state machine before generating nodes. Include:

- every supported start state;
- normal progress and success states;
- no-op and already-complete paths;
- recoverable failures and bounded retries;
- unsafe or ambiguous states that must stop;
- an observable post-action success check;
- a stable return or handoff state.

Use `$maa-pipeline-guide` to choose Pipeline state transitions versus CustomAction or CustomRecognition. Define the required files, nodes, options, and verification ladder. For actions that spend currency, consume items, start battles, or change an account, design a non-mutating probe before the real action.

### 5. IMPLEMENT

Apply the smallest coherent change that can satisfy the task contract:

- assemble and edit the overall Pipeline control flow in this orchestrator according to the designed state machine;
- consult `$maa-pipeline-guide` while designing, editing, or reviewing that control flow;
- use `$maa-pipeline-generate` to produce recognition/action nodes and ROI sweeps;
- use `$maa-pipeline-option` only for required user-facing controls and their end-to-end wiring;
- use `$maa-cli-operate` for compact repeatable validation and guarded runtime operations;
- use `$maa-pipeline-testing` after each coherent increment for recognition, Custom wiring, and behavioral validation, then run the integrated verification ladder.

Keep temporary probes distinguishable from deliverable nodes. Derive every click target from a recognition result instead of a hardcoded coordinate; see [coordinate hygiene](../maa-pipeline-guide/references/coordinate-hygiene.md). Preserve the target project's existing schema and naming conventions. Update the run state after each meaningful observation, edit, or failed attempt.

### 6. VERIFY

Read [references/acceptance-protocol.md](references/acceptance-protocol.md). Verify in increasing-risk order:

1. syntax, schema, references, and resource loading;
2. graph integrity and option/Custom wiring;
3. non-mutating recognition probes on known stable screens;
4. normal, no-op, disabled, failure, and recovery branches;
5. an end-to-end run only when its side effects are authorized;
6. post-action state and regressions against the task contract.

Attach observable evidence to each acceptance criterion. A skipped or unavailable check remains open unless the contract explicitly permits a documented limitation.

### 7. COMPLETE

Complete only when every required acceptance criterion has supporting evidence, no unexplained high-risk finding remains, temporary artifacts are handled, and the final state is stable.

Do not declare completion based only on generated JSON, a clean resource load, an unverified plan, or the model's own assessment. Report changed artifacts, verification evidence, remaining limitations, and safe follow-up actions.

### 8. RECOVER

Read [references/recovery-policy.md](references/recovery-policy.md) whenever an observation, tool call, edit, or test fails. Record the root cause or best bounded hypothesis, a safe retry, retry count, evidence needed from the retry, and an explicit stop condition.

Re-observe after navigation or unexpected output. Replan when the state model is wrong. Return to `EXPLORE` and reopen the gate when a failure shows that a state, a transition, or a reused component's precondition was assumed rather than observed. Stop instead of repeating ambiguous clicks, resource-consuming actions, or an unchanged failing attempt.

When the failure class itself is unknown, request evidence from `$maa-diagnose` before choosing a route, then decide retry, replan, delegate a repair, request user action, or stop from its normalized result. This orchestrator owns that decision; the diagnostic skill only supplies evidence and a bounded owner.

## Phase output

At each phase boundary, update a compact result with:

```yaml
status: success | warning | error
summary: one-line phase result
next_actions: []
artifacts: []
evidence: []
stop_reason: null
```

Keep the task contract stable unless new evidence or a user decision changes it. Compact context at phase boundaries; load only the specialist skill and reference needed for the next action.