expxagents 0.18.2 → 0.20.0

package/assets/core/solution-architect.agent.md

@@ -197,6 +197,75 @@ Create `_memory/memories.md` for squad-level learning.
 2. **Agent instructions** must include: "Before producing any visual output, read `squads/design-system/_memory/design-tokens.md` for colors, fonts, and spacing. Read `squads/design-system/_memory/brand-guidelines.md` for brand rules. Use assets from `_expxagents/_assets/` for logos and images."
 3. The first step of visual squads should always reference the design system tokens
 
+## Pencil Visual Templates Integration
+
+**For squads that produce visual assets** (social media posts, carousels, stories, landing pages, slides, email templates, ads, branding), use the Pencil visual design system:
+
+### When to Enable
+
+| Squad Type | visual_templates? | Reason |
+|-----------|------------------|--------|
+| Instagram Post/Carousel/Stories | YES | Visual image templates |
+| Landing Page | YES | Visual layout |
+| Slide Deck | YES | Presentation templates |
+| Email Marketing | YES | Visual email templates |
+| Ads (Meta/Google) | YES | Visual ad templates |
+| Branding/Web Design | YES | Identity visual |
+| Blog | NO | Text/HTML, no visual design |
+| Instagram Reels | NO | Video, not static image |
+| Other non-visual squads | NO | No visual assets |
+
+### squad.yaml Configuration
+
+Add `visual_templates` block to qualifying squads:
+
+```yaml
+squad:
+  # ... standard fields ...
+  visual_templates:
+    enabled: true
+    format: "4:5"     # aspect ratio (4:5 for IG, 16:9 for slides, etc.)
+    count: 3           # number of initial templates
+```
+
+### Standard Dimensions
+
+| Type | Width x Height | Format |
+|------|---------------|--------|
+| Instagram Post | 1080x1350 | 4:5 |
+| Instagram Post (square) | 1080x1080 | 1:1 |
+| Instagram Story | 1080x1920 | 9:16 |
+| Slide Deck | 1920x1080 | 16:9 |
+| Email Header | 600x200 | 3:1 |
+| Blog Cover | 1200x630 | ~2:1 |
+| Landing Page | 1440x900+ | ~16:10 |
+
+### Directory Structure
+
+When creating a visual squad, create the `templates/` directory:
+
+```
+squads/<setor>/<grupo>/<sessao>/<code>/
+├── squad.yaml
+├── templates/           ← NEW: for visual squads
+│   └── (user creates .pen file here via Pencil)
+├── agents/
+├── _memory/
+└── ...
+```
+
+### Agent Designer Instructions
+
+For the designer agent in visual squads, include this section in the agent's .md:
+
+```markdown
+## Pencil Templates
+- **Templates directory:** `templates/`
+- **Sync command:** Run `expxagents sync-templates` after editing .pen files
+- **Template rotation:** Rotate through available templates for variety
+- **Always read the template .md files** before generating HTML output
+```
+
 ## Agent Persona Rules
 
 Every agent in every squad MUST have:
@@ -232,6 +301,8 @@ Before presenting the design to the user:
 - [ ] Pipeline flows logically from research → creation → review
 - [ ] Format matches an available best-practice (if platform specified)
 - [ ] Visual squads reference design system and assets path
+- [ ] Visual squads have `visual_templates` block in squad.yaml
+- [ ] Visual squads have `templates/` directory created
 - [ ] Every agent has a human name (first + last) and an avatar URL
 
 ## After Design

package/assets/mcps/_catalog.yaml

@@ -0,0 +1,17 @@
+catalog:
+  version: "1.0.0"
+  categories:
+    - name: development
+      mcps: [github, postgresql]
+    - name: communication
+      mcps: [slack]
+    - name: project-management
+      mcps: [linear]
+    - name: monitoring
+      mcps: [sentry]
+    - name: knowledge
+      mcps: [notion]
+    - name: design
+      mcps: [figma, pencil]
+    - name: infrastructure
+      mcps: [vercel]

package/assets/mcps/figma.mcp.yaml

@@ -0,0 +1,35 @@
+id: figma
+name: Figma
+description: Design files, components, and style inspection
+category: design
+icon: figma
+
+detection:
+  method: npm
+  npm:
+    package: "figma-developer-mcp"
+
+server:
+  command: npx
+  args: ["-y", "figma-developer-mcp"]
+  env:
+    FIGMA_ACCESS_TOKEN: "${FIGMA_ACCESS_TOKEN}"
+
+auth:
+  - key: FIGMA_ACCESS_TOKEN
+    label: "Figma Access Token"
+    hint: "Create at https://www.figma.com/developers/api#access-tokens"
+    required: true
+
+tools:
+  - name: get_file
+    description: Get a Figma file and its contents
+  - name: get_components
+    description: Get components from a Figma file
+  - name: get_styles
+    description: Get styles defined in a Figma file
+
+relevant_sectors:
+  - design
+  - product
+  - development

