pm-backlog-agent/CLAUDE.md

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.