Queue Moonmind Workflows

---
name: queue-moonmind-workflows
description: Queue additional MoonMind workflows from inside an existing workflow by submitting explicit `/api/executions` requests, applying stable idempotency, verifying every returned `workflowId` with the execution API, and writing a durable queue summary. Use when a workflow needs to fan out follow-up MoonMind executions, create child implementation workflows, replace local task-list or manifest-only handoffs, or prove that downstream workflows were actually queued.
---

# Queue MoonMind Workflows

## Overview

Queue child MoonMind workflows through the durable execution API and verify
their visibility before reporting success. This skill is for workflow fan-out:
creating more MoonMind executions from a running MoonMind workflow, not for
planning future work in an agent-local task list.

## Non-Negotiables

- Do not claim workflows were queued unless each successful item has a
  `workflowId` returned by `POST /api/executions` and verified by
  `GET /api/executions/{workflowId}`.
- Do not satisfy queueing requests by writing only a markdown file, a local JSON
  manifest, an in-session task list, or a proposal.
- Use `MOONMIND_URL` and the execution API. Do not write directly to the
  database, call Temporal CLI directly for creation, or infer success from
  agent stdout.
- Use stable idempotency. Prefer a parent workflow/run scope plus the child ref;
  fail when idempotency cannot be established unless the operator explicitly
  asks for non-idempotent submission.
- Keep child request bodies compact. Large source briefs, story files, logs, or
  generated context must be artifact refs or issue refs, not embedded blobs.

## Manifest

Write a manifest containing one complete `/api/executions` request per child:

```json
{
  "batchScope": "mm:parent-workflow-or-run",
  "workflows": [
    {
      "ref": "github:MoonLadderStudios/MoonMind#722",
      "request": {
        "type": "task",
        "priority": 0,
        "maxAttempts": 3,
        "payload": {
          "repository": "MoonLadderStudios/MoonMind",
          "runtimeInheritance": "caller",
          "requiredCapabilities": ["git", "gh"],
          "task": {
            "title": "Implement GitHub issue #722",
            "instructions": "Implement GitHub issue MoonLadderStudios/MoonMind#722.",
            "taskTemplate": {"slug": "github-issue-implement", "scope": "global"},
            "inputs": {
              "github_issue_ref": "MoonLadderStudios/MoonMind#722"
            },
            "publish": {"mode": "pr"}
          }
        }
      }
    }
  ]
}
```

The helper supports both execution API shapes:

- task-shaped wrapper: `{"type": "task", "payload": {...}}`
- direct execution create body: `{"workflowType": "MoonMind.UserWorkflow", ...}`

Author preset children with `task.taskTemplate: {"slug": "<preset-slug>",
"scope": "global"}` so the execution API expands the exact registered
preset. `github-issue-implement` is a preset (`preset:github-issue-implement`),
not a Skill: do not queue it via `task.skill.name`. Reserve `task.tool:
{"type": "skill", "name": ...}` for actual Skill identities and validate
every example ref against the real capability catalog and admission contract.

When `MOONMIND_EXECUTION_FANOUT_BEARER_TOKEN_FILE` or the direct
`MOONMIND_EXECUTION_FANOUT_BEARER_TOKEN` value is present, only the task-shaped
child form is accepted and the helper binds it to the caller with
`runtimeInheritance="caller"`; direct create and schedule shapes remain available
only to ordinary authenticated API users.

For task-shaped requests, idempotency is stored at `request.payload.idempotencyKey`.
For direct create requests, idempotency is stored at `request.idempotencyKey`.

## Workflow

