SAMO Pilot (Claude Code Plugin)

SAMO Pilot is a Claude Code plugin that gives the AI deep knowledge of SAMO's 3-layer architecture. Once installed, Claude Code can plan, generate, validate, and review SAMO project configurations across all layers — XML metadata, business server JSON, and DynApp frontend JSON.

What It Does

Capability	Description
Plan	Breaks requirements into FeatureTypes and plans all 3 layers (XML metadata, business logic, DynApp UI)
Generate	Produces correct XML definitions, business server JSON configs, DynApp JSON configs, and JS API scripts
Validate	Checks cross-layer consistency — verifies field IDs, references, and naming conventions across XML/business/dynapp
Research	Looks up exact syntax and patterns from SAMO documentation via MCP Server tools

Prerequisites

Requirement	Details
Claude Code	Install Claude Code CLI
Node.js	Required for MCP server execution via npx
@samo npm scope	The MCP server (@samo/mcp-server) is fetched from the SAMO Nexus registry. Configure the scope and log in — see npm setup guide.
GitLab access	Network access to the SAMO GitLab instance for plugin installation and project scaffolding
GitLab access token	Required for project scaffolding. Contact the RDT team or email simon.misak@asseco-ce.com to obtain it.

Installation

Screenshot needed

Terminal showing the /plugin marketplace add command and successful installation output

1. Install Claude Code if you haven't already
2. Open your SAMO project directory and start Claude Code:

   cd your-samo-project/
   claude

3. Add the plugin marketplace:

   /plugin marketplace add git@gitlab:samo/server/tools-implementation/samo-pilot.git

   If you don't have access to the SAMO GitLab, contact the RDT team or email simon.misak@asseco-ce.com to request access.
4. Start asking — the plugin activates automatically based on context:

   > Plan a new water network management application with pipes, valves, and hydrants
   > /create-featuretype WaterPipe
   > Add a diameter attribute to the WaterPipe feature type
   > How do I configure a trigger that validates pipe length?

GIF needed

Claude Code session with SAMO Pilot active — asking it to plan a new application and seeing the 3-layer breakdown

Troubleshooting: SSL Certificate Error

If you see SSL certificate problem: unable to get local issuer certificate when adding the marketplace, tell Git to use the Windows certificate store:

git config --global http.sslBackend schannel

This is a one-time setup per machine. Then retry the /plugin marketplace add command.

Configuring the GitLab Token in Claude Code

After installing the plugin, Claude Code stores the GitLab token securely. If you need to update it later:

1. Open Claude Code in your terminal
2. Run the plugin config command:

   /plugin config samo-pilot

3. Enter the new GitLab access token when prompted

Screenshot needed

Claude Code terminal showing /plugin config samo-pilot and the token prompt

The token is stored securely by Claude Code and never written to disk in plain text. It is passed to the MCP server via the SAMO_GITLAB_TOKEN environment variable at runtime.

Updating the Plugin

To update SAMO Pilot to the latest version:

1. Type /plugin in Claude Code and press Enter
2. Select Installed from the menu
3. Select samo-pilot from the list
4. Select Update now
5. After the update completes, select Reload plugins to apply the changes

GIF needed

Claude Code /plugin menu showing Installed → samo-pilot → Update now flow

This pulls the latest version from the GitLab marketplace and updates the MCP server dependency (@samo/mcp-server) automatically.

Plugin Structure

samo-pilot/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest (name, version, user config)
│   └── marketplace.json         # Marketplace listing
├── .mcp.json                    # MCP server definitions
├── CLAUDE.md                    # Platform knowledge injected every turn
├── agents/
│   ├── samo-planner.md          # Architecture & implementation planning subagent
│   ├── samo-reviewer.md         # Cross-layer config validation subagent
│   └── samo-docs-researcher.md  # Documentation research subagent
├── skills/
│   ├── lids-modeler/            # XML metadata modeling (auto-triggered)
│   ├── business-logic/          # Business server config patterns (auto-triggered)
│   ├── business-server-schemas/ # Business server JSON schema lookup (auto-triggered)
│   ├── dynamic-app/             # DynApp frontend config patterns (auto-triggered)
│   ├── module-catalog/          # DynApp module catalog lookup (auto-triggered)
│   ├── samo-navigation/        # DynApp navigation config (auto-triggered)
│   ├── samo-project-planner/    # Project planning & scaffolding (auto-triggered)
│   ├── create-featuretype/      # /create-featuretype slash command
│   └── edit-featuretype/        # /edit-featuretype slash command
└── .vscode/
    └── samo.d.ts                # TypeScript definitions for SAMO JS API

Skills

Skills are contextual capabilities that activate automatically based on what you're working on, or via slash commands.

Auto-triggered Skills

Skill	Trigger Keywords
lids-modeler	XML, metadata, model.xml, featuretype, attribute, codelist, symbology, thematization
business-logic	trigger, workflow, action, validation, script, JS API, automation
business-server-schemas	business server JSON schema lookup
dynamic-app	view, form, list, dashboard, UI, frontend, dynapp, navigation
module-catalog	DynApp module catalog lookup
samo-navigation	DynApp navigation, app parts, pages
samo-project-planner	new project, create project, plan, scaffold, build application

These skills activate when Claude Code detects relevant context in your conversation — no slash command needed:

GIF needed

Auto-triggered skill in action — Claude detects XML context and activates lids-modeler to generate correct FeatureType definitions

• lids-modeler — Guides Claude through correct XML structure and naming conventions when working with model.xml, FeatureType definitions, attributes, codelists, symbology, or thematization.
• business-logic — Provides patterns for business server JSON configuration when working with triggers, workflows, actions, validations, or JS API scripts.
• business-server-schemas — Looks up business server JSON schema definitions for correct config structure.
• dynamic-app — Guides correct DynApp JSON structure when working with views, forms, lists, dashboards, or frontend configuration.
• module-catalog — Looks up DynApp module schemas and their properties.
• samo-navigation — Assists with DynApp application navigation, app parts, and page configuration.
• samo-project-planner — Breaks requirements into FeatureTypes and plans all 3 layers when planning a new project.

Slash Command Skills

Command	Description
/create-featuretype <name>	Scaffolds a new FeatureType across all layers (XML definition, business entity config, DynApp entity config)
/edit-featuretype <name>	Guides modifications to an existing FeatureType with cross-layer consistency

GIF needed

Using /create-featuretype WaterPipe — Claude generates XML, business JSON, and DynApp config in one go

Agents

Agents are specialized sub-agents that SAMO Pilot delegates to for specific tasks:

Agent	Model	Purpose
samo-planner	Sonnet	Breaks requirements into FeatureTypes, plans all 3 layers, outputs implementation checklist
samo-reviewer	Sonnet	Reviews configs for cross-layer consistency — verifies IDs, references, naming conventions
samo-docs-researcher	Default	Searches SAMO documentation via MCP to answer technical questions

Screenshot needed

samo-reviewer agent validating cross-layer consistency — checking IDs and references across XML, business, and DynApp configs

MCP Server

SAMO Pilot includes the SAMO MCP Server which provides documentation search, project scaffolding, scripting API lookup, and DynApp schema tools. The server is launched automatically by Claude Code — no manual setup required.

Requirements

• Claude Code CLI
• Node.js (for MCP server execution via npx)
• Network access to the SAMO GitLab instance