plugin.yaml

id: pm-essentials
name: PM Essentials
version: 0.4.0
description: >
  Reference plugin for EvoNexus — exercises every v1a + Wave 2.1 + Wave 2.2r +
  Wave 2.3 capability so plugin authors can copy it as a starting template.
  Installs a PM-focused agent, three skills, two slash commands, a rule block,
  SQL schema with seed data, two dashboard widgets, four full-screen pages
  (company / projects / kanban / reports), three read-only queries, two
  writable-data resources, one heartbeat, one scheduled routine, one Claude Code
  hook handler, one MCP server declaration (Wave 2.3), and one integration with
  env var configuration (Wave 2.2r).
author: Evolution Foundation
license: MIT
homepage: https://github.com/EvolutionAPI/evonexus-plugin-pm-essentials

min_evonexus_version: 0.30.0
tier: essential

# Wave 2.1 adds ui_pages and writable_data capabilities.
capabilities:
  - agents
  - skills
  - rules
  - heartbeats
  - sql_migrations
  - widgets
  - claude_hooks
  - readonly_data
  # v1a extension — seed host-managed rows (projects/goals/tickets/triggers)
  # tagged with source_plugin so uninstall cleans them automatically.
  - goals
  - tasks
  - triggers
  # Wave 2.1: full-screen plugin pages + writable CRUD endpoints
  - ui_pages
  - writable_data

# Declare env vars the plugin reads at runtime. Missing vars are a WARNING
# (not a blocker) on install preview — see AC26 in the EvoNexus PRD.
env_vars_needed: []

# Slugs this plugin refuses to coexist with. Use when two plugins would
# clobber the same SQL table, widget mount_point, or hook handler path.
conflicts: {}

# Minimum versions of other plugins this one depends on. Empty for a
# standalone plugin.
dependencies: {}

# Dashboard widgets. `mount_point: overview` places the widget on the home
# dashboard. `custom_element_name` must match the `customElements.define()`
# call inside the JS bundle or the card renders empty.
ui_entry_points:
  widgets:
    - id: pm-open-projects
      label: Open Projects
      mount_point: overview
      custom_element_name: pm-open-projects
      filename: pm-open-projects.js
      icon: null

    - id: pm-sprint-burndown
      label: Sprint Burndown
      mount_point: overview
      custom_element_name: pm-sprint-burndown
      filename: pm-sprint-burndown.js
      icon: null

  # Wave 2.1: full-screen pages — served by /plugins/pm-essentials/ui/pages/*.js
  # Route: /plugins-ui/pm-essentials/<path>
  pages:
    - id: company
      label: Company Overview
      path: company
      bundle: ui/pages/company.js
      custom_element_name: pm-company-page
      sidebar_group: pm-essentials
      icon: Building2
      order: 10

    - id: projects
      label: Projects
      path: projects
      bundle: ui/pages/projects.js
      custom_element_name: pm-projects-page
      sidebar_group: pm-essentials
      icon: FolderKanban
      order: 20

    - id: kanban
      label: Sprint Kanban
      path: kanban
      bundle: ui/pages/kanban.js
      custom_element_name: pm-kanban-page
      sidebar_group: pm-essentials
      icon: Columns
      order: 30

    - id: reports
      label: Reports
      path: reports
      bundle: ui/pages/reports.js
      custom_element_name: pm-reports-page
      sidebar_group: pm-essentials
      icon: BarChart3
      order: 40

  # Sidebar group injected after native groups (order 10 = before system/admin)
  sidebar_groups:
    - id: pm-essentials
      label: PM Essentials
      order: 10
      collapsible: true

# Wave 2.1: writable data resources exposed via POST/PUT/DELETE.
# Column allowlist is enforced at runtime — unlisted columns are rejected.
# json_schema provides optional payload validation via jsonschema library.
writable_data:
  - id: projects
    description: Create, update, and delete pm_essentials_projects rows.
    table: pm_essentials_projects
    allowed_columns:
      - name
      - status
      - due_date
    json_schema:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        status:
          type: string
          enum: [active, on_hold, completed]
        due_date:
          type: [string, "null"]
      additionalProperties: false

  - id: tasks
    description: Update task status for kanban drag-and-drop (PUT only).
    table: pm_essentials_tasks
    allowed_columns:
      - title
      - status
      - assignee
      - priority
      - project_id
      - sprint_id
    json_schema:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 500
        status:
          type: string
          enum: [todo, in_progress, review, done, cancelled]
        assignee:
          type: [string, "null"]
        priority:
          type: string
          enum: [urgent, high, medium, low]
        project_id:
          type: [integer, "null"]
        sprint_id:
          type: [integer, "null"]
      additionalProperties: false

