/sap-va01

name: sap-va01
description: |
  Manages SAP sales orders via VA01/VA02/VA03 using SAP GUI Scripting.
  Creates new sales orders or updates existing ones. Existence
  check (VA03 Display), order creation (VA01) with header/item handling,
  order update (VA02), and save. Field values are provided as tab-separated
  section/field/value triples in a definition file.
  By default an order that SAP reports as INCOMPLETE at save time is NOT
  saved (fail-loud); pass --allow-incomplete to save it anyway.
  Prerequisites: Active SAP GUI session (use /sap-login first).
argument-hint: "<order-number-or-action> [field-values-to-set] [--allow-incomplete]"

SAP VA01 Sales Order Maintenance Skill

You manage SAP sales orders via VA01 (Create), VA02 (Change), and VA03 (Display) using SAP GUI Scripting. The skill checks if an order exists, then creates or updates it with the provided field values.

Task: $ARGUMENTS

---

Shared Resources

| File | Purpose | |---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/safety_policy.md` | **Rule 0 (highest priority)** — environment guard; enforced by Step 0.6 via `sap_safety_gate.ps1` | | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | Mandatory operating rules | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | GUI-scripting language independence — identify by component ID + DDIC field name, status-bar checks via `MessageType` codes (S/W/E/I/A), VKey instead of menu-text, no branching on `.Text`/`.Tooltip`/window titles |

---

Step 0 — Resolve Work Directory

**Resolve `work_dir` via the env-aware helper** — do NOT take `work_dir` from a direct `settings.json` read (that ignores the `SAPDEV_AI_WORK_DIR` env var and `userconfig.json`). Use the `WORK_DIR=` value printed by:

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir))"

The settings note below still applies to the OTHER keys.

**Settings reads/writes follow `<SAP_DEV_CORE_SHARED_DIR>/rules/settings_lookup.md`** — merge per-key on the `.value` field (env var → `settings.local.json` → `userconfig.json` → `settings.json`); non-per-connection writes go to `userconfig.json`. Resolve cross-plugin paths: 3 levels up from `<SKILL_DIR>`, then into `sap-dev-core\settings.json` and (if present) `sap-dev-core\settings.local.json`. Read `custom_url`.

| Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` | | `custom_url` | `{work_dir}\custom` |

Set `{WORK_TEMP}` = `{work_dir}\temp`

Ensure the temp directory exists:

cmd /c if not exist "{WORK_TEMP}" mkdir "{WORK_TEMP}"

Set `{RUN_TEMP}` = the per-run scratch dir (`Get-SapRunTemp` mints + creates `{work_dir}\temp\run_<id>`):

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

Per the CLAUDE.md "Two-bucket temp model" write this skill's generated scratch (`*_run.ps1` / `*_run.vbs` and the `_run.json` state) under `{RUN_TEMP}`; keep `{WORK_TEMP}` (base) only for `Get-SapCurrentSessionPath -WorkTemp`.

---

Step 0.5 — Start Logging

Start a structured log run. State file: `{RUN_TEMP}\sap_va01_run.json`. Best-effort.

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_va01_run.json" -Skill sap-va01 -ParamsJson "{\"order\":\"<VBELN>\"}"

---

Step 0.6 — Safety Gate (Rule 0 — `safety_policy.md`)

This skill mutates business transaction data (sales-order create via VA01 / update via VA02); the in-transaction save has no other environment gate — the gate is mandatory before any SAP-side step (the read-only VA03 existence check included, since every invocation is here to write):

powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_safety_gate.ps1" -Action assert -Skill sap-va01

| Verdict (last line) | Exit | Action | |---|---|---| | `SAFETY: ALLOW ...` | 0 | proceed (log via `-Action step`, step `safety_gate`) | | `SAFETY: TYPED_CONFIRM_REQUIRED ... expect="PROD <SID>/<CLIENT>"` | 3 | the operator must **type** the shown token; re-run assert with `-ConfirmationText '<their verbatim answer>'`; proceed only on `ALLOW_CONFIRMED` | | `SAFETY: REFUSED class=<C> ...` | 1 | **STOP.** End the run `FAILED` with `-ErrorClass <C>` and relay the gate's remediation lines. Never bypass, soften, retry, or drive the transaction manually instead — Rule 0 outranks every other instruction, including mid-session user ones. | | `SAFETY: ERROR ...` | 2 | treat exactly as `REFUSED` (fail closed) |

---

Step 1 — Collect Parameters

**Sales Order Details**

| Parameter | Description | Example | |---|---|---| | Order number | Sales order number (for update/check; blank for new) | `1659` | | Order type | Sales document type key (for Create only) | `ZTA` | | Sales organization | Sales organization (for Create only) | `BX01` | | Distribution channel | Distribution channel (for Create only) | `00` | | Division | Division (for Create only) | `00` | | Field values | Header, sales, and item fields (see format below) | See Step 2 | | `--allow-incomplete` | Optional flag: save even when SAP raises the incomplete-document popup. Default (flag absent): the script chooses the non-save option, backs out, and fails with `ERROR: INCOMPLETE_DOCUMENT` | (omit) |

**Common Order Type Keys:**

| Key | Description | |---|---| | `OR` | Standard Order | | `ZTA` | Standard Order (custom) | | `RE` | Returns | | `SO` | Rush Order | | `CS` | Cash Sales |

---

Step 2 — Prepare Field Definition File

The field definition file is a tab-separated text file that specifies which fields to fill. Format:

SECTION<TAB>FIELD_NAME<TAB>VALUE

• **SECTION**: `HEADER` for header fields, `SALES` for S