goiabaseeds 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# goiabaseeds
+
+Design AI agents that stay in sync — right inside your IDE. lucide:code-2
+
+GoiabaSeeds is a refined multi-agent orchestration framework. Describe your mission; GoiabaSeeds aligns a team of specialized agents to master your workflow instantly.
+
+## What is a Department?
+
+A Department is a collective of specialized AI agents built to solve a single mission.
+- **Specialized Roles**: Every agent owns a specific task in the chain. ph:briefcase-bold
+- **Automated Pipeline**: Work flows through a structured sequence. ph:flow-arrow-bold
+- **Human Oversight**: The process pauses only for your final decision or checkpoint.
+
+Example:
+
+- **Researcher** gathers information and industry trends
+- **Strategist** generates ideas and defines the approach
+- **Writer** produces the final content
+- **Reviewer** ensures quality before delivery
+
+## Installation
+
+**Prerequisite:** Node.js 20+
+
+```bash
+npx goiabaseeds init
+```
+
+To update an existing installation:
+
+```bash
+npx goiabaseeds update
+```
+
+## Supported IDEs
+
+| IDE | Status |
+|-----|--------|
+| Antigravity | Available |
+| Claude Code | Available |
+| Codex (OpenAI) | Available |
+| Open Code | Available |
+| Cursor | Available |
+| VS Code + Copilot | Available |
+
+## Dashboard & Approval Workflow
+
+The Dashboard is a real-time virtual office where you watch agents work and approve/revise their outputs.
+
+### Starting the Dashboard
+
+From your project root:
+
+```bash
+cd dashboard
+npm run dev
+```
+
+The dev server will start on `http://localhost:5173` (or next available port).
+
+### Dashboard Features
+
+- **Real-time Agent Status**: See which agent is active, idle, or waiting for approval
+- **Approval Requests**: When an agent needs your approval, an interactive memo popup appears
+- **Approve or Revise**: Click "✓ Approve" to continue, or "→ Revise" with instructions
+- **Visual Feedback**: Blue monitor = active agent, gray = idle, gold = waiting for approval
+
+### Approval Workflow Example
+
+When a `content-review` department runs:
+
+1. **Researcher agent** gathers information and needs approval
+   - Click the researcher's desk (gold status dot)
+   - Review the memo popup with research findings
+   - Approve or request revisions
+
+2. **Writer agent** creates content based on research
+   - Approve writing style and structure
+   - Or revise with specific feedback
+
+3. **Review checkpoint** shows final content
+   - Approve for publishing
+   - Or request another round of revisions
+
+### Dashboard Troubleshooting
+
+If agents aren't showing or approvals aren't appearing:
+
+1. **Check the browser console** (F12 → Console)
+   - Should NOT see "WebSocket is closed" errors
+   - Should see clean connection
+
+2. **Verify the departments directory exists**
+   - `departments/` folder at project root
+   - Each department has `department.yaml` with agent definitions
+
+3. **Confirm the dashboard is running**
+   ```bash
+   cd dashboard && npm run dev
+   ```
+   - Should log: `[department-watcher] departments dir: ...`
+
+## Architecture Overview
+
+GoiabaSeeds consists of:
+
+- **Core Framework** (`src/`) — Agent orchestration, pipeline execution, approval handling
+- **CLI** (`bin/goiabaseeds.js`) — Command-line interface
+- **Dashboard** (`dashboard/`) — Real-time visual interface for monitoring and approvals
+- **Templates** (`templates/`) — Boilerplate for new projects
+- **Agents** (`agents/`) — Pre-built agent definitions
+
+For developers working on the framework, see [CLAUDE.md](./CLAUDE.md) for detailed architecture and testing guidelines.
+
+## Creating your Department
+
+Describe what you need:
+
+```
+/goiabaseeds create "A department that writes LinkedIn posts about AI trends"
+```
+
+The **Architect** asks a few questions, designs the department, and sets everything up automatically. You approve the design before any execution begins.
+
+## Running a Department
+
+```
+/goiabaseeds run <department-name>
+```
+
+The department runs automatically, pausing only at checkpoints where your decision is needed.
+
+## Examples
+
+```
+/goiabaseeds create "Department that generates Instagram carousels from trending news, creates the images, and publishes automatically"
+/goiabaseeds create "Department that produces all infoproduct launch materials: sales pages, WhatsApp messages, emails, and CPL scripts"
+/goiabaseeds create "Department that writes complete tutorials with screenshots for employee training"
+/goiabaseeds create "Department that takes YouTube videos and automatically generates viral clips"
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/goiabaseeds` | Open the main menu |
+| `/goiabaseeds help` | Show all commands |
+| `/goiabaseeds create` | Create a new department |
+| `/goiabaseeds run <name>` | Run a department |
+| `/goiabaseeds list` | See all your departments |
+| `/goiabaseeds edit <name>` | Modify a department |
+| `/goiabaseeds skills` | Browse installed skills |
+| `/goiabaseeds install <name>` | Install a skill from catalog |
+| `/goiabaseeds uninstall <name>` | Remove an installed skill |
+
+## Recent Fixes
+
+### Dashboard Agent Display (v0.x.x)
+
+**Issue**: Agents defined in `department.yaml` weren't showing in the Dashboard virtual office.
+
+**Cause**: YAML parsing bug in the department watcher plugin — it was looking for agents in the wrong location.
+
+**Fix**: Updated the plugin to correctly parse department metadata and extract agent names from both object and string formats.
+
+**How to verify**:
+- Start the dashboard: `cd dashboard && npm run dev`
+- Visit `http://localhost:PORT/api/snapshot` in your browser
+- You should see all agents listed with their names
+
+## License
+
+MIT — use it however you want.