package/assets/mcps/github.mcp.yaml

@@ -0,0 +1,44 @@
+id: github
+name: GitHub
+description: PRs, issues, code review, releases
+category: development
+icon: github
+
+detection:
+  method: hybrid
+  cli:
+    command: gh
+    version_flag: --version
+    min_version: "2.0.0"
+  npm:
+    package: "@modelcontextprotocol/server-github"
+
+server:
+  command: npx
+  args: ["-y", "@modelcontextprotocol/server-github"]
+  env:
+    GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+
+auth:
+  - key: GITHUB_PERSONAL_ACCESS_TOKEN
+    label: "GitHub Personal Access Token"
+    hint: "Create at https://github.com/settings/tokens (scopes: repo, read:org)"
+    required: true
+    validate: "gh auth status"
+
+tools:
+  - name: create_pull_request
+    description: Create a new pull request
+  - name: list_issues
+    description: List repository issues
+  - name: create_issue
+    description: Create a new issue
+  - name: search_code
+    description: Search code across repositories
+  - name: get_file_contents
+    description: Get contents of a file
+
+relevant_sectors:
+  - development
+  - quality
+  - operations

package/assets/mcps/linear.mcp.yaml

@@ -0,0 +1,37 @@
+id: linear
+name: Linear
+description: Issue tracking, project management, and team workflows
+category: project-management
+icon: linear
+
+detection:
+  method: npm
+  npm:
+    package: "@larryhudson/linear-mcp-server"
+
+server:
+  command: npx
+  args: ["-y", "@larryhudson/linear-mcp-server"]
+  env:
+    LINEAR_API_KEY: "${LINEAR_API_KEY}"
+
+auth:
+  - key: LINEAR_API_KEY
+    label: "Linear API Key"
+    hint: "Create at https://linear.app/settings/api"
+    required: true
+
+tools:
+  - name: create_issue
+    description: Create a new issue
+  - name: list_issues
+    description: List project issues
+  - name: update_issue
+    description: Update an existing issue
+  - name: list_projects
+    description: List available projects
+
+relevant_sectors:
+  - product
+  - development
+  - operations

package/assets/mcps/notion.mcp.yaml

@@ -0,0 +1,37 @@
+id: notion
+name: Notion
+description: Knowledge base, documentation, and collaborative workspace
+category: knowledge
+icon: notion
+
+detection:
+  method: npm
+  npm:
+    package: "@notionhq/notion-mcp-server"
+
+server:
+  command: npx
+  args: ["-y", "@notionhq/notion-mcp-server"]
+  env:
+    NOTION_API_KEY: "${NOTION_API_KEY}"
+
+auth:
+  - key: NOTION_API_KEY
+    label: "Notion API Key"
+    hint: "Create at https://www.notion.so/my-integrations"
+    required: true
+
+tools:
+  - name: search
+    description: Search pages and databases
+  - name: get_page
+    description: Get the content of a page
+  - name: create_page
+    description: Create a new page
+  - name: update_page
+    description: Update an existing page
+
+relevant_sectors:
+  - knowledge
+  - product
+  - operations

package/assets/mcps/pencil.mcp.yaml

@@ -0,0 +1,32 @@
+id: pencil
+name: Pencil
+description: Visual design creation and editing in VS Code
+category: design
+icon: pencil
+
+detection:
+  method: extension
+  extension:
+    prefix: "highagency.pencildev-"
+    binary_dir: out
+    binary_resolve: platform
+
+server:
+  command: null
+  args: ["--app", "visual_studio_code"]
+  env: {}
+
+auth: []
+
+tools:
+  - name: batch_design
+    description: Create and modify visual designs
+  - name: batch_get
+    description: Read design nodes
+  - name: get_screenshot
+    description: Capture design screenshots
+
+relevant_sectors:
+  - design
+  - marketing
+  - product

package/assets/mcps/postgresql.mcp.yaml

@@ -0,0 +1,39 @@
+id: postgresql
+name: PostgreSQL
+description: SQL queries, schema inspection, and database management
+category: development
+icon: postgresql
+
+detection:
+  method: hybrid
+  cli:
+    command: psql
+    version_flag: --version
+  npm:
+    package: "@modelcontextprotocol/server-postgres"
+
+server:
+  command: npx
+  args: ["-y", "@modelcontextprotocol/server-postgres"]
+  env:
+    POSTGRESQL_URL: "${POSTGRESQL_URL}"
+
+auth:
+  - key: POSTGRESQL_URL
+    label: "PostgreSQL Connection URL"
+    hint: "Format: postgresql://user:password@host:5432/database"
+    required: true
+    validate: "psql -c 'SELECT 1'"
+
+tools:
+  - name: query
+    description: Execute a SQL query
+  - name: list_tables
+    description: List all tables in the database
+  - name: describe_table
+    description: Get the schema of a specific table
+
+relevant_sectors:
+  - development
+  - data
+  - operations

