cmw-platform

name

cmw-platform

description

Use when working with Comindware Platform — connecting to platform, listing applications, exploring templates, managing records, querying data, creating or editing attributes, or any task requiring autonomous platform interaction. Triggers on platform operations, CMW queries, tenant management, rental lot operations, debt tracking, or record CRUD. Also triggers when user mentions working directly with API credentials, using manual HTTP approaches, or trying to bypass the tool layer. ALSO triggers when user mentions browser automation, UI-only features, visual verification, or accessing platform features not available via API.

CMW Platform Skill

Enables autonomous interaction with Comindware Platform using tools from the agent's tools/ directory.

Browser Use: Browser automation for UI-only features and visual verification.

Four browser options available out-of-the-box:

• agent-browser MCP — tool-based, token-efficient, Chrome-only. Best for agent workflows.
• playwright MCP — tool-based, cross-browser, rich snapshots with element refs. Best for complex UI and debugging (headed by default).
• agent-browser CLI — shell command, persistent sessions, Chrome-only. Best for standalone PowerShell scripts with session reuse.
• playwright-cli — shell command, cross-browser, advanced features (PDF, network, tracing). Best for cross-browser testing scripts.

All four are configured in ~/.config/opencode/opencode.json. Full guidance + decision matrix in Section 2 below.

---

1. Core Concepts

Platform Terminology

Critical: Use human-readable terms, never expose API terms to LLMs:

API Term	Human-Friendly	Notes
alias	system name	Entity identifier
instance	record	Data entry
user command	button	UI action
container	template	Application/template
property	attribute	Field/column
dataset	table	List view. Also called список or list by users
list	table	Table view in template
solution	application	Business application
scheme	process diagram	Visual workflow
trigger	scenario	Automation logic
workspace	navigation section	Navigation section
card	card view	Card view for a table (not a form)
task	task	User task

Guiding Principles

Persist Context. Read Before Write. Idempotent Operations. Explicit Over Implicit.

→ See also: references/principles.md

Workflow

Always follow: Intent → Plan → Validate → Execute → Result

Workflow order: API → tools → browser

1. OpenAPI / KB — cmw_open_api/web_api_v1.json, system_core_api.json, solition_api.json; MCP get_knowledge_base_articles when behavior is unclear.
2. Agent tools — tools/ (create_edit_record, list_template_records, requests_ helpers) before raw HTTP or UI.
3. Browser — only for UI-only actions, visual proof, or when API paths fail after spec review (e.g. Staff Attach account when IncludeInContainer returns 500 on some hosts).

→ Staff login link: cmw-platform-staff-account-link
→ Process instance demo fill: cmw-platform-process-record-fill

Tool Usage Discipline

• Check for duplicate calls before invoking
• Transform results to human-readable format (never raw JSON)
• Validate required context before execution

Browser Automation vs API

When to use Browser Automation:

• UI-only features (visual configuration, drag-and-drop)
• Visual verification (screenshots, layout validation)
• Features not available via API
• Complex multi-step UI workflows

When to use API:

• Data operations (CRUD on records)
• Bulk operations
• Programmatic access
• Performance-critical tasks

Tool Invocation Pattern

from tools.applications_tools.tool_list_applications import list_applications

result = list_applications.invoke({})
if not result["success"]:
    print(f"Error: {result['error']}")
    return
print(result["data"])

Knowledge Base

When uncertain about platform behavior, call the MCP tool get_knowledge_base_articles from the Comindware knowledge base server. Never use ask_comindware MCP tool.

→ See also: references/knowledge_base.md

Response Structure

{
    "success": bool,      # True if operation succeeded
    "status_code": int,   # HTTP status code
    "data": list|dict,     # Response payload
    "error": str|dict      # Error details if success=False
}

System Prompt Alignment

For platform ops, agent_ng/system_prompt.json is PRIMARY (agentic behavior); AGENTS.md is SECONDARY (project work).

→ See also: references/system_prompt_alignment.md

Save Before Edit

ALWAYS save schemas and data BEFORE editing or deleting:

# Save to cmw-platform-workspace/ immediately after fetching
cp Step1_Schema_GET.json cmw-platform-workspace/Step1_Schema_BEFORE.json
# ... make changes ...
cp Step2_Schema_GET_AFTER.json cmw-platform-workspace/Step2_Schema_AFTER.json