# Claude Code hooks. Each entry maps an event (PreToolUse, PostToolUse,
# Stop, SubagentStop) to a handler script under claude-hook-handlers/.
# The EvoNexus dispatcher calls the handler and always exits 0 — a failing
# hook never blocks Claude Code.
claude_hooks:
  - event: Stop
    handler_path: claude-hook-handlers/on_stop.py

# Declarative read-only queries. The frontend calls
# GET /api/plugins/pm-essentials/readonly-data/<id> and the backend executes
# the SQL under a 1000-row cap. Queries must only touch tables prefixed
# with `{plugin_slug}_` — enforced on install.
readonly_data:
  - id: open_projects
    description: Active projects with task counts and due dates.
    sql: >
      SELECT
        pm_essentials_projects.id,
        pm_essentials_projects.name,
        pm_essentials_projects.status,
        pm_essentials_projects.due_date,
        COUNT(pm_essentials_tasks.id) AS task_count
      FROM pm_essentials_projects
      LEFT JOIN pm_essentials_tasks
        ON pm_essentials_tasks.project_id = pm_essentials_projects.id
      WHERE pm_essentials_projects.status = 'active'
      GROUP BY pm_essentials_projects.id
      ORDER BY pm_essentials_projects.due_date ASC

  - id: sprint_tasks
    description: Tasks in the current active sprint.
    sql: >
      SELECT
        pm_essentials_tasks.id,
        pm_essentials_tasks.title,
        pm_essentials_tasks.status,
        pm_essentials_tasks.assignee,
        pm_essentials_tasks.priority,
        pm_essentials_projects.name AS project_name
      FROM pm_essentials_tasks
      JOIN pm_essentials_projects
        ON pm_essentials_projects.id = pm_essentials_tasks.project_id
      WHERE pm_essentials_tasks.sprint_id IS NOT NULL
        AND pm_essentials_tasks.sprint_id = (
          SELECT id FROM pm_essentials_sprints
          WHERE status = 'active'
          ORDER BY started_at DESC
          LIMIT 1
        )
      ORDER BY pm_essentials_tasks.priority DESC, pm_essentials_tasks.created_at ASC

  - id: sprint_burndown
    description: Task counts by status for the active sprint, for the burndown widget.
    sql: >
      SELECT status, COUNT(*) AS count
      FROM pm_essentials_tasks
      WHERE sprint_id = (
        SELECT id FROM pm_essentials_sprints
        WHERE status = 'active'
        ORDER BY started_at DESC
        LIMIT 1
      )
      GROUP BY status
      ORDER BY
        CASE status
          WHEN 'todo' THEN 1
          WHEN 'in_progress' THEN 2
          WHEN 'review' THEN 3
          WHEN 'done' THEN 4
          ELSE 5
        END

source_url: https://github.com/EvolutionAPI/evonexus-plugin-pm-essentials

# Wave 2.0: Plugin & Agent identity (icon + avatar)
# Assets served by /plugins/pm-essentials/ui/<path> endpoint.
metadata:
  icon: "ui/assets/icon.png"
  icon_sha256: "dee97b2fb0a46d5c0304fdbde7e2b1e58f283bbed381601c56b6ffaedda974c3"

agents:
  - file: "agents/pm-nova.md"
    avatar: "ui/assets/avatars/pm-nova.png"
    avatar_sha256: "fd20ca765309e2856f86d3bd8cbdb6c6c079c96b8f6cf90088a694bb98b7af0f"

# Wave 2.3: MCP servers injected into ~/.claude.json on install.
# Effective name in claude.json: plugin-pm-essentials-{name}
# Restart Claude Code CLI after install to activate MCP servers.
mcp_servers:
  - name: filesystem-pm
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "${WORKSPACE}/workspace/project"
    env: {}

# Wave 2.2r: Integrations — env vars that plugin skills/heartbeats consume.
# Values are saved to .env under section # plugin-pm-essentials.
# Configure via /integrations → Custom tab → "PM Essentials — Todoist" card.
#
# Note: health_check is intentionally omitted for Todoist in v1.
# The Todoist REST API requires a Bearer Authorization header which is not
# yet supported by the v1 http health_check spec (headers support is a v2
# follow-up). Install, configure TODOIST_PLUGIN_API_KEY, and use the
# Test button (manual test endpoint) to verify connectivity.
integrations:
  - slug: todoist
    label: "PM Essentials — Todoist"
    category: productivity
    env_vars:
      - name: TODOIST_PLUGIN_API_KEY
        description: >
          Personal API token from
          https://todoist.com/app/settings/integrations/developer
        required: true
        secret: true