1. Resolve helpers exclusively from the run's immutable active bundle.

   ```bash
   QUEUE_MOONMIND_WORKFLOWS_SKILL_DIR="${QUEUE_MOONMIND_WORKFLOWS_SKILL_DIR:-${MOONMIND_ACTIVE_SKILLS_DIR:+$MOONMIND_ACTIVE_SKILLS_DIR/queue-moonmind-workflows}}"
   test -n "$QUEUE_MOONMIND_WORKFLOWS_SKILL_DIR" && test -f "$QUEUE_MOONMIND_WORKFLOWS_SKILL_DIR/SKILL.md"
   ```

   Inside MoonMind, `MOONMIND_ACTIVE_SKILLS_DIR` is always set and the helper
   below resolves from it; a checked-in `.agents/skills` directory must never
   shadow the selected snapshot. When no skill-specific override is present,
   the helper resolves to
   `${MOONMIND_ACTIVE_SKILLS_DIR:-.agents/skills}/queue-moonmind-workflows/scripts/queue_moonmind_workflows.py`.
   Outside MoonMind, set
   `QUEUE_MOONMIND_WORKFLOWS_SKILL_DIR` to the directory containing this
   `SKILL.md` (no MoonMind-only environment variables required). A missing
   selected helper is a materialization/packaging error: stop as blocked
   instead of substituting stale repository code.

2. Resolve the child targets and write the manifest to a managed artifact path,
   usually `artifacts/queue-moonmind-workflows-manifest.json`.
3. Run the helper:

   ```bash
   python3 "$QUEUE_MOONMIND_WORKFLOWS_SKILL_DIR/scripts/queue_moonmind_workflows.py" \
     --manifest artifacts/queue-moonmind-workflows-manifest.json \
     --max-workflows 25
   ```

4. Read the helper output. A successful queue has:
   - `submitted > 0`
   - `verified == submitted`
   - `errors == []`
   - one `workflowId` per queued item
5. Report queued workflow IDs and the summary artifact path. If any item failed
   submission or verification, report the run as failed/partial and include the
   specific failing `ref` values.

## Helper Behavior

`scripts/queue_moonmind_workflows.py`:

- requires `MOONMIND_URL`;
- reads `MOONMIND_EXECUTION_FANOUT_BEARER_TOKEN_FILE` when present and fails
  closed if that lease-owned file is missing or empty; otherwise accepts the
  direct `MOONMIND_EXECUTION_FANOUT_BEARER_TOKEN` value for portable hosts;
- sends the scoped value as a bearer with the fan-out v1 marker and never
  substitutes a broader API token when scoped authority is configured;
- forwards supported API auth from `MOONMIND_AUTH_HEADER`,
  `MOONMIND_API_TOKEN`, `MOONMIND_AUTH_TOKEN`, `MOONMIND_BEARER_TOKEN`, or
  `MOONMIND_API_KEY` when present, and also forwards
  `MOONMIND_WORKER_TOKEN` or `MOONMIND_WORKER_TOKEN_FILE` for deployments that
  still accept the legacy worker header;
- forwards parent workflow/agent headers from `MOONMIND_TASK_WORKFLOW_ID`,
  `MOONMIND_WORKFLOW_ID`, `TEMPORAL_WORKFLOW_ID`, `MOONMIND_AGENT_RUN_ID`,
  `MOONMIND_RUN_ID`, or `AGENT_RUN_ID`;
- derives idempotency keys from `batchScope`, child `ref`, and the request body;
- submits each child with `POST /api/executions`;
- verifies each returned `workflowId` with bounded retries against
  `GET /api/executions/{workflowId}`;
- writes `queue-moonmind-workflows-result.json` under the managed session
  artifact spool when available, otherwise under `--artifacts-dir`;
- exits non-zero when submission or verification errors occur.

Use `--dry-run` to validate and summarize the manifest without submitting. Use
`--allow-empty` only when a no-op is an acceptable outcome.

## Result Standard

Treat these as failures:

- `MOONMIND_URL` is missing.
- The manifest has zero workflows and `--allow-empty` was not set.
- The manifest exceeds `--max-workflows`; cap skips are reported as partial
  failures instead of silent success.
- Any child request lacks a stable idempotency key and the helper cannot derive
  one from parent scope.
- A `POST /api/executions` response lacks `workflowId`.
- A returned `workflowId` cannot be fetched through `GET /api/executions/{id}`
  within the retry window.
- The helper exits non-zero.

When queueing from an already-running workflow, prefer
`runtimeInheritance: "caller"` in the child payload and include a fallback
runtime only when the parent task context supplies one. Do not silently switch
model, effort, provider profile, repository, publish mode, or credentials.