ALPS AI Guide

ALPS Design with AI

Why AI Makes a Great ALPS Guide

ALPS design requires balancing multiple concerns: clear state definitions, meaningful transitions, consistent naming, and alignment with standard vocabularies. AI assistants excel at this kind of multi-dimensional thinking.

Deep Context Understanding

AI can analyze your domain requirements and identify the essential states and transitions. When you describe “an e-commerce system with shopping cart,” the AI understands the implicit flow: browsing → cart → checkout → confirmation, and suggests appropriate state names and transition labels.

Semantic Naming

Naming requires more than following conventions—it demands understanding intent. While linters can enforce patterns like go* or do*, AI understands what you mean and why it matters.

When you describe “let users save items for later,” AI recognizes this as a wishlist pattern and suggests doAddToWishlist aligned with Schema.org’s WantAction—not a generic doSave. It distinguishes author (creative attribution) from creator (technical origin), ensuring your vocabulary connects meaningfully with external systems.

Standards Compliance

AI automatically aligns your descriptors with established vocabularies:

  • Schema.org definitions for common concepts
  • IANA Link Relations for standard relationships
  • Consistent naming conventions across your entire profile

Integration Methods

If you use Claude Code, Skill is the easiest option. For Claude Desktop or other MCP-compatible clients, see MCP Server. For other LLMs, see llms.txt.

Note: Skills are loaded only when needed, using context efficiently. Console-based AI agents like Claude Code can run asd commands via Bash, so Skill alone is sufficient. GUI clients like Claude Desktop and Cursor require MCP tools since they cannot run Bash.

Skill (Claude Code)

The recommended method for Claude Code users. Skills provide persistent context that guides AI behavior throughout your session.

alps-skills

alps-skills is a collection of ALPS-related skills.

Skill Description
alps Generate, validate, and improve ALPS profiles
alps-to-openapi Generate OpenAPI specs from ALPS
alps-to-graphql Generate GraphQL schema from ALPS
alps-to-jsonschema Generate JSON Schema from ALPS
alps-to-sql Generate SQL DDL from ALPS (PostgreSQL, MySQL, SQLite)

Setup

/plugin marketplace add alps-asd/alps-skills
/plugin install alps-skills

Or use /plugin to browse and install from the Discover tab.

Verify

Ask: “What skills are available?”

Response should include “alps” skill.

Usage

  • “Create an ALPS profile for a blog system”
  • “Validate alps.xml and fix any issues”

Input can be text, Figma designs, OpenAPI specs, whiteboard photos, website URLs, and moredatabase schemas, existing code, GraphQL schemas, Postman collections, Swagger docs, sequence diagrams, user stories, ERDs, JSON responses, route definitions, meeting notes, Slack threads, napkin sketches….

Tip: Press Ctrl+V in the console to paste images from clipboard.

MCP Server

For AI clients supporting Model Context Protocol. MCP provides real-time tool access for validation and diagram generation.

1. Check Node.js Version

node --version  # v18.0.0 or higher required

If below v18, upgrade Node.js. If using nvm, run nvm use 18.

2. Create Configuration File

Add the following configuration to your client:

Claude Code: Create .mcp.json in your project

Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Cursor: Settings → MCP → Add Server

{
  "mcpServers": {
    "alps": {
      "command": "npx",
      "args": ["@alps-asd/mcp"]
    }
  }
}

3. Verify Connection

Confirm “alps” appears in the MCP server list. For Claude Code, run /mcp.

4. Try It Out

Try “Create an ALPS profile for a todo app”. An ASD document with diagrams will be generated.

5. Tips

MCP connections may disconnect during sessions. Run /mcp to reconnect.

For frequent use, global installation provides faster startup:

npm install -g @alps-asd/mcp

Available Tools

Tool Description
validate_alps Validate ALPS profile and get detailed feedback
alps2svg Generate SVG state diagram
alps2mermaid Generate Mermaid diagram
alps_guide Get ALPS best practices

llms.txt (Any LLM)

For LLMs without Skill or MCP support. The llms.txt standard provides AI-friendly documentation that any assistant can consume.

Resources

Resource Description
llms.txt ALPS specification index
llms-full.txt Complete ALPS specification
ALPS Creation Guide Design principles and examples

System Prompt

Add to your system prompt or AGENTS.md:

For ALPS profile creation, refer to: https://www.app-state-diagram.com/alps-skills/skills/alps/SKILL.md

Manual Copy

Paste at the beginning of your conversation or upload as a file attachment.

OpenAI GPTs

ALPS Assistant is a custom GPT trained specifically for ALPS questions.

Note: Requires OpenAI Plus account.

Google NotebookLM

ALPS Guide Notebook is an interactive notebook for exploring ALPS concepts with AI assistance.

References