🇺🇸 English · 🇨🇱 Español

---

🇺🇸 ai-project-manager

An AI agent that autonomously manages software project backlogs — writing tasks to Trello, auditing task completion against real Git commits, and coordinating between GitHub, Trello, and Google Sheets. Built to eliminate "ghost Done cards" and keep project state honest.

The Problem It Solves

In fast-moving dev teams, project management boards drift from reality:

• Cards marked "Done" that never had a real commit behind them
• Backlog in a spreadsheet disconnected from the Trello board
• No automatic detection of when a branch is ready to merge

This agent fixes all three.

What It Does

🔍 Commit Auditing

POST /api/v1/cron/audit-trello-done scans every card in the Done column and looks for a matching commit (last 30 days, matched by story code US-XX or title keywords). If no commit is found, the agent comments on the card and asks the responsible dev — it doesn't assume the work is done.

📋 Backlog Management

• Syncs tasks between Google Sheets (operational) and Trello (visual)
• Auto-assigns the correct team member in Trello
• Discovers new GitHub repos and onboards them into the backlog

🔀 Merge Readiness Detection

POST /api/v1/cron/check-merge-readiness compares develop vs main per project via the GitHub API. If develop has commits that main doesn't, it creates a merge recommendation card with the exact commit count.

Architecture

┌─────────────────────────────────────────────────────┐
│                  FastAPI Application                │
│  /api/v1/                                           │
│  ├── projects/   → Project registry + discovery    │
│  ├── tasks/      → Backlog management              │
│  └── cron/       → Audit jobs                      │
└──────────────────────────────────────────────────────┘
         │              │              │
   ┌─────▼──┐    ┌──────▼──┐   ┌──────▼──────┐
   │ GitHub │    │  Trello │   │Google Sheets│
   │   API  │    │   API   │   │     API     │
   └────────┘    └─────────┘   └─────────────┘

Key Design Decisions

Why not GPT to decide if a task is done?
LLMs hallucinate. The agent only checks for hard evidence: a real commit with a matching code or keyword. No commit = not done, period.

Why FastAPI?
Async support for concurrent API calls to GitHub + Trello + Sheets. Pydantic for request validation. Automatic OpenAPI docs.

Stack

Python 3.11 · FastAPI · Uvicorn · GitHub API · Trello REST API · Google Sheets API · Vertex AI (optional) · Docker · Cloud Run

Setup

git clone https://github.com/Seba-LupeLab/ai-project-manager
cd ai-project-manager
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload
# Docs at http://localhost:8000/docs

Example API Calls

# Audit all Done cards for real commits
curl -X POST http://localhost:8000/api/v1/cron/audit-trello-done

# Check merge readiness across all projects
curl -X POST http://localhost:8000/api/v1/cron/check-merge-readiness

# Discover new repos not yet in backlog
curl http://localhost:8000/api/v1/projects/discover

---

🇨🇱 ai-project-manager

Agente de IA que gestiona autónomamente el backlog de proyectos de software — escribe tareas en Trello, audita el cumplimiento contra commits reales de Git y coordina entre GitHub, Trello y Google Sheets. Construido para eliminar las "tarjetas Done fantasma".

El Problema que Resuelve

En equipos de desarrollo que avanzan rápido, los tableros de gestión se desconectan de la realidad:

• Tarjetas marcadas como "Done" sin ningún commit real detrás
• Backlog en una hoja de cálculo desconectado del tablero de Trello
• Sin detección automática de cuándo una rama está lista para mergearse

Este agente resuelve los tres.

Qué Hace

🔍 Auditoría de Commits

POST /api/v1/cron/audit-trello-done escanea cada tarjeta en la columna Done y busca un commit coincidente (últimos 30 días, por código US-XX o palabras clave del título). Si no encuentra commit, el agente comenta en la tarjeta y le pregunta al dev responsable — no asume que el trabajo está terminado.

📋 Gestión de Backlog

• Sincroniza tareas entre Google Sheets (operacional) y Trello (visual)
• Asigna automáticamente el miembro correcto del equipo en Trello
• Descubre nuevos repos de GitHub y los incorpora al backlog

🔀 Detección de Merge Readiness

POST /api/v1/cron/check-merge-readiness compara develop vs main por proyecto vía la API de GitHub. Si develop tiene commits que main no tiene, crea una tarjeta de recomendación de merge con el conteo exacto de commits.

Arquitectura

┌─────────────────────────────────────────────────────┐
│               Aplicación FastAPI                    │
│  /api/v1/                                           │
│  ├── projects/   → Registro + descubrimiento        │
│  ├── tasks/      → Gestión de backlog              │
│  └── cron/       → Jobs de auditoría               │
└──────────────────────────────────────────────────────┘
         │              │              │
   ┌─────▼──┐    ┌──────▼──┐   ┌──────▼──────┐
   │ GitHub │    │  Trello │   │Google Sheets│
   │   API  │    │   API   │   │     API     │
   └────────┘    └─────────┘   └─────────────┘

Decisión de Diseño Clave

¿Por qué no usar GPT para decidir si una tarea está hecha?
Los LLMs alucinan. El agente solo verifica evidencia concreta: un commit real con código o palabras clave coincidentes. Sin commit = no está hecho, punto.

Stack

Python 3.11 · FastAPI · Uvicorn · GitHub API · Trello REST API · Google Sheets API · Vertex AI (opcional) · Docker · Cloud Run

Inicio Rápido

git clone https://github.com/Seba-LupeLab/ai-project-manager
cd ai-project-manager
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload
# Documentación en http://localhost:8000/docs