Fulcrum

Fulcrum es un gestor de proyectos agentico, pensado para integrarse con Coder (https://coder.com) y GitHub Codespaces.

Features

• PM Agent: Agente conversacional con 12 tools, 3 modos (Chat/Agent/God), y streaming SSE
• Multi-Agent System: 5 sub-agentes especializados (Research, Code Analysis, Task Executor, Report, Code Generation)
• Project Status: Overview de cualquier proyecto con estado de Git, GitHub issues/PRs, y tareas
• GitHub Integration: OAuth, repos, issues, PRs, Codespaces, Actions
• Coder Integration: OAuth, workspaces, MCP Bridge para operaciones remotas
• Code Generation: Delegacion a OpenCode via AgentAPI en workspaces Coder
• Settings UI: Configuracion de modelo PM, moderation pipeline, y search providers
• Audit Logs: Registro de acciones destructivas y bloques de moderacion
• Security: Token encryption, CSRF, rate limiting, content moderation, path traversal prevention

Quick Start (Docker)

# 1. Configurar entorno
cp .env.example .env
bash init_env.sh

# 2. Levantar servicios
docker compose up -d

# 3. Migraciones
docker compose exec api alembic upgrade head

# 4. Verificar
curl http://localhost:8000/health
open http://localhost:8000          # Web UI
open http://localhost:8000/docs     # API docs (Swagger)

Documentacion

Documento	Proposito
docs/GOVERNANCE.md	Reglas operativas multi-agente (estados, DoD, gobernanza)
docs/API_CONTRACT.md	Contrato vivo backend/frontend (endpoints y tipos)
docs/WORKFLOWS.md	Flujos E2E canonicos con criterios de acceptance
docs/RUNBOOK.md	Comandos estandar de setup/build/test y troubleshooting
docs/KNOWN_GAPS.md	Lista viva de brechas/deferred con owner y next action
docs/HANDOFF.md	Registro de traspasos entre sesiones/agentes
docs/DECISIONS/ADR-0000-doc-governance.md	ADR inicial de gobernanza documental
ROADMAP.md	Trabajo pendiente priorizado (P0-P3)
docs/deprecated/README.md	Indice de documentacion historica/deprecada

Estructura del repositorio

fulcrum/
├── src/
│   ├── api/                    # FastAPI (routers, middleware, static assets + Vue dist)
│   │   ├── middleware/         # Auth, CSRF, rate limiting
│   │   ├── routers/           # Auth, projects, chat, settings, integrations
│   │   ├── services/          # User service
│   │   └── static/            # Built Vue assets (`dist/`) + icons/images
│   ├── clients/               # Git, GitHub, Coder MCP, AgentAPI, filesystem
│   ├── config/                # Coder configuration
│   ├── core/
│   │   ├── agents/            # PM Agent, sub-agents, tools, moderation, search
│   │   └── auth/              # JWT security, Fernet encryption
│   ├── models/                # SQLAlchemy models (user, project, chat, agent, audit)
│   ├── server/                # MCP server + tool implementations
│   ├── storage/               # Database interfaces (Postgres)
│   └── workers/               # Celery workers (5 agent queues)
├── alembic/                   # Database migrations (17 versions)
├── tests/                     # pytest test suite
├── docker-compose.yml         # api + worker + db + redis
├── Dockerfile
├── pyproject.toml
├── init_env.sh                # Environment initialization
└── generate_secrets.sh        # Secret generation

Configuracion

Variables requeridas en produccion

• JWT_SECRET: Clave secreta para firmar tokens JWT (la app falla sin ella en produccion)
• ENCRYPTION_KEY: Clave Fernet para encriptar tokens de API en la BD
• DATABASE_URL: DSN de PostgreSQL

Variables opcionales

• CORS_ORIGINS: Origenes permitidos (default: localhost:8000,3000)
• CSRF_ENABLED: Habilitar CSRF protection (1 para activar)
• REDIS_URL: Redis para Celery y rate limiting
• PROJECTS_ROOT: Directorio de proyectos (default: /home/coder/Projects)
• FEEDBACK_GITHUB_REPO: Repo destino para feedback (default: successbyfailure/project-assistant)
• OAUTH_TOKEN_HEALTH_CHECK_ENABLED: Habilita monitor proactivo de expiracion OAuth por Celery beat (1/0)
• OAUTH_TOKEN_HEALTH_CHECK_INTERVAL_MINUTES: Intervalo de ejecucion del monitor OAuth
• OAUTH_TOKEN_HEALTH_WINDOW_MINUTES: Ventana para marcar tokens como proximos a expirar
• ENVIRONMENT: development | staging | production

Ver .env.example para la lista completa.

Docker Services

Servicio	Puerto	Proposito
api	8000	FastAPI + Web UI
worker	-	Celery workers (research, code_gen, task_executor, code_analysis, report)
db	5432	PostgreSQL 16
redis	6379	Broker, cache, rate limiting

Testing (backend)

El flujo oficial de tests backend se ejecuta sobre la imagen Docker api:

docker compose build api
docker compose run --rm -e PYTHONPATH=/app api bash -lc "pip install --no-cache-dir .[dev] && pytest -q tests"

Referencia completa y troubleshooting: docs/RUNBOOK.md.

Notas

• La app usa Postgres (ver docker-compose.yml) para tareas manuales y de agentes.
• La UX de Ajustes concentra PM/Moderacion/Busqueda. Integraciones mantiene cuentas y OAuth.

License

MIT