git:20260913.61b838c to git:20260921.665df0e

- # 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 -->