package/assets/mcps/sentry.mcp.yaml

@@ -0,0 +1,41 @@
+id: sentry
+name: Sentry
+description: Error tracking, performance monitoring, and issue management
+category: monitoring
+icon: sentry
+
+detection:
+  method: npm
+  npm:
+    package: "@sentry/mcp-server"
+
+server:
+  command: npx
+  args: ["-y", "@sentry/mcp-server"]
+  env:
+    SENTRY_AUTH_TOKEN: "${SENTRY_AUTH_TOKEN}"
+    SENTRY_ORG: "${SENTRY_ORG}"
+
+auth:
+  - key: SENTRY_AUTH_TOKEN
+    label: "Sentry Auth Token"
+    hint: "Create at https://sentry.io/settings/auth-tokens/"
+    required: true
+    validate: "sentry-cli info"
+  - key: SENTRY_ORG
+    label: "Sentry Organization Slug"
+    hint: "Your Sentry organization slug"
+    required: true
+
+tools:
+  - name: list_issues
+    description: List Sentry issues
+  - name: get_issue
+    description: Get details of a specific issue
+  - name: search_events
+    description: Search error events
+
+relevant_sectors:
+  - development
+  - quality
+  - infrastructure

package/assets/mcps/slack.mcp.yaml

@@ -0,0 +1,37 @@
+id: slack
+name: Slack
+description: Team messaging, channels, and notifications
+category: communication
+icon: slack
+
+detection:
+  method: npm
+  npm:
+    package: "@modelcontextprotocol/server-slack"
+
+server:
+  command: npx
+  args: ["-y", "@modelcontextprotocol/server-slack"]
+  env:
+    SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
+
+auth:
+  - key: SLACK_BOT_TOKEN
+    label: "Slack Bot Token"
+    hint: "Create a Slack app at https://api.slack.com/apps"
+    required: true
+
+tools:
+  - name: send_message
+    description: Send a message to a channel
+  - name: list_channels
+    description: List available channels
+  - name: search_messages
+    description: Search messages across channels
+  - name: get_thread
+    description: Get messages in a thread
+
+relevant_sectors:
+  - communication
+  - operations
+  - customer-success

package/assets/mcps/vercel.mcp.yaml

@@ -0,0 +1,39 @@
+id: vercel
+name: Vercel
+description: Deployments, projects, and hosting management
+category: infrastructure
+icon: vercel
+
+detection:
+  method: hybrid
+  cli:
+    command: vercel
+    version_flag: --version
+  npm:
+    package: "mcp-handler"
+
+server:
+  command: npx
+  args: ["-y", "mcp-handler"]
+  env:
+    VERCEL_TOKEN: "${VERCEL_TOKEN}"
+
+auth:
+  - key: VERCEL_TOKEN
+    label: "Vercel Token"
+    hint: "Create at https://vercel.com/account/tokens"
+    required: true
+    validate: "vercel whoami"
+
+tools:
+  - name: list_deployments
+    description: List recent deployments
+  - name: get_deployment
+    description: Get details of a specific deployment
+  - name: list_projects
+    description: List all projects
+
+relevant_sectors:
+  - infrastructure
+  - development
+  - operations

package/dist/cli/src/commands/doctor.js