This is NOT optional. Violating this rule has caused data loss before.

→ See also: references/tool_inventory.md, references/api_endpoints.md → See also: references/working_files.md for the fetch-and-save pattern + file naming convention.

---

2. Browser Automation

Use browser automation when the operation is not available via API. All four options are pre-configured in ~/.config/opencode/opencode.json.

Decision Guide

Scenario	Use
Agent conversation, Chrome OK	agent-browser MCP — most token-efficient (~5.7× vs Playwright)
Cross-browser / visual debugging / complex forms	playwright MCP — headed by default, rich [ref=eN] snapshots
Standalone script, persistent sessions, Chrome OK	agent-browser CLI — named sessions survive shell restarts
Standalone script, cross-browser, PDF / tracing	playwright-cli — no session persistence, full Playwright feature set

When to Use Browser vs API

Operation	Use API	Use Browser
List records	✅ Fast, structured	❌ Slow, parsing needed
Create/edit attributes	✅ Direct, reliable	❌ Complex UI navigation
Visual workflow designer	❌ No API	✅ UI-only feature
Admin panel configuration	⚠️ Limited API	✅ Full access
Verify UI changes	❌ Can't see UI	✅ Screenshots
Extract UI table data	⚠️ If no API	✅ Fallback option

Quick Invocation Reference

agent-browser MCP (tool calls in agent, see browser_automation.md):

browser_new_session → browser_navigate → browser_snapshot → browser_click / browser_fill → browser_screenshot → browser_close_session

playwright MCP (tool calls in agent — headed by default):

playwright_browser_navigate → playwright_browser_snapshot → playwright_browser_fill_form / playwright_browser_click → playwright_browser_take_screenshot

⚠️ Re-snapshot after every DOM-changing action — refs ([ref=eN]) invalidate on navigation.

agent-browser CLI (PowerShell):

agent-browser open "https://host/" ; agent-browser snapshot -i ; agent-browser fill @e14 "user" ; agent-browser screenshot out.png

playwright-cli (PowerShell):

playwright-cli open "https://host/" ; playwright-cli snapshot ; playwright-cli fill e14 "user" ; playwright-cli screenshot page.png

The flows above use short names; your MCP host may namespace tools (names differ by client). Example full names used in this skill’s reference: agent-browser_browser_*, playwright_browser_* — see MCP Tool Interface Reference. Call whatever appears in your client’s tool list.

Credentials

Always load from .env — never hardcode. See references/browser_automation.md for Python and PowerShell patterns.

CMW Platform URL Patterns

See references/browser_automation.md for the entity ID prefix registry (oa.{N}, event.{N}, etc.), all admin/template/form URL patterns, and the resolve_entity tool reference.

Best Practices

1. Snapshot → Act → Re-snapshot — after every DOM-changing action
2. Save before edit — screenshot current state before destructive changes
3. Session isolation — unique session_name / sessionId per workflow
4. Headed for debugging, headless for automation
5. PowerShell, not bash — use ; not &&, Get-Content not cat

→ See also: references/browser_automation.md — full tool lists for all 4 options, CMW Platform URL patterns, troubleshooting, platform testing lessons

---

3. Exploration

Explore application structure systematically.

Workflow: Discover Application

from tools.applications_tools.tool_list_applications import list_applications
from tools.applications_tools.tool_list_templates import list_templates
from tools.templates_tools.tool_list_attributes import list_attributes

# Step 1: List applications
apps = list_applications.invoke({})
target_app = next(
    (a for a in apps["data"] if "target_application" in a["Name"]),
    None
)

# Step 2: List templates in application
templates = list_templates.invoke({
    "application_system_name": target_app["Application system name"]
})

# Step 3: Get schema for each template
for tmpl in templates["data"][:5]:
    attrs = list_attributes.invoke({
        "application_system_name": target_app["Application system name"],
        "template_system_name": tmpl["Template system name"]
    })

Utility Script

For batch exploration, use explore_templates.py.

→ See also: references/workflow_sequences.md — ready-made scripts and usage patterns.

---

4. Data Operations

Query Records with Filters

from tools.templates_tools.tool_list_records import list_template_records

