Generate NPA Workflow

When To Use

Load after author-npa-workflow when the task is to design a new pipeline (not edit an existing reference spec). Use for creative mashups, customer demos, and SkyPilot-to-spec conversions.

Design Recipe

1. Pick tools first — only use toolRef values from npa/src/npa/orchestration/npa_workflow/catalog.py. Add catalog entries before inventing shell.
2. Name the story — one sentence in metadata.description (what flows where).
3. Config layout (beauty convention):
   • bucket, prefix, runtime knobs (vlm_backend, iteration counts)
   • blank line
   • URI keys grouped (*_uri) built from s3://{{config.bucket}}/{{config.prefix}}/…
4. Graph patterns:

   Pattern	YAML shape
   Linear chain	next: edges
   Fan-in deps	needs: (ordering hints only)
   Fixed repeat	loop.max: "{{config.attr}}"
   Dynamic exit	loop.until: promote_checkpoint
   Runtime branch	transitions + writesDecision: true on the decision state

5. Decision states — any state that writes config.decision_uri must set writesDecision: true (never rely on a magic state name like decide).
6. Terminal — every completion leaf needs terminal: true.
7. Validate early — missing {{config.*}} and bad loop bounds fail at validate-spec, not at plan/execute.

Beauty Checklist

• apiVersion: npa.workflow/v0.0.1 + kind: Workflow at top
• Fold long descriptions with > under metadata.description
• One blank line between config runtime keys and URI keys
• resources profiles referenced by states.*.resources
• State description on every node
• inputs / outputs with uri + schema labels when artifacts cross stages
• Prefer toolRef over run.shell

Creative Example (reference)

workflows/testing/tokenfactory-cosmos-gate.yaml — Token Factory reason → Cosmos augment → VLM critique loop with promote / re-augment gate.

Generate + Verify

# 1. Write YAML under workflows/testing/
# 2. Validate structure + tokens + cycles
npa/.venv/bin/npa workbench workflow validate-spec <new.yaml> --json

# 3. Plan (use --assume-decision when transitions exist)
npa/.venv/bin/npa workbench workflow plan-spec <new.yaml> \
  --run-id creative-demo --assume-decision loop_back --json

# 4. Register in tests — add filename to:
#    - npa/tests/orchestration/npa_workflow/test_spec.py parametrize
#    - npa/tests/smoke/test_npa_workflow_smoke.py parametrize
#    - skills/index.yaml npa_workflow_yaml smoke list (optional)

npa/.venv/bin/python -m pytest npa/tests/orchestration/npa_workflow/ \
  npa/tests/smoke/test_npa_workflow_smoke.py npa/tests/smoke/test_all_workflow_yamls.py -q

Anti-Patterns

• Do not add sim2real engine.py stages — specs invoke catalog tools only.
• Do not use Jinja, eval, or shell for control flow.
• Do not create transition cycles — validation rejects unbounded graphs.
• Do not hardcode bucket/project IDs — use example-bucket placeholders.