package/bin/goiabaseeds.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { init } from '../src/init.js';
+import { update } from '../src/update.js';
+import { skillsCli } from '../src/skills-cli.js';
+import { agentsCli } from '../src/agents-cli.js';
+import { listRuns, printRuns } from '../src/runs.js';
+import { exportDepartment } from '../src/export.js';
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  strict: false,
+  options: {
+    quick: { type: 'boolean', default: false },
+  },
+});
+
+const command = positionals[0];
+
+if (command === 'init') {
+  await init(process.cwd(), values.quick ? { _quick: true } : {});
+} else if (command === 'install') {
+  // npx goiabaseeds install <name>
+  const result = await skillsCli('install', positionals.slice(1), process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else if (command === 'uninstall') {
+  // npx goiabaseeds uninstall <name>
+  const result = await skillsCli('remove', positionals.slice(1), process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else if (command === 'update') {
+  const target = positionals[1];
+  if (target) {
+    // npx goiabaseeds update <name> → update specific skill
+    const result = await skillsCli('update-one', [target], process.cwd());
+    if (!result.success) process.exitCode = 1;
+  } else {
+    // npx goiabaseeds update → update core
+    const result = await update(process.cwd());
+    if (!result.success) process.exitCode = 1;
+  }
+} else if (command === 'skills') {
+  // Backward compat: npx goiabaseeds skills list|install|remove|update
+  const subcommand = positionals[1];
+  const args = positionals.slice(2);
+  const result = await skillsCli(subcommand, args, process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else if (command === 'agents') {
+  const subcommand = positionals[1];
+  const args = positionals.slice(2);
+  const result = await agentsCli(subcommand, args, process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else if (command === 'runs') {
+  const departmentName = positionals[1] || null;
+  const runs = await listRuns(departmentName, process.cwd());
+  printRuns(runs);
+} else if (command === 'bundle' || command === 'export') {
+  // npx goiabaseeds bundle <department> [--output <path>] [--zip]
+  const args = positionals.slice(1);
+  const result = await exportDepartment(args, process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else if (command === 'run') {
+  // npx goiabaseeds run <department>  — standalone pipeline execution
+  const { runDepartment } = await import('../src/run.js');
+  const result = await runDepartment(positionals[1], process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else if (command === 'models') {
+  // npx goiabaseeds models [set <provider>|test]
+  const { modelsCli } = await import('../src/models-cli.js');
+  const result = await modelsCli(positionals.slice(1), process.cwd());
+  if (!result.success) process.exitCode = 1;
+} else {
+  console.log(`
+  goiabaseeds — Multi-agent orchestration framework
+
+  Usage:
+    npx goiabaseeds init                    Initialize GoiabaSeeds
+    npx goiabaseeds run <department>        Run a department (standalone mode)
+    npx goiabaseeds models                  List configured models & providers
+    npx goiabaseeds models set <provider>   Change default provider
+    npx goiabaseeds models test             Test model API connectivity
+    npx goiabaseeds update                  Update GoiabaSeeds core
+    npx goiabaseeds install <name>          Install a skill
+    npx goiabaseeds uninstall <name>        Remove a skill
+    npx goiabaseeds update <name>           Update a specific skill
+    npx goiabaseeds skills                  List installed skills
+    npx goiabaseeds agents                  List installed agents
+    npx goiabaseeds agents install <name>   Install a predefined agent
+    npx goiabaseeds agents remove <name>    Remove an agent
+    npx goiabaseeds agents update           Update all agents
+    npx goiabaseeds runs [department-name]  View execution history
+    npx goiabaseeds bundle <department>     Bundle department for sharing
+    npx goiabaseeds export <department>     Export department (alias for bundle)
+
+  Learn more: https://github.com/netoribeiro/goiabaseeds
+  `);
+  if (command) process.exitCode = 1;
+}

package/eslint.config.js

@@ -0,0 +1,14 @@
+import js from "@eslint/js";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+  {
+    files: ["src/**/*.js", "bin/**/*.js", "tests/**/*.js"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: { ...globals.node },
+    },
+  },
+];

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "goiabaseeds",
+  "version": "1.0.0",
+  "description": "Multi-agent orchestration framework — create AI departments that work together",
+  "type": "module",
+  "bin": {
+    "goiabaseeds": "bin/goiabaseeds.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "lint": "eslint src/ bin/ tests/",
+    "version": "node -e \"require('fs').writeFileSync('templates/_goiabaseeds/.goiabaseeds-version', require('./package.json').version + '\\n')\" && git add templates/_goiabaseeds/.goiabaseeds-version"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "multi-agent",
+    "orchestration",
+    "departments"
+  ],
+  "author": "Neto Ribeiro (https://github.com/netoribeiro)",
+  "homepage": "https://github.com/netoribeiro/goiabaseeds#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netoribeiro/goiabaseeds.git"
+  },
+  "bugs": {
+    "url": "https://github.com/netoribeiro/goiabaseeds/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "agents/",
+    "skills/",
+    "templates/"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.0.0",
+    "@ai-sdk/google": "^1.0.0",
+    "@ai-sdk/openai": "^1.0.0",
+    "@inquirer/checkbox": "^5.1.0",
+    "@inquirer/input": "^5.0.0",
+    "@inquirer/select": "^5.1.0",
+    "ai": "^4.0.0",
+    "yaml": "^2.7.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0"
+  },
+  "main": "eslint.config.js",
+  "directories": {
+    "test": "tests"
+  }
+}

package/skills/README.md

@@ -0,0 +1,60 @@
+# GoiabaSeeds Skill Catalog
+
+Browse available skills for your departments. Install any skill with:
+
+```bash
+npx goiabaseeds install <skill-name>
+```
+
+## Available Skills
+
+| Skill | Type | Description | Env Vars | Install |
+|-------|------|-------------|----------|---------|
+| [apify](./apify/) | mcp | Web scraping and automation platform. Extract data from any website using pre-built Actors. | `APIFY_TOKEN` | `npx goiabaseeds install apify` |
+| [canva](./canva/) | mcp | Create, search, autofill, and export designs from Canva. | _(none -- OAuth)_ | `npx goiabaseeds install canva` |
+| [instagram-publisher](./instagram-publisher/) | script | Publish Instagram carousel posts from local JPEG images via the Graph API. | `INSTAGRAM_ACCESS_TOKEN`, `INSTAGRAM_USER_ID` | `npx goiabaseeds install instagram-publisher` |
+| [blotato](./blotato/) | mcp | Publish and schedule posts across Instagram, LinkedIn, Twitter/X, TikTok, YouTube, and more. | `BLOTATO_API_KEY` | `npx goiabaseeds install blotato` |
+| [image-fetcher](./image-fetcher/) | hybrid | Acquire visual assets via web search, live screenshots (Playwright), and user-provided files. | _(none)_ | `npx goiabaseeds install image-fetcher` |
+| [image-creator](./image-creator/) | mcp | Render HTML/CSS into production-ready PNG images via Playwright. | _(none)_ | `npx goiabaseeds install image-creator` |
+| [image-generator](./image-generator/) | script | Generate AI images via Openrouter API. Test mode (cheap) and production mode (high-quality). Supports reference images for brand consistency. | `OPENROUTER_API_KEY` | `npx goiabaseeds install image-generator` |
+
+## Skill Types
+
+- **mcp** -- Connects to an external MCP server (stdio or HTTP transport)
+- **script** -- Runs a local script (Node.js, Python, etc.)
+- **hybrid** -- Combines MCP server access with local script capabilities
+
+## Directory Structure
+
+Each skill lives in its own folder with a `SKILL.md` file:
+
+```
+skills/
+  apify/
+    SKILL.md
+  canva/
+    SKILL.md
+  instagram-publisher/
+    SKILL.md
+    scripts/
+      publish.js
+  blotato/
+    SKILL.md
+  image-fetcher/
+    SKILL.md
+  image-creator/
+    SKILL.md
+  image-generator/
+    SKILL.md
+    scripts/
+      generate.py
+```
+
+The `SKILL.md` file contains YAML frontmatter (name, type, version, MCP/script config, env vars, categories) and a Markdown body with usage instructions and available operations.
+
+## Adding a New Skill
+
+1. Create a new folder under `skills/` with the skill ID as the name
+2. Add a `SKILL.md` file with valid YAML frontmatter and Markdown body
+3. If the skill includes scripts, place them in a `scripts/` subfolder
+4. Update this README to include the new skill in the catalog table

package/skills/apify/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: apify
+description: >
+  Web scraping and automation platform. Extract data from any website,
+  run pre-built scrapers (Actors), and automate web workflows using
+  thousands of ready-made tools from the Apify Store.
+description_pt-BR: >
+  Plataforma de web scraping e automação. Extraia dados de qualquer site,
+  execute scrapers prontos (Actors) e automatize fluxos de trabalho web
+  com milhares de ferramentas da Apify Store.
+description_es: >
+  Plataforma de web scraping y automatización. Extrae datos de cualquier sitio web,
+  ejecuta scrapers prediseñados (Actors) y automatiza flujos de trabajo web
+  con miles de herramientas de la Apify Store.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: apify
+  command: npx
+  args: ["-y", "@apify/actors-mcp-server@latest"]
+env:
+  - APIFY_TOKEN
+categories: [scraping, data, automation]
+---
+
+# Apify Web Scraper
+
+## When to use
+
+Use Apify when you need to extract data from websites, scrape social media profiles, run search engine queries, or automate web data collection workflows. Apify provides thousands of pre-built scrapers (called Actors) that handle common scraping tasks out of the box.
+
+## Instructions
+
+You have access to Apify tools for web scraping and data extraction.
+
+### Key capabilities
+
+- Use Apify Actors (pre-built scrapers) to extract data from websites
+- Popular Actors: web-scraper, instagram-scraper, google-search-scraper, youtube-scraper, twitter-scraper, tiktok-scraper
+- Each Actor has its own input schema -- check documentation before running
+
+### Best practices
+
+- Start with the simplest Actor that meets the need
+- Use `maxItems` to limit results and avoid excessive costs
+- Check Actor pricing before running (some have per-result costs)
+- Parse results and extract only the fields you need
+
+## Available operations
+
+- **Run Actor** -- Execute any Apify Actor with custom input parameters
+- **Web Scraping** -- Extract structured data from any website
+- **Social Media Scraping** -- Scrape profiles, posts, and engagement data from Instagram, YouTube, Twitter/X, TikTok
+- **Search Scraping** -- Run Google, Bing, or other search engine queries and collect results
+- **Data Export** -- Retrieve scraped datasets in JSON format

package/skills/blotato/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: blotato
+description: >
+  Social media publishing and scheduling platform.
+  Publish and schedule posts across Instagram, LinkedIn, Twitter/X,
+  TikTok, YouTube, and more. Upload media and monitor post status.
+description_pt-BR: >
+  Plataforma de publicação e agendamento em redes sociais.
+  Publique e agende posts no Instagram, LinkedIn, Twitter/X,
+  TikTok, YouTube e mais. Faça upload de mídia e monitore o status dos posts.
+description_es: >
+  Plataforma de publicación y programación en redes sociales.
+  Publica y programa posts en Instagram, LinkedIn, Twitter/X,
+  TikTok, YouTube y más. Sube contenido multimedia y monitorea el estado de los posts.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: blotato
+  transport: http
+  url: "https://mcp.blotato.com/mcp"
+  headers:
+    blotato-api-key: BLOTATO_API_KEY
+env:
+  - BLOTATO_API_KEY
+categories: [social-media, automation, publishing, scheduling]
+---
+
+# Blotato Publisher
+
+## When to use
+
+Use Blotato when you need to publish or schedule social media posts across multiple platforms from a single interface. Blotato supports Instagram, LinkedIn, Twitter/X, TikTok, YouTube, and more. It handles media uploads, post scheduling, and status monitoring.
+
+## Instructions
+
+You have access to Blotato for social media publishing.
+
+### Key workflow
+
+1. Use `blotato_list_accounts` to get account IDs and platforms
+2. If post includes images or videos, upload them with `blotato_upload_media` first and use the returned media IDs in `blotato_create_post`
+3. Use `blotato_create_post` to publish or schedule
+4. Use `blotato_get_post_status` to confirm success
+
+### Best practices
+
+- Always call `blotato_list_accounts` first to get valid account IDs
+- For scheduled posts, use ISO 8601 format for datetime
+- After posting, poll `blotato_get_post_status` until status is "published" or "scheduled"
+- If status is "failed", report the error details to the user
+
+### Requirements
+
+- Blotato account required (blotato.com)
+- API key must be configured (Blotato Settings > API section)
+
+## Available operations
+
+- **List Accounts** -- Retrieve connected social media accounts and their platform types
+- **Upload Media** -- Upload images and videos for use in posts
+- **Create Post** -- Publish or schedule a post to one or more platforms
+- **Get Post Status** -- Monitor publishing status (published, scheduled, failed)
+- **Multi-platform Publishing** -- Post the same content across Instagram, LinkedIn, Twitter/X, TikTok, YouTube simultaneously

package/skills/canva/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: canva
+description: >
+  Create, search, autofill, and export designs from Canva.
+  Enables agents to generate visual content, fill templates
+  with brand assets, and export in various formats.
+description_pt-BR: >
+  Crie, busque, preencha e exporte designs do Canva.
+  Permite que agentes gerem conteúdo visual, preencham templates
+  com assets da marca e exportem em diversos formatos.
+description_es: >
+  Crea, busca, completa y exporta diseños de Canva.
+  Permite que los agentes generen contenido visual, completen plantillas
+  con recursos de marca y exporten en diversos formatos.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: canva
+  transport: http
+  url: "https://mcp.canva.com/mcp"
+categories: [design, ui, assets, automation]
+---
+
+# Canva Connect
+
+## When to use
+
+Use Canva when you need to create, search, or export visual designs. This skill connects to the user's Canva account via OAuth and enables agents to generate presentations, social media posts, logos, and other visual content. It also supports autofilling templates with brand assets and exporting designs in various formats.
+
+## Instructions
+
+You have access to Canva through the Canva Connect MCP server.
+
+### Key capabilities
+
+- Create new designs (presentations, social posts, logos, etc.)
+- Autofill templates with content (text, images, brand elements)
+- Search existing designs in the user's Canva account
+- Export designs as PDF or image files
+
+### Best practices
+
+- Use templates when possible -- faster and more on-brand
+- When autofilling, match content to template placeholder names
+- Export in the format most useful for the pipeline (PNG for social, PDF for documents)
+- Respect the user's Canva plan limitations (some features require paid plans)
+
+### Requirements
+
+- User needs a Canva account (free or paid)
+- OAuth authorization is required on first use (browser popup)
+- Autofill templates require a Canva paid plan
+
+## Available operations
+
+- **Create Design** -- Generate new designs from scratch or templates
+- **Search Designs** -- Find existing designs in the user's Canva account
+- **Autofill Template** -- Fill template placeholders with text, images, and brand elements
+- **Export Design** -- Export designs as PDF, PNG, JPG, or other formats
+- **Browse Templates** -- Search Canva's template library for the right starting point