convez.ai
AgenteAutomaçãoAvançado
divyagowdrudinesh

Vistara PM Agent

divyagowdrudinesh/vistara-pm-agent

Automatize portfolios Jira + Confluence com Python e Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent Python que constrói portfolios enterprise-grade em Jira + Confluence via APIs REST Atlassian e Claude. Automatiza criação de épicos, histórias, subtarefas, sprints e páginas de documentação, com scripts especializados para correções em lote e descoberta de configurações.

Instalação

$npx convez-ai divyagowdrudinesh/vistara-pm-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Documentar retrospectivamente projetos complexos em Jira com múltiplos épicos e sprints
  • Sincronizar portfólios de programa entre Jira e Confluence de forma programática
  • Executar operações em lote: atribuição de sprints, correção de story points, adicionar critérios de aceição

Veredito

Ferramenta sólida e prática para gerentes de programa que precisam transformar trabalho de campo em artefatos Jira/Confluence escaláveis. O código é bem documentado e modular — cada script resolve um problema real de API. Requer familiaridade com REST APIs, credenciais Atlassian e variáveis de ambiente.

README

A tradução para o português deste README ainda está na fila.

vistara-pm-agent

Python agent that builds enterprise-grade Jira + Confluence portfolios via the Atlassian REST API and Anthropic Claude API.

Python License


Why this exists

Between 2022 and 2025 I served as Project Manager at Vistara Animation, leading real programme delivery across four strategic initiatives — curriculum brochures, festival logistics, college partnerships, and industry placement pipelines. The work happened in the field: spreadsheets, WhatsApp threads, physical whiteboards.

This agent retrospectively documents that body of work as a professional Jira + Confluence portfolio:

DimensionCount
Epics4
Stories42
Sub-tasks9
Sprints9
Confluence pagesin progress

Each script was written to solve a concrete API problem discovered while building the portfolio. The codebase is the artefact — it shows not just what was managed, but how the documentation was engineered.

Portfolio PDF: [Portfolio — link to be added]


Architecture

flowchart TD
    A[.env] -->|load_dotenv| B[agent.py / create_epicN.py]
    B -->|REST POST /rest/api/3/issue| C[Jira Cloud]
    B -->|REST POST /rest/agile/1.0/sprint| C
    B -->|REST POST /wiki/api/v2/pages| D[Confluence Cloud]
    E[config.py] -->|PROJECT_KEY, issue types| B
    F[fix_*.py / backfill_*.py] -->|PATCH existing issues| C
    G[debug/] -->|discovery & smoke tests| C
    G -->|discovery & smoke tests| D

What each script does

ScriptPurpose
agent.pyCore helper — create_issue() function used across Epic 1 & 2; reads env vars, sets auth headers
config.pyShared constants: PROJECT_KEY = "VAI", issue type strings
create_epic3.pyBuilds Epic 3 (Cinemotsava 2025): 14 stories, sub-tasks, acceptance criteria, Sprints 6–7
create_epic4.pyBuilds Epic 4 (Partner College & Placement Pipeline): 10 stories, sub-tasks, acceptance criteria, Sprints 8–9
create_sprints.pyCreates Sprints 4–5 for the Epic 2 brochure workstream via Agile API
assign_sprints.pyBulk-assigns issue keys to sprint IDs via POST /rest/agile/1.0/sprint/{id}/issue
add_acceptancecriteria.pyPosts acceptance criteria as ADF-formatted comments on all Epic 1 & 2 stories
fix_storypoints.pyPatches story points on Epic 2 stories using customfield_10037
fix_subtasks.pyAdds two missing sub-tasks to Epic 2 parent stories
fix_subtasks_e3.pyAdds three missing sub-tasks to Epic 3 parent stories
backfill_epic1_points.pyRetrospectively sets story points on all 10 Epic 1 issues
find_sprints.pyDiscovery — lists all boards and sprints for the VAI project (used to get board ID 100)
find_confluence.pyDiscovery — lists personal and global Confluence spaces to locate the VAI space
debug/debug_addcriteria.pyVerifies env vars load correctly and tests comment API against VAI-15
debug/debug_direct.pyHardcoded-credential smoke test to isolate auth failures from .env loading
debug/debug_points.pyScans all Jira fields to identify story point custom field IDs
debug/delete_testpage.pyDeletes a specific Confluence test page by page ID
debug/test_confluence_write.pyCreates a test page in the VAI Confluence space to verify write permissions
debug/test_personal_direct.pyAttempts to access the personal Confluence space by its ~userid key
debug/test_personal_space.pyLists all Confluence spaces to locate the personal space key

Quick start

# 1. Clone
git clone https://github.com/divyagowdrudinesh/vistara-pm-agent.git
cd vistara-pm-agent

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure credentials
cp .env.example .env
# Open .env and fill in your Atlassian API token, email, base URL, and Anthropic key

# 4. Run the main agent
python agent.py

Key technical decisions

1 — customfield_10037 not customfield_10016

Jira Cloud uses two different custom field IDs for story points depending on whether the project uses next-gen or classic boards. customfield_10016 is the next-gen field; customfield_10037 is the classic Software board field. debug_points.py was written specifically to enumerate all field IDs and find the correct one.

2 — "Sub-task" (hyphenated)

The Jira REST API v3 rejects "Subtask" with a 400. The correct issue type name is "Sub-task" with a hyphen. This is not documented prominently in the official docs.

3 — Atlassian 404 on expired token

When an Atlassian API token expires, the platform returns 404 (not 401). This means expiry looks like a missing resource, not an authentication failure. Always check token validity first when you see unexpected 404s on known issue keys.

4 — ADF 5-level nesting for acceptance criteria

Confluence Atlassian Document Format requires a strict content hierarchy for structured content: doc → bulletList → listItem → paragraph → text. Flattening or skipping any level causes a 400 with a cryptic schema validation error.


Bug log

#BugRoot causeFix
1Story points not savingUsed customfield_10016 (next-gen field) on a classic boardSwitched to customfield_10037 found via debug_points.py
2Sub-task creation 400Issue type name "Subtask" rejected by APIChanged to "Sub-task" (hyphenated) per Jira schema
3All requests returning 404Atlassian API token expired mid-sessionRotated token in .env; confirmed with debug_direct.py
4Sprint creation 400Sprint name exceeded 30-character limitShortened all sprint names
5Comment creation 400Plain text rejected, ADF required for v3 APIRebuilt all payloads in ADF
6Sprint 4 Issues Not CompletedStories transitioned to Done after sprint closeDocumented as lesson
7Velocity chart shows 0 for Sprints 1-4Story points backfilled after sprint closeDocumented as limitation
8Confluence API 403Free tier blocks programmatic creation in personal spacesScoped out Epics 2-4

Author

Divya G D — Project Manager, Vistara Animation (2022–2025)

LinkedIn

Ver o original no GitHub

Bom para

Relacionados