protoagent.bundle.yaml

# A protoAgent plugin BUNDLE (ADR 0040) — the Portfolio Manager tier of the
# portfolio→team hierarchy, the manager-of-teams counterpart to the Lead Engineer
# bundle (github.com/protoLabsAI/leadEngineer).
#
# Install:  python -m server plugin install <this-repo-url>
#
# A Portfolio Manager orchestrates work across MANY Lead Engineer teams: it spins a
# team up per project (portfolio_spinup_team), dispatches features to it over A2A,
# rolls up + diffs + sequences cross-board dependencies, and disposes a team once its
# board drains. It does NOT run a board itself — that's the team tier.
#
# So this bundle ENABLES the manager tier (delegates + portfolio + github) but
# INSTALLS the team tier too (project_board + agent_browser, off by default): a
# spawned team's plugins.dir defaults to THIS host's plugins dir, so the team
# discovers project_board here without a per-team reinstall. Install once, provision
# many teams. github is enabled at the MANAGER tier itself — filing/triaging issues
# is portfolio-manager work (surfacing what a team can't unblock, tracking cross-repo
# asks), not something only a coding team needs.
#
# PIN LIFECYCLE (ADR 0049): pins are release TAGS and only move through a passing
# verify — .github/workflows/verify-bundle.yml installs this manifest into a scratch
# agent and probes every declared console view (each PR + weekly), and the scheduled
# bump job opens a PR when a member tags a new release. Keep member entries on ONE
# line (scripts/check_bundle_updates.py rewrites the `ref:` token in place).
id: pm-stack
name: Portfolio Manager
description: >-
  The manager-of-teams tier (ADR 0055). One agent orchestrates work across MANY Lead
  Engineer teams: it spins a team up per project on demand (portfolio_spinup_team),
  dispatches features to each team's board over A2A, rolls up a bounded cross-board
  view, watches for changes, sequences cross-board dependencies, and disposes a team
  once its board drains. It runs no board of its own — the project-team counterpart is
  the Lead Engineer bundle. Enables the manager spine (delegates + portfolio + github,
  the last for filing/triaging issues) and carries the team plugins (project_board +
  agent_browser, installed but off) so the teams it spawns discover them on this host.
  The portfolio→team split of the old pm-stack.

# The core version this exact pin set was last verified against (ADR 0049). The verify
# workflow checks out this protoAgent ref for the smoke — bump on re-verify.
verified_against: 0.95.1

plugins:
  - { id: delegates, builtin: true }                                                  # ACP/A2A spawn spine — ships with protoAgent
  - { id: portfolio,     url: https://github.com/protoLabsAI/portfolio-plugin,     ref: v0.16.0 }   # orchestrate + spawn teams
  - { id: github,        url: https://github.com/protoLabsAI/github-plugin,       ref: v0.1.3 }   # file/triage issues + PRs across repos
  - { id: project_board, url: https://github.com/protoLabsAI/projectBoard-plugin,  ref: v0.32.0 }  # installed-not-enabled: spawned teams' board
  - { id: agent_browser, url: https://github.com/protoLabsAI/agent-browser-plugin, ref: v0.5.1 }   # installed-not-enabled: spawned teams' browser

# The PM runs the MANAGER tier: delegates + portfolio + github. project_board +
# agent_browser stay installed-but-off here — they're for the Lead Engineer teams this
# PM spawns (which discover them via this host's plugins dir), not for the PM itself.
enabled: [delegates, portfolio, github]
config:
  portfolio:
    # The base team config portfolio_spinup_team clones per project. EMPTY IS THE HAPPY PATH
    # (portfolio v0.14+): a spawned team inherits the PM's own resolved gateway + its
    # OPENAI_API_KEY (via the team's env), so it runs real model turns with NO creds prep.
    # Only point this at a creds-filled copy for a team on a DIFFERENT gateway than the PM's.
    # {{REPO}} / {{TEAM_NAME}} / {{GATE}} are filled per spawn.
    team_template: ""
  github:
    # github-plugin ships `write: false` by default (its own operator-trust gate) — this
    # bundle opts IN at the manager tier: a PM's job includes filing issues (an unblockable
    # dependency, a cross-repo ask) and triaging (commenting/labeling), not just reading.
    # Merge itself stays confirm-guarded by the plugin regardless of this setting.
    write: true
    # No default_repo/repos here — those are operator/instance config (which repos THIS
    # PM watches), not a bundle-wide default. Set them in your own langgraph-config.yaml.

# Agent archetype (ADR 0042) — presents this bundle as a "Portfolio Manager" agent type
# in the new-agent picker, with a starting persona. Additive metadata.
archetype:
  label: Portfolio Manager
  icon: Network
  blurb: Orchestrates many engineering teams — spins one up per project, dispatches + rolls up work, disposes it when the board drains.
  soul: |
    # Portfolio Manager

    You are a portfolio manager. You orchestrate work across MANY engineering teams —
    you do not write code or run a board yourself.

    Your loop, per project:
    - Spin up a team for it with `portfolio_spinup_team(name, repo)` — an ephemeral
      Lead Engineer pinned to that repo. Reuse a standing team if one already fits.
      It runs a READ-ONLY readiness scan on spin-up (no board features, no code
      changes) and hands YOU the summary — you own the board, so review it and
      `portfolio_dispatch` whatever actually needs work; the team never self-boards.
    - Dispatch self-sufficient features to its board with `portfolio_dispatch` (give a
      clear spec + acceptance criteria + the files to touch — a vague task ships nothing).
    - Sequence cross-team dependencies with `portfolio_link` + `portfolio_plan` +
      `portfolio_autodispatch`; hold work behind a blocker and release it when that ships.
    - Stay current without polling: `portfolio_watch` once, then read the deltas
      `portfolio_diff` surfaces (merged / blocked / unblocked / new).
    - Dispose a finite project's team when its board drains — `portfolio_autodispose`
      (or `portfolio_teardown_team`). Standing teams you keep.
    - File and triage GitHub issues for anything a team can't resolve itself — an
      external dependency, a cross-repo ask, a bug that needs a human's call. Comment/
      label to keep them current as work moves; that's portfolio-manager work, not a
      team's.

    Think in terms of OUTCOMES across the portfolio, not individual diffs. Keep each
    team's brief small and shippable, watch the rollup, unblock what's stuck, and report
    progress as features merge to done.