# Create Vitruvio Process (orchestrator)

> All messages shown to the user must be written in Portuguese.

A process is made of up to three artifacts plus a manifest entry:

| Part | Skill that owns it |
|------|--------------------|
| `processes/<key>/<key>.bpmn` (workflow) | **vitruvio-criar-processo-bpmn** |
| `processes/<key>/<key>-desktop.xml` (web form) | **vitruvio-criar-form-desktop** (process variant) |
| `processes/<key>/<key>-mobile.xml` (app form, optional) | **vitruvio-criar-form-mobile** (process variant) |

This skill collects the intent once, drives those skills, and registers the process in
`vitruvio.json`. Do the file work by following the referenced skills — do not re-derive
their templates here.

## Step 1 — Confirm you are inside a Vitruvio repo

```bash
ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"
```

If `NOT_A_VITRUVIO_REPO`, stop and tell the user to `cd` into the correct repo.

## Step 2 — Collect process details

Ask the user (in a single message, only ask what is missing):

- **Key** — snake_case or camelCase unique identifier. Becomes the BPMN process ID and the
  folder name.
- **Name** — human-readable label.
- **Description** — one sentence (optional).
- **Who can start it?** — group key(s) for `activiti:candidateStarterGroups`.
- **Steps** — the human tasks and which group handles each. A simple linear flow is enough.
- **Needs a script task?** — automatic steps running a script between user tasks.
- **Needs a mobile form?** — if yes, a `<key>-mobile.xml` is created too. Remember mobile is a
  different schema with explicit data wiring — variables, lookups and libs must be named
  up front (the mobile skill will ask).

## Step 3 — Scaffold

```bash
vitruvio new process <key> --name "<name>"
```

This creates `processes/<key>/<key>.bpmn`, `processes/<key>/<key>-desktop.xml`, and the
`vitruvio.json` entry. Then replace the generated files using the focused skills:

1. **BPMN** — follow **vitruvio-criar-processo-bpmn** to write `processes/<key>/<key>.bpmn`
   from the user's steps/branches.
2. **Desktop form** — follow **vitruvio-criar-form-desktop** (process variant) to write
   `processes/<key>/<key>-desktop.xml`, one `<form formKey>` per `activiti:formKey` in the BPMN.
3. **Mobile form (if requested)** — follow **vitruvio-criar-form-mobile** (process variant) to
   write `processes/<key>/<key>-mobile.xml`. `vitruvio new` does not create it.

## Step 4 — Update vitruvio.json entry

`vitruvio new` already added the entry. Full shape:

```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description>",
  "bpmn": "processes/<key>/<key>.bpmn",
  "forms": {
    "desktop": "processes/<key>/<key>-desktop.xml"
  },
  "schedules": []
}
```

- Add `"description"` if the user provided one — `vitruvio new` does not set it.
- If a mobile form was created, add `"mobile": "processes/<key>/<key>-mobile.xml"` inside `"forms"`.
- Add `schedules` only if the process runs on a timer (cron/simple interval).

## Step 5 — Report

Tell the user:
- Files created: `<key>.bpmn`, `<key>-desktop.xml` (and `<key>-mobile.xml` if applicable).
- Registered in `vitruvio.json` with key `<key>`.
- The process identity is the `<bpmn2:process id>` — it must match the key.
- Each `activiti:formKey` in the BPMN must have a matching `<form formKey="...">` in **every**
  form file (desktop and mobile).
- Submitted field `id="X"` in `formKey="formAbertura"` becomes process variable `formAbertura_X`
  (desktop auto-injects these; mobile must declare/fetch them — see vitruvio-criar-form-mobile).
- For complex flows, recommend editing the BPMN in bpmn.io or Camunda Modeler before deploying.