# pm-backlog-agent AI agent for managing the backlog of one or several products. Supports multiple personas (PM, developer, tester, designer) with role-based access control. ## Coding Guidelines - **Language**: all code, comments, commit messages, and documentation in English. - **Comments**: only when the why is non-obvious. No block comments, no section dividers. - **Conciseness**: no boilerplate, no placeholders, no "coming soon" stubs. - **No over-engineering**: solve the problem at hand; don't design for hypothetical futures. - **Images**: always use `latest` when the tag exists; pin to the latest known version only when `latest` is not published (e.g. Harbor). Keeps images up to date with security patches. ## Architecture ### Protocol stack Four complementary layers — each owns a distinct concern: ``` ┌─────────────────────────────────────────┐ │ A2UI (Google) │ WHAT to render — declarative UI spec ├─────────────────────────────────────────┤ │ AG-UI (CopilotKit) │ HOW agent ↔ UI talk — event transport ├─────────────────────────────────────────┤ │ A2A (Google) │ HOW agents ↔ agents talk ├─────────────────────────────────────────┤ │ MCP │ HOW agent ↔ tools talk └─────────────────────────────────────────┘ ``` - **MCP** — outbound only; the agent calls Jira, Confluence, Calendar, and Metabase as MCP tools. No MCP server is exposed publicly. - **A2A** — inbound from other agents (security, market watch, communication). OAuth2 Client Credentials; each peer agent has its own service account. - **AG-UI** — inbound from human users via the React frontend. Bidirectional event bus (SSE/WebSocket): streams chat tokens, tool call results, state deltas, thinking steps, and A2UI component payloads back to the UI; user actions flow back to the agent through the same channel. - **A2UI** — declarative JSON component descriptions embedded inside AG-UI events. Agents describe UI components (sprint board, story card, approval dialog); the client renders them using its own native widgets from a trusted catalog. No arbitrary code execution — UI is data, not code. ### Agent (backend) **PydanticAI** (Python) — structured outputs via Pydantic models map naturally to Jira issues, epics, and sprint plans. FastAPI serves both the AG-UI endpoint and the A2A endpoint on a single process. ### UI (frontend) Handled by the shared **`pm-ui`** microservice (separate repo). `pm-ui` is a Next.js + CopilotKit app that serves as the single frontend for all agents in the ecosystem. It routes to each agent's AG-UI endpoint depending on context. This agent does not own or ship any UI code. ### Auth - **Human users** — "Sign in with Google" (OAuth2 Authorization Code + PKCE). Free, no infrastructure. Google Calendar scopes requested at login time — one consent flow covers both authentication and Calendar access. Actions in Calendar appear as the actual user, not a service account. RBAC enforced in FastAPI middleware (PM / developer / tester / designer roles mapped from JWT claims). - **Peer agents** — HashiCorp Vault (AppRole / JWT auth). Short-lived tokens, automatic rotation. One Vault role per agent. OAuth2 Client Credentials flow on the A2A endpoint. - **Downstream APIs** (Jira, Confluence, Metabase) — agent's own Vault-managed service account. User identity recorded in the agent's audit log, not delegated downstream. ### Attack surface Two inbound surfaces on one FastAPI server, one port, one TLS certificate: ``` /ag-ui/* → human users (OAuth2 Auth Code + PKCE) /a2a/* → peer agents (OAuth2 Client Credentials) ``` Outbound only: MCP calls to Jira, Confluence, Calendar, Metabase, and the communication agent over A2A. ### Integrations - **Jira** — create, update, prioritize, and triage backlog items - **Confluence** — link stories to specs, auto-generate acceptance criteria docs - **Calendar** (Google Calendar / Outlook) — sync sprint ceremonies, deadlines, and stakeholder meetings - **Metabase** — backlog health dashboards (open-source, self-hostable, REST API) ### Communication **Do not add Slack, email, or other notification tools directly to this agent.** All delivery is delegated to a dedicated **communication agent** called over A2A. This centralises credential management, channel routing, rate limiting, and de-duplication across the entire multi-agent system. --- ## User Stories ### Persona & Access Control - As a **PM**, I can log in and get full read/write access to all backlog items, epics, and settings. - As a **developer**, I can view and update items assigned to me but cannot reprioritize or delete items. - As a **tester**, I can view backlog items, add test notes, and transition items to "ready for QA". - As a **designer**, I can view items, attach design assets, and flag items needing UX review. - As any persona, I can see only the boards and projects I have been granted access to. ### Backlog Management - As a **PM**, I can ask the agent in natural language to create a new Jira story with title, description, acceptance criteria, and priority. - As a **PM**, I can ask the agent to reprioritize the backlog based on business value and effort, and get a ranked list with reasoning. - As a **PM**, I can ask the agent to split an epic into stories and have them created automatically in Jira. - As a **PM**, I can ask the agent to find duplicate or similar stories and propose merges. - As a **PM**, I can ask the agent to identify stale items (no activity for N days) and propose archiving or updating them. - As a **PM**, I can ask the agent to generate a sprint plan given team capacity and story estimates. ### Triage & Enrichment - As a **PM**, I can paste raw feature requests or bug reports and have the agent create properly formatted Jira items. - As any persona, I can ask the agent to enrich a story with acceptance criteria generated from its description. - As a **PM**, I can ask the agent to label and categorize a batch of untagged items. - As a **PM**, I can ask the agent to estimate story points for items that lack them, with a brief rationale. ### Calendar & Ceremony Sync - As a **PM**, I can ask the agent to schedule a backlog refinement session and have it appear in team calendars. - As a **PM**, I can ask the agent to show me what is due before a given date, cross-referencing Jira due dates and calendar events. - As any persona, I can get a daily or weekly digest of upcoming deadlines and ceremonies. ### Dashboards & Reporting - As a **PM**, I can ask the agent to generate a backlog health report (velocity, age distribution, blocked items). - As a **PM**, I can ask the agent to show the current sprint progress and flag items at risk. - As a **PM**, I can ask the agent to produce a release notes draft from items marked "done" in a sprint. - As a **stakeholder**, I can ask the agent for a plain-language summary of what the team is working on this sprint. ### Agent-to-Agent Intake - As the **security agent**, I can submit a vulnerability finding and have the agent create a Jira security issue with the correct priority, label, and assignee. - As the **market watch agent**, I can submit a competitive insight and have the agent create a discovery story linked to the relevant epic. - As any **external agent**, I can query the backlog API to check whether a given topic already has an open item before creating a duplicate. - As a **PM**, I can review, approve, or reject agent-submitted items from a dedicated intake queue. ### Confluence Integration - As a **PM**, I can ask the agent to generate a Confluence page for a new epic from the associated Jira stories. - As any persona, I can ask the agent to find the Confluence spec linked to a story. - As a **PM**, I can ask the agent to update a Confluence decision log with the outcome of a backlog discussion. ### Notifications & Alerts Notifications are delivered by the **communication agent** over A2A — this agent does not call Slack or email directly. - As any persona, I can opt in to receive a notification when an item I am watching changes status. - As a **PM**, I can configure alerts for when the backlog exceeds a size threshold or when no items are estimated. - As a **PM**, I can choose my preferred notification channel (email, Slack, etc.) in my profile; the communication agent handles delivery.