@@ -21,6 +21,32 @@ export async function doctorCommand() {
     catch {
         checks.push({ name: 'Claude Code CLI', status: 'fail', message: 'Not found — install from https://claude.ai/code' });
     }
+    // MCP integrations check
+    const { getConfiguredMcpIds } = await import('../mcp/validate.js');
+    const { loadMcpDefinition } = await import('../mcp/catalog.js');
+    const { detectMcp } = await import('../mcp/detect.js');
+    const configured = getConfiguredMcpIds(process.cwd());
+    const mcpsDir = path.resolve('mcps');
+    if (configured.length > 0) {
+        for (const id of configured) {
+            const def = loadMcpDefinition(mcpsDir, id);
+            if (def) {
+                const result = detectMcp(def);
+                checks.push({
+                    name: `MCP: ${def.name}`,
+                    status: result.status !== 'unavailable' ? 'ok' : 'warn',
+                    message: result.detail,
+                });
+            }
+        }
+    }
+    else {
+        checks.push({
+            name: 'MCP integrations',
+            status: 'warn',
+            message: 'No MCPs configured. Run: expxagents mcp setup <id>',
+        });
+    }
     // Project structure
     const requiredDirs = ['squads', '_expxagents/_memory'];
     for (const dir of requiredDirs) {

package/dist/cli/src/commands/init.js

@@ -148,6 +148,7 @@ Present using AskUserQuestion with 2-4 options:
 | \`/expxagents install <name>\` | Install skill from catalog |
 | \`/expxagents uninstall <name>\` | Remove installed skill |
 | \`/expxagents delete <name>\` | Confirm and delete squad |
+| \`/expxagents sync-templates [squad]\` | Sync Pencil .pen visual templates to .md specs |
 | \`/expxagents dashboard\` | Run CLI to start server + open dashboard |
 | \`/expxagents virtual-office\` | Run CLI to start server + open virtual office in browser |
 | \`/expxagents help\` | Show help text |
@@ -227,6 +228,9 @@ SQUADS
   /expxagents edit <name>  Modify a squad
   /expxagents delete <name> Delete a squad
 
+TEMPLATES
+  /expxagents sync-templates  Sync Pencil visual templates
+
 SKILLS
   /expxagents skills       Browse skills
   /expxagents install      Install a skill
@@ -326,6 +330,12 @@ export async function initCommand(options = {}) {
     else {
         console.log('  agents/ already exists (use --update to refresh)');
     }
+    // Copy MCP catalog
+    const mcpsSrc = path.join(assetsDir, 'mcps');
+    if (fs.existsSync(mcpsSrc)) {
+        const mcpsResult = copyDirRecursive(mcpsSrc, path.resolve('mcps'));
+        console.log(`  📡 MCP catalog: ${mcpsResult.changed}/${mcpsResult.total} files`);
+    }
     // Create/update Claude Code skill (.claude/skills/expxagents/SKILL.md)
     const skillDir = path.join(cwd, '.claude', 'skills', 'expxagents');
     const skillPath = path.join(skillDir, 'SKILL.md');
@@ -380,6 +390,7 @@ BRIDGE_TIMEOUT_MS=300000
     const gitignoreEntries = [
         'node_modules/',
         '.env',
+        '.mcp.json',
         '*.tmp',
         'squads/*/state.json',
         'squads/*/state.json.tmp',
@@ -397,6 +408,38 @@ BRIDGE_TIMEOUT_MS=300000
         fs.writeFileSync(gitignorePath, gitignoreEntries.join('\n') + '\n', 'utf-8');
         console.log('  Created .gitignore');
     }
+    // MCP Setup
+    const mcpsDir = path.resolve('mcps');
+    if (fs.existsSync(mcpsDir)) {
+        const { listAllMcpIds, loadMcpDefinition } = await import('../mcp/catalog.js');
+        const { detectMcp, detectExtension, resolvePlatformBinary } = await import('../mcp/detect.js');
+        const { writeMcpConfig } = await import('../mcp/setup.js');
+        const ids = listAllMcpIds(mcpsDir);
+        const results = ids.map(id => {
+            const def = loadMcpDefinition(mcpsDir, id);
+            return def ? { def, detection: detectMcp(def) } : null;
+        }).filter((r) => r !== null);
+        console.log('\n🔍 Detecting available MCP integrations...\n');
+        for (const { def, detection } of results) {
+            const icon = detection.status === 'detected' ? '✅' : detection.status === 'available' ? '⬜' : '⛔';
+            console.log(`  ${icon} ${def.id.padEnd(14)} — ${detection.detail}`);
+        }
+        // Auto-configure extension-based MCPs (like Pencil) that need no auth
+        for (const { def, detection } of results) {
+            if (detection.status === 'detected' && def.detection.method === 'extension' && def.auth.length === 0) {
+                if (def.detection.extension) {
+                    const ext = detectExtension(def.detection.extension.prefix);
+                    if (ext) {
+                        const binary = resolvePlatformBinary();
+                        const resolvedCmd = path.join(ext.extensionPath, def.detection.extension.binary_dir, binary);
+                        writeMcpConfig(process.cwd(), def, {}, resolvedCmd);
+                        console.log(`  → ${def.name} auto-configured`);
+                    }
+                }
+            }
+        }
+        console.log('\n  Run: expxagents mcp setup <id> to configure additional MCPs\n');
+    }
     // Install Python dependencies
     const pythonDeps = ['aiohttp', 'aiofiles', 'python-dotenv'];
     console.log(`\n  Installing Python dependencies (${pythonDeps.join(', ')})...`);

package/dist/cli/src/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function mcpCommand(): Command;