result = list_template_records.invoke({
    "application_system_name": "your_app",
    "template_system_name": "your_template",
    "filters": {"SomeAttribute": {"$gt": 30}},
    "limit": 100
})
if result["success"]:
    for record in result["data"]:
        print(record["id"], record.get("Name", ""))

Create a Record

from tools.templates_tools.tool_create_edit_record import create_edit_record

result = create_edit_record.invoke({
    "operation": "create",
    "application_system_name": "your_app",
    "template_system_name": "your_template",
    "values": {
        "AttributeName": "value",
        "AnotherAttribute": 123.45
    }
})

Pagination

Hard limit: 100 records per request. Paginate using offset:

def fetch_all(app_name: str, template: str, page_size: int = 100):
    all_records = []
    offset = 0
    while True:
        result = list_template_records.invoke({
            "application_system_name": app_name,
            "template_system_name": template,
            "limit": page_size,
            "offset": offset
        })
        if not result["success"] or not result["data"]:
            break
        all_records.extend(result["data"])
        if len(result["data"]) < page_size:
            break
        offset += page_size
    return all_records

Utility Scripts

For script-backed data operations, use:

• query_with_filter.py
• analyze_stats.py
• batch_edit_attributes.py

→ See also: references/workflow_sequences.md — ready-made scripts, batch edit workflow, and usage examples.

---

5. Import/Export Applications

Use import/export when you need to move an entire application in CTF form.

• Export — create a CTF package for a full application
• Import — upload and apply a CTF package to create or update an application

→ See also: references/import_export.md → See also: references/api_endpoints.md

---

6. UI Components

Datasets, Toolbars, and Buttons are separate API entities with different endpoints:

Entity	Tool to Get	Tool to Edit
Dataset	get_dataset	edit_or_create_dataset
Toolbar	get_toolbar	edit_or_create_toolbar
Button	get_button	edit_or_create_button

Keep these core rules in mind:

• Create-kind buttons require create_form
• Toolbar item names override button display names
• Dataset-specific toolbars should not be shared blindly across datasets
• Verify UI component edits via API, not only via the UI, because the UI may cache stale state

→ See also: references/ui_components.md → See also: references/tool_inventory.md → See also: references/workflow_sequences.md

---

7. Localization (System Names)

Two distinct workflows — choose before starting:

Goal	Workflow
Rename system names / aliases	Workflow A — 9-phase process with platform restart and CTF round-trip
Translate Russian UI strings to English	Workflow B — harvest → translate → apply → CSV

→ See also: references/localization.md — both workflows in full detail, phase map, suffix rules, tool_localize, step scripts, type/predicate mappings.

---

8. Troubleshooting

Error Handling

Status	Meaning	Action
401	Bad credentials	Check .env configuration
408	Query timeout	Reduce limit parameter (max 100)
500	Server error	Retry with exponential backoff

Retry Pattern

import time

def retry_with_backoff(func, payload, max_retries=3, delay=1):
    for attempt in range(max_retries):
        result = func.invoke(payload)
        if result["success"]:
            return result
        if result.get("status_code") in (500, 503, 408):
            time.sleep(delay * (2 ** attempt))
            continue
        return result
    return {"success": False, "error": "Max retries exceeded"}

Safe Attribute Translation

→ See also: references/edit_or_create.md — required fields per type, per-tool validation rules, and partial-update mechanics.

Diagnostic Script

Use diagnose_connection.py to verify platform connectivity. Exit code 0 = pass, 1 = fail.

→ See also: references/errors.md — diagnostic command and recovery guidance.

Switching platform instance (host / tenant)

Before cross-host work or comparing reference vs target (e.g. TR vs FR), switch CMW_BASE_URL, force dotenv for scripts, and verify connectivity — read-only first when diffing instances.

→ cmw-platform-instance-switch/SKILL.md — CMW_BASE_URL, load_dotenv(override=True), CMW_USE_DOTENV=true, verify, repo boundaries.

Configuration backup (post-change)

After multi-entity or security batches — and between major themed migration edits on a target instance — launch an existing configuration backup via Web API (preferred) or UI fallback.

→ cmw-platform-backup-launch/SKILL.md — GET /webapi/Backup/Configuration → pick existing configurationId → POST /webapi/Backup/Session/{configurationId} (Backup_CreateSession in cmw_open_api/web_api_v1.json); optional poll GET /webapi/Backup/Session/{sessionId}. UI fallback: Configurations tab → checkbox → Start backup. Do not create or delete backup configurations unless the user asks.

Employee record ↔ platform account (Attach account)

After AccountService creates a login, link it to a Staff employee row via the Employees list → Attach account modal (select existing account(s)). This is record-level Include, not account create.

→ cmw-platform-staff-account-link — link field, API order, host caveats; references/employee_account_attach.md — UI modal steps.

---

9. Growing platform skills

Repo boundary (required): references/instance_repo_documentation_boundary.md — what lives in cmw-platform-agent vs {instance_progress_dir}; scratch rules; stubs for moved instance playbooks; RecordType / doc.* scope for process-model docs.

Policy: When you solve a repeatable platform workflow (API or UI), capture it for the next agent — do not leave the recipe only in chat or scratch scripts.

• Mandatory wave-end documentation: After any batch/wave that discovers new API or UI manipulation patterns, append an agnostic subsection to references/platform_usage_discoveries.md (or extend an existing reference) before ending the session wave or claiming done. Placeholders only ({source_host}, {target_host}, {instance_progress_dir}) — no tenant hosts or record ids in skill bodies. Instance operations[] flush stays mandatory in parallel. Recent wave examples: grouped MaintenanceExecution lists vs API count, MyMaintenance dataset PUT path (405 on Dataset@), staff id vs platform account for USER() filters, StatusBoost legacy OBJECT() expressions, ServiceRequestTypes SLA remap, PMPlans seed-driven equipment create-link, Spaces semi-empty hierarchy gap-fill.
• Parent agents delegate long-running execution to background subagents; the parent coordinates and merges results. Instance migration progress (themed batch JSON, id maps, operator checklists) lives in {instance_progress_dir} only — not in cmw-platform-agent docs/_scratch/.
• JSON over agent memory: Read and write {instance_progress_dir}/localization/migration_progress/*.json for every batch — meta.status, root map[], meta.errors, backup_pending, retry_count, agent_wave, timestamps. Never rely on a prior chat turn for record id maps. Harvest/seed patterns: references/record_harvest_seed.md; instance batch schema in {instance_progress_dir}/localization/migration_progress/README.md.
• Mandatory progress flush: After each batch/wave, also write {instance_progress_dir}/docs/localization/progress_reports/YYYYMMDD_*.md — tenant rules and checklists live under {instance_progress_dir}/.agents/skills/ and {instance_progress_dir}/localization/AGENTS.md.

Where to save

Kind	Location
Multi-step API workflow (own trigger)	.agents/skills/cmw-platform-<topic>/SKILL.md
Detail, OpenAPI shapes, UI steps for one entity	.agents/skills/cmw-platform/references/<topic>.md
Repeatable CLI (backup, accounts, harvest/seed)	.agents/skills/cmw-platform/scripts/ — index references/scripts_index.md
Browser-only entity recipe	Extend references/browser_automation.md or the relevant reference (e.g. employee_account_attach.md)

Do not use cmw-platform-agent docs/_scratch/ for instance migration (harvest JSON, phase runners, batch results). That folder stays empty; instance scratch is {instance_progress_dir}/docs/_scratch/ only. Do not scatter one-off notes in platform docs/_scratch/ or commit empty stub skills. Prefer enriching an existing reference over duplicating a thin skill.

Where to document findings

Scope	Repository	Put it here
Instance-specific	{instance_progress_dir}	Migration progress JSON, plans, gap analyses, harvest outputs, operator checklists, model-export audits
Platform-generic	cmw-platform-agent (this repo)	.agents/skills/cmw-platform* and references/, companion skills, docs/ — reusable API/UI/OpenAPI patterns

Do not duplicate long-form instance audits here; capture a one-paragraph generic lesson in a reference (e.g. localization.md, consolidated FM/demo lessons in references/platform_usage_discoveries.md).

Order of approach (reinforced)

1. OpenAPI — cmw_open_api/web_api_v1.json and public Object API where documented.
2. Existing agent tools — tools/ and references/tool_inventory.md.
3. Existing skills/references — search .agents/skills/cmw-platform* before inventing HTTP.
4. Browser last — only when API/tools cannot do the job (see § Browser Automation vs API).

Parallel subagents (independent templates)

When templates or entity groups have no cross-record dependencies, the parent coordinator may run parallel background subagents (one template per agent) for speed. Every spawn prompt: source-form-first — open read-only source record form before API; datamodel alone is insufficient (ralph_loop_goal_autonomy.md). Instance waves: {instance_progress_dir}/localization/AGENTS.md.

Avoid parallel on:

• Same template writes — concurrent PUT/POST on the same dataset or records risks races and partial state.
• Backup POST — configuration backup launch (cmw-platform-backup-launch); serialize with other instance-wide mutations.
• AccountService bulk on the same accounts — create, edit, password, group membership on overlapping login ids.
• Single process instance — one running work order / Sobytiya row (workflow state, transitions, form fill).

Backup: One backup per milestone after the parallel wave completes, not one per subagent. Coordinator or last finishing agent sets backup_pending: true in instance migration_progress/ JSON; one agent runs backup before the next milestone.

Prefer subagent hives over foreground duplication — delegate independent template work to background subagents rather than repeating harvest/seed/API steps in the parent chat.

Autonomous migration waves (instance work): Parent runs up to 6 parallel background subagents per wave, then reconciles roadmap and one target backup; commit instance repo only. Full loop: {instance_progress_dir}/localization/AGENTS.md · {instance_progress_dir}/.agents/skills/ralph-loop-instance/SKILL.md.

Ralph-style iteration (goal autonomy): Fresh context + disk JSON verification + same wave prompt — references/ralph_loop_goal_autonomy.md. Instance runbooks: {instance_progress_dir}/docs/localization/ and {instance_progress_dir}/.agents/skills/ralph-loop-instance/SKILL.md. Do not enable Ralph Loop plugin stop-hook while parallel subagents are active.

Background shell (long platform scripts)

For better async, run long CLI in background (Shell run_in_background or adequate block_until_ms), then poll outputs — do not block the parent chat on harvest/seed/backup.

Script (under .agents/skills/cmw-platform/scripts/)	Typical use
harvest_template_records.py	TR read-only template harvest
seed_records_from_harvest.py	FR create/update from harvest JSON
backup_configuration_session.py	FR config backup (--poll until complete)
Multi-record migrate helpers	Themed batch API writes

Within a subagent: parallel subagents for independent templates; inside one agent, long scripts → background terminal + poll migration_progress/*.json or script stdout until done.

High-concurrency note: when several agents run in parallel, avoid importing the full tools package for tiny one-off maintenance jobs if a lightweight Web API script is enough. Full tool imports may compete on cmw-agent.log rollover in busy waves. Prefer direct requests + dotenv + explicit --base-url for simple harvest/seed/backup helpers, write durable JSON progress, and rotate or ignore local log files rather than blocking the wave.

API skill examples (companion skills)

Topic	Skill / reference
Configuration backup launch	cmw-platform-backup-launch
Host / tenant switch	cmw-platform-instance-switch
Account create, password, groups	cmw-platform-account-bootstrap
Employee row ↔ login (Include)	cmw-platform-staff-account-link + references/employee_account_attach.md
Running process / work order row fill	cmw-platform-process-record-fill + references/process_record_demo_fill.md
Tenant hierarchy / themed migration (instance)	{instance_progress_dir}/.agents/skills/ (e.g. cmw-platform-fm-hierarchy-seed, ralph-loop-instance) and {instance_progress_dir}/localization/AGENTS.md — stubs: tr_fr_record_harvest_seed.md, us_fm_ru_to_en_replication.md
Demo fill / migration usage (indicators, Code_calc, gap-fill, multi-list WO orchestration, Administration sweep, inspection form vs API, cross-instance id rule, MaintenanceExecution grouped lists, MyMaintenance dataset PUT, staff vs account assignee, StatusBoost legacy expr, ServiceRequestTypes SLA remap, PMPlans equipment seed-link, Spaces semi-empty)	references/platform_usage_discoveries.md
Process model templates (doc.XXXX), five areas + form PUT safety	references/process_model_template_localization.md
Entity display names (any tenant; aliases unchanged; PUT no-op)	references/entity_display_name_localization.md
Record instance rows in list views (#data/…/lst.M/)	references/record_instance_field_localization.md
EN target RU leftovers (instance playbook; Patterns A–E)	{instance_progress_dir}/.agents/skills/cmw-platform/references/en_template_ru_leftover_cleanup.md (instance repo only — platform stub redirects)

Browser recipes (entity-specific)

Refine existing skills/references with tested selectors and hash routes — do not fork parallel docs.

Entity / flow	Where to extend
Employees → Attach account modal	references/employee_account_attach.md
Backup → checkbox + Start backup	cmw-platform-backup-launch UI fallback
Datasets, toolbars, buttons	references/ui_components.md, references/browser_automation.md
Processes / scenarios	references/browser_automation.md URL patterns
Source structure forms (read-only business context)	Instance skills under {instance_progress_dir}/.agents/skills/ — open source forms before datamodel-only reads (ralph_loop_goal_autonomy.md)

Naming

• Companion skills: cmw-platform-<topic> in kebab-case (directory name matches).
• References: snake_case.md under references/, linked from this skill’s index.

Authoring new skills

Follow Cursor’s create-skill guidance for frontmatter, description triggers, and progressive disclosure.

Repo boundary: {instance_progress_dir} owns instance migration state and audits; cmw-platform-agent owns repeatable platform recipes — see Where to document findings and instance_repo_documentation_boundary.md.

---

Reference Index

Document	Purpose
references/principles.md	Guiding principles for all platform work
references/working_files.md	Fetch-and-save pattern + workspace file naming
references/edit_or_create.md	edit_or_create_* validation, required fields, partial updates
references/knowledge_base.md	get_knowledge_base_articles MCP usage
references/system_prompt_alignment.md	system_prompt.json vs AGENTS.md precedence
references/tool_inventory.md	Complete tool catalog with signatures
references/api_endpoints.md	HTTP endpoint reference
references/account_bootstrap_api.md	System Core account create, update, password, group (OpenAPI detail)
references/employee_account_attach.md	Staff employee row ↔ platform account (Attach account UI / Include API)
../cmw-platform-instance-switch/SKILL.md	Switch host/tenant (CMW_BASE_URL, dotenv, verify, read-only compare)
../cmw-platform-account-bootstrap/SKILL.md	Account create/update (Create or Edit → password → group)
../cmw-platform-backup-launch/SKILL.md	Launch existing configuration backup (API preferred; UI fallback)
references/import_export.md	Full import/export application reference
references/ui_components.md	Full UI components reference: toolbars, buttons, datasets, forms
references/form_handling.md	Form API workflow: visible FieldComponent creation/upsert, replacement, rollback, verification
references/errors.md	Error handling playbook
references/platform_usage_discoveries.md	Agnostic FM/demo lessons: indicators, Code_calc, gap-fill, dataset PUT endpoint + globalAlias + composite filters, MyMaintenance USER(), MaintenanceExecution grouped lists, staff vs account assignee, StatusBoost legacy expr, ServiceRequestTypes SLA remap, PMPlans equipment seed-link, Spaces semi-empty, contract/annual-plan/inspection patterns, WorkStatus id collision, multi-list WO orchestration, location calc, maintenance/PM/SOP, operations[] flush
references/workflow_sequences.md	Reusable code patterns
references/localization.md	Both localization workflows: alias rename (9-phase) + RU→EN UI text translation
references/browser_automation.md	Browser automation guide
references/instance_repo_documentation_boundary.md	Platform vs instance repo: decision table, scratch, stubs, doc.* process model template scope
references/entity_display_name_localization.md	Display-name localization for templates, datasets, toolbars, buttons, forms, context (API + ontology; PUT no-op; aliases unchanged)
references/process_model_template_localization.md	Localize all doc.XXXX process model templates: enumerate, five-area checklist, form PUT safe patterns, dataset pitfalls
references/record_instance_field_localization.md	Records API scan/PUT for instance rows in #data/{template}/lst.{M}/; pagination; calculated vs writable
§ Growing platform skills	Policy: capture repeatable API/UI workflows as skills or references; instance RU leftover playbook: {instance_progress_dir}/.agents/skills/cmw-platform/references/en_template_ru_leftover_cleanup.md

Optional companion skills (GitHub)

• web-search
• human-search
• searxng-agent-skills
• browser-switch
• deep-research
• agent-browser
• Playwright CLI
• microsoft/playwright

Install: npx skills add (e.g. npx skills add arterm-sedov/web-search-skill --skill web-search).

---