agentleFS
Procesio-ExternalsProcesio-Externals/procesio-cli/CLAUDE.md

procesio-cli

CLAUDE.md5 starsChanged 3 months agoApache-2.0View on GitHub

Instructions for an AI assistant working in this repository. A human reader wants 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. 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.…

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Regenerate what is generated: After a manifest change run python scripts/build-tool-skill.py <tool> and python scripts/build-router.py.

    line 34
  2. Very specific:

    Create tools/<name>/ with a tool.yaml, an entrypoint, and a README.md.

    line 73
  3. Distinctive:

    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.

    line 79

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

PROCESIO CLI + Agent

Instructions for an AI assistant working in this repository. A human reader wants 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; what is this process for / read a process's documented purpose, action purposes and canvas areas; which processes in this workspace are undocumented / map a workspace I do not know; see a process in the designer / screenshot a process canvas / check how the areas and actions look; list forms / list documents; get or toggle a process; AI Decisional; switch procesio environment / work on PROCESIO Main-QA / Main-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; render an HTML page to an image / make a blog cover, social card or banner image from HTML; render HTML to a PDF → 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
  • procesio-setup — Connect this installation to a PROCESIO workspace, so the MCP server and the CLI can reach it → get-skill.py procesio-setup
  • 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 -->

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.