first commit
This commit is contained in:
Stéphane Tailland
@@ -0,0 +1,118 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user