--- slug: "pomasa" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/extremeprogramming-cn/pomasa@main/README.md" repo: "https://github.com/extremeprogramming-cn/pomasa" source_file: "README.md" branch: "main" --- # POMASA **Pattern-Oriented Multi-Agent System Architecture** [ EN | [中文](https://github.com/extremeprogramming-cn/pomasa/blob/HEAD/README.zh-cn.md) ] ## TL;DR ```bash npx add-skill eXtremeProgramming-cn/pomasa ``` Then just tell your AI client (e.g. Claude Code or Codex): ``` Help me create a multi-agent research system for analyzing AI trends in healthcare. ``` That's it. The agent will guide you through the rest. ## Purpose POMASA is a pattern language and generation toolkit for building Declarative Multi-Agent Systems. Its core value proposition: **Enable AI to rapidly construct new MAS systems guided by patterns**. ## Overall Approach ### Problem When building multi-agent systems, every team uses their own approach to construct systems and their own terminology to describe architecture. The lack of a common pattern language makes it difficult to: - Disseminate knowledge - Reuse experience - Discuss problems clearly ### Solution POMASA adopts a "pattern language + generator" approach: 1. **Pattern Catalog** (`skills/pomasa/pattern-catalog/`): Reusable architectural patterns extracted from real systems, each describing a specific problem and its solution 2. **Generator** (`skills/pomasa/SKILL.md`): A prompt that guides AI to build new systems based on patterns ### Architecture Overview ![POMASA Architecture](https://github.com/extremeprogramming-cn/pomasa/raw/HEAD/pomasa-explained-v2.1.jpg) POMASA patterns are organized into four categories (shown on the left), governing three architectural layers: - **Definition Layer**: Blueprints define Agent behavior; Reference Data provides domain knowledge and methodology - **Execution Layer**: Intelligent Runtime executes Blueprints; Orchestrator coordinates Workers through staged pipelines - **Data Layer**: File System serves as the data bus, with data progressively refined from Materials → Drafts → Final outputs ### Core Principles - **Patterns are knowledge carriers**: Transform tacit architectural experience into explicit, shareable patterns - **Patterns have necessity levels**: Required, Recommended, Optional—systems can be flexibly composed - **AI is the executor**: AI reads pattern documents, understands design principles, and generates pattern-conforming systems - **Continuous evolution**: New patterns are added as practice accumulates ## Directory Structure ``` pomasa/ ├── README.md # This file ├── skills/ │ └── pomasa/ # POMASA skill (installable) │ ├── SKILL.md # Generator instructions │ ├── user_input_template.md │ └── pattern-catalog/ # Pattern catalog │ ├── README.md │ ├── COR-01-... │ ├── STR-01-... │ ├── BHV-01-... │ └── QUA-01-... └── references/ # Background reading materials ├── declarative-multi-agent-architecture-part1-en.md └── declarative-multi-agent-architecture-part2-en.md ``` ## How to Use ### Method 1: Install as Skill (Recommended) Install POMASA as an agent skill for Claude Code, Cursor, Cline, and other compatible agents: ```bash npx add-skill eXtremeProgramming-cn/pomasa ``` After installation, simply tell the agent what you want: ``` Help me create a multi-agent research system for analyzing AI trends in healthcare. ``` The agent will automatically activate the POMASA skill and guide you through the process. ### Method 2: Direct Use (Without Skill Installation) Tell your AI agent: ``` Please read skills/pomasa/SKILL.md, then help me create a multi-agent system. ``` The agent will: 1. Ask for your project information (or you can prepare `user_input_template.md` in advance) 2. Read the relevant patterns in pattern-catalog 3. Select the appropriate pattern combination based on your needs 4. Generate the complete system files ### Scenario: Understanding or Improving an Existing System ``` Please read skills/pomasa/pattern-catalog/README.md, then analyze which patterns [a system directory] uses and what improvements could be made. ``` ### Scenario: Learning MAS Architecture Read the pattern documents under `skills/pomasa/pattern-catalog/` directly to learn about declarative MAS design principles and best practices. ## Pattern Overview See [skills/pomasa/pattern-catalog/README.md](https://github.com/extremeprogramming-cn/pomasa/blob/HEAD/skills/pomasa/pattern-catalog/README.md) ## Tool Compatibility POMASA patterns are primarily written and tested with Claude Code. The patterns reference these common tool capabilities: | Tool Category | Purpose | Claude Code Example | |--------------|---------|---------------------| | **File Read** | Read file contents | `Read` | | **File Write** | Create or overwrite files | `Write` | | **File Edit** | Modify existing files | `Edit` | | **File Search** | Find files by pattern | `Glob` | | **Content Search** | Search text in files | `Grep` | | **Web Search** | Find web pages | `WebSearch` | | **Web Fetch** | Retrieve web page content | `WebFetch` | | **Command Execution** | Run shell commands | `Bash` | | **Subagent Launch** | Start a child agent | `Task` | **For other runtimes** (Cursor, Cline, Windsurf, etc.): If your runtime uses different tool names or doesn't have a particular tool, find an equivalent in your environment. The patterns describe *what* capability is needed, not *which specific tool* to use. **MCP Tools**: Some patterns mention MCP (Model Context Protocol) tools with naming format `mcp__server__tool`. These are specific to runtimes that support MCP. If your runtime doesn't support MCP, use the built-in equivalents (e.g., use `WebSearch` instead of an MCP search tool). ## Publication Xiong Jie. **A Pattern Language for Knowledge Engineering with Large Language Models**. In *Proceedings of the 32nd Conference on Pattern Languages of Programs, People, and Practices (PLoP 2025)*, Skamania Lodge, Columbia River Gorge, WA, USA. ACM, 2026. [DOI: 10.64346/PLoP2025p02](https://doi.org/10.64346/PLoP2025p02) | [Full text](https://plopcon.org/proceedings/plop/2025/2.html)