CLAUDE.md git:20260921.665df0eA

Immutable. This exact content never changes and is served at /api/v1/blob/2176778c0008928d.

# PROCESIO CLI + Agent

Instructions for an AI assistant working in this repository. A human reader wants
[README.md](README.md) instead.

Command-line tooling and an AI agent for the PROCESIO automation platform: drive processes, forms, documents and custom actions from a terminal or from an AI coding assistant.

## What this repo is

A registry of **tools** and **agents** for the PROCESIO automation platform. A tool is
a script that talks to PROCESIO. An agent carries method rather than mechanics: it
drives tools and knows how the work should be done. Both are discovered from their
manifests, so nothing anywhere holds a hardcoded list.

```
python scripts/list-tools.py                    # what exists, and whether it is ready
python scripts/run-tool.py procesio --help      # every action and its arguments
python scripts/run-agent.py procesio guidance   # the build-and-test playbook
```

The capability router at the bottom of this file maps a request to the command that
serves it. It is generated from the manifests, so trust it over your memory of an
earlier session.

## The contract

1. **JSON in, JSON out.** A tool prints exactly one JSON object on stdout for success,
   or `{"error": {"code", "message", "details"}}` for failure, and exits non-zero on
   failure. Progress and debug output go to stderr only. Never print anything else to
   stdout: a caller is parsing it.
2. **The manifest is the source of truth.** `tool.yaml` declares actions, arguments,
   secrets and output. The registry reads manifests; everything else reads the
   registry. Change the manifest in the same commit as the contract it describes.
3. **Regenerate what is generated.** After a manifest change run
   `python scripts/build-tool-skill.py <tool>` and `python scripts/build-router.py`.
   A stale generated file is worse than a missing one, because it will be believed.
4. **No secrets in files.** Ever. Credentials live in the OS credential store under
   `agents-and-tools:<tool>:<secret>` and are read through `tools/_lib/creds.py`.
   `python scripts/secret_scan.py` enforces this over the tree and refuses anything
   credential-shaped. Never log, print or commit a secret value.
5. **Framework and user data are separate.** `tools/`, `agents/` and `scripts/` are
   shareable code and carry zero user-specific data. Everything about a particular
   user or installation, including the environment registry and credential profiles,
   lives under `context-state-knowledge/`, which is never versioned. Resolve those
   paths through `tools/_lib/userdata.py`, never by hand.

## Credentials

Which store is used follows the platform, with no configuration: Windows Credential
Manager, the macOS login Keychain, or the Linux desktop keyring. A headless machine
has no OS keyring, so choose one explicitly with `AAT_CREDS_BACKEND`:
`encrypted-file` (read/write, passphrase in `AAT_SECRETS_PASSPHRASE`), or `file` / `env`
for secrets a host or cluster already manages. See `tools/_lib/README.md`.

Store a credential with `python scripts/set-credential.py <tool> <secret>`. Never write
one into a file, an argument, or a config, and never echo one back to the user.

## Working on a PROCESIO process

`tools/procesio/` holds the mechanics: the API client, the DTOs, the flow model, the
canvas layout engine, and one handler per action. Its long-form notes
(`PROCESIO-*-NOTES.md`) record non-obvious platform behaviour discovered the hard way,
and they are the first place to look when the API does something surprising.

`agents/procesio/` holds the method: the build-and-test playbook, the best practices,
and the verify gate. Before building or changing a process, read
`python scripts/run-agent.py procesio guidance`. Before calling one done, run
`python scripts/run-agent.py procesio verify --process-id <id>` - a process that
validates is not the same as a process that runs.

## Adding a tool

1. Create `tools/<name>/` with a `tool.yaml`, an entrypoint, and a `README.md`.
2. Declare every secret under `secrets:`. The registry reports `missing_secrets` until
   they are stored, which is how "not configured" stays distinct from "broken".
3. Generate its manual: `python scripts/build-tool-skill.py <name>`.
4. Confirm it appears in `python scripts/list-tools.py`.

Write anything you learn about an external system into a durable note in that tool's
own folder in the same session you learn it. A discovery that lives only in a chat is
gone by the next one.

## Capability Router (auto-generated)

<!-- CAPABILITY-ROUTER:START — generated by scripts/build-router.py; rerun after adding/removing a tool. Do not hand-edit. -->

### Tools — run with `python scripts/run-tool.py <tool> <action> [--args]`

- **connector-builder** — build a PROCESIO custom action / connector from API docs; generate a .nupkg connector for PROCESIO from documentation; create / run / drive an AI Connector Builder build; approve / revise the plan / regenerate files / download the connector artifact; edit the connector builder's prompts / spec modules / examples (improve generation) → `connector-builder create-build --api-url <docs-url> --user-requirements '...'   (then gather / answer / approve-plan / approve-generate / download-artifact)`
- **framework-map** — regenerate / rebuild the framework map or the agents-and-tools visualization; update the framework HTML with the new tools / agents / mechanics; refresh the agents and tools diagram / presentation page; which tools or agents changed / still need an RO translation; build the bilingual framework map (EN/RO) → `framework-map build   (dry-run counts + untranslated: framework-map check)`
- **mysql** — run a MySQL query; query a MySQL / MariaDB database; read a table from MySQL; list MySQL tables or columns → `mysql query --profile default --sql "SELECT * FROM issues LIMIT 10"`
- **procesio** — procesio; run a procesio process; launch procesio process; procesio workspace; procesio api; list procesio processes; procesio instance; trigger procesio flow; procesio endpoint; export procesio; procesio export; import procesio / import a .procesio bundle; duplicate a process / copy a process / clone a process; delete a process / form / document / webhook / credential; validate a process (correctness oracle); test a credential connection / test a custom action; upload / install / delete / list a custom action (.nupkg connector); download a flow-instance file (Generate-Document output); layout / re-lay-out a process canvas; read or inspect a flow graph; list forms / list documents; get or toggle a process; AI Decisional; switch procesio environment / work on PROCESIO Internal-QA / Internal-DEV / a client env; list / add / set the default procesio environment (<Client>-<ENV>); bind a credential to an environment; run procesio against QA / DEV / staging / a client installation → `procesio list-processes   (run: procesio run-process --id <id> --payload '{...}')`
- **sqlserver** — run a SQL Server query; query a SQL Server / MSSQL database; read a table from SQL Server; list SQL Server tables or columns → `sqlserver query --profile default --sql "SELECT TOP 10 * FROM dbo.Customer"`
- **web** — drive/scrape a website that has no API, using a saved login session; deeper web research → `web run --session <name> ...   (read text: web get-text; one-time login: web save-session)`
- **xlsx** — Read local Excel (.xlsx/.xlsm) workbooks - list sheets, read a sheet as JSON, or dump the whole file to text → `xlsx list-sheets`

### Agents — run with `python scripts/run-agent.py <agent> <action> [--args]`

- **connector-builder** — build a PROCESIO custom action / connector from API docs and test it; drive the AI Connector Builder end to end (gather → plan → generate → compile); what's the next step for this connector build; upload a generated connector to PROCESIO and improve it from the feedback; how do I run the connector build → test → improve loop → `connector-builder next-step --build-id <ID>   (checklist: connector-builder checklist; guidance: connector-builder guidance --topic playbook; status: connector-builder status)`
- **procesio** — build a procesio use case; test / verify a procesio process or resource; audit a procesio process for best practices; how should I build / test in procesio; improve a procesio implementation → `procesio verify --process-id <id>   (audit: procesio audit --process-id <id>; guidance: procesio guidance; checklist: procesio checklist)`

### Skills

Claude **auto-triggers** these from their descriptions — do NOT run-tool them. Project agents discover them via the registry and load one's full content with `python scripts/get-skill.py <name> --content`.

**Registered in this project** — run `python scripts/list-skills.py` (`skills/<name>/`):

- **agent-skill-engineer** — create, update, split, merge, refactor, or audit an Agent Skill or SKILL.md package; optimize skill descriptions, routing boundaries, progressive disclosure, context cost, or safety; design fixed-rubric skill evaluations, baselines, A/A noise checks, A/B comparisons, or field trials → `get-skill.py agent-skill-engineer`
- **procesio-cli** — operate or troubleshoot a PROCESIO workspace through the CLI or MCP; create, edit, run, validate, audit, export, import, schedule, trigger, test, or verify a PROCESIO resource; inspect a PROCESIO process instance, form, document, webhook, credential, data model, or custom action → `get-skill.py procesio-cli`
- **procesio-cli-maintainer** — change or review the procesio-cli repository source, manifests, tools, agents, MCP, registry, CI, or tests; add an action or capability while preserving JSON, credentials, routing, generation, and reversibility contracts; integrate an already-designed Agent Skill into repository generation, translations, governance, or release controls → `get-skill.py procesio-cli-maintainer`
- **procesio-platform-advisor** — assess PROCESIO product fit, feasibility, architecture, pricing, sizing, or compliance; compare PROCESIO with another automation or integration platform; decide which processes to automate without changing a workspace → `get-skill.py procesio-platform-advisor`
- **sql-server-optimizer** — analyze or optimize SQL Server T-SQL, execution plans, indexes, logical reads, blocking, or parameter sniffing; review SQL used in a PROCESIO Execute Query or Execute Command action; replace unsafe PROCESIO inline SQL variables with native typed parameters → `get-skill.py sql-server-optimizer`

<!-- CAPABILITY-ROUTER:END -->