⚡ git-prodman

Product management that lives in your Git repo

Local-first · AI-native · MIT licensed

Installation • Quick Start • Commands • Web UI • AI • Philosophy

git-prodman is a CLI tool that brings product management into your Git repository. PRDs, specs, epics, decisions—all stored as version-controlled YAML and Markdown files. No SaaS, no accounts, no cloud sync. Just Git.

Why?

Context fragmentation kills products. Specs in Notion, tasks in Jira, decisions in Slack, code in GitHub. git-prodman puts everything in one place: your repo.
Git is the best database for versioned, collaborative documents. Every edit creates a commit. Every merge is a sync.
AI works better with context. When your product artifacts live alongside your code, AI assistants can understand the full picture.

Features

📝 Specs & Epics — YAML + Markdown files with schema validation
🚶 User Journeys — Map user experiences with steps, emotions, and touchpoints
🗺️ Roadmap — Timeline view of milestones and releases
🤖 AI Assistant — Query your product with natural language (OpenAI, Anthropic, Ollama)
🌐 Bundled Web UI — Visual editor served locally, no separate install
🔀 Git-Native — Every save is a commit, sync when ready
🔍 Full-Text Search — Find anything across all artifacts
🌙 Dark/Light Mode — Easy on the eyes

Installation

npm (recommended)

npm install -g git-prodman

From source

git clone https://github.com/git-prodman/git-prodman.git
cd git-prodman
npm install
npm run build
npm link

Standalone binary

Download from Releases:

Platform	Download
macOS (Apple Silicon)	`prodman-macos-arm64`
macOS (Intel)	`prodman-macos-x64`
Linux (x64)	`prodman-linux-x64`
Windows (x64)	`prodman-win-x64.exe`

Quick Start

# Initialize in your project
cd your-project
prodman init

# Create your first epic
prodman epic create

# Start the web UI
prodman ui

This creates a .prodman/ directory:

.prodman/
├── product.yaml      # Product vision & OKRs
├── roadmap.yaml      # Milestones & releases
├── config.yaml       # Project settings
├── epics/            # Epic YAML files
├── specs/            # Spec Markdown files
├── issues/           # Issue tracking
├── decisions/        # Architecture Decision Records
├── journeys/         # User Journey maps
└── templates/        # Templates for new artifacts

Commands

Core Commands

prodman init              # Initialize .prodman/ in current repo
prodman ui [--port 3333]  # Start web UI
prodman status            # Show project overview

Artifact Management

# Epics
prodman epic create       # Create new epic (interactive)
prodman epic list         # List all epics
prodman epic show EP-001  # Show epic details

# Specs
prodman spec create       # Create new spec
prodman spec list         # List all specs
prodman spec show SP-001  # Show spec details

# Issues
prodman issue create      # Create new issue
prodman issue list        # List all issues

# User Journeys
prodman journey create    # Create new user journey
prodman journey list      # List all journeys
prodman journey show UJ-001  # Show journey details
prodman journey update UJ-001 --add-step  # Add steps interactively

# Decisions (ADRs)
prodman decision create   # Create new ADR
prodman decision list     # List all decisions

Git Operations

prodman sync              # Push commits to remote
prodman pull              # Pull with conflict detection
prodman diff              # Show uncommitted changes
prodman conflicts         # List files with merge conflicts
prodman resolve <file>    # Resolve merge conflicts

Search & AI

prodman search "auth"              # Full-text search
prodman ask "What's our MVP scope?" # AI query
prodman "summarize the roadmap"    # Bare AI query

Configuration

prodman config show       # Show current config
prodman config set        # Interactive configuration
prodman config path       # Show config file location

Web UI

Start the bundled web interface:

prodman ui

Opens http://localhost:3333 with:

Dashboard — Project stats, Git status, recent activity
Roadmap — Timeline view of milestones
Epics — Table view with status badges
Specs — List + split-pane Markdown editor
Journeys — User journey maps with step visualization
Kanban — Drag-and-drop board for epics and issues
Files — Tree explorer for .prodman/ directory
AI — Chat interface with streaming responses

Screenshots

Dashboard (Dark Mode)

The dashboard shows project stats, Git status, and recent epics.

File Explorer (Light Mode)

Browse and view all .prodman/ files in a tree structure.

AI Integration

git-prodman supports multiple AI providers:

OpenAI

prodman config set
# Select: openai
# Enter API key: sk-...
# Model: gpt-4o (default)

Anthropic (Claude)

prodman config set
# Select: anthropic  
# Enter API key: sk-ant-...
# Model: claude-3-5-sonnet-20241022 (default)

Ollama (Local)

# Start Ollama first
ollama serve

prodman config set
# Select: ollama
# Endpoint: http://localhost:11434 (default)
# Model: llama3.2 (default)

Usage

# CLI queries
prodman ask "What are our P0 epics?"
prodman "How should we approach the auth system?"

# Web UI
# Click the 🤖 AI tab and chat directly

Philosophy

Git is the Database

No external database. No sync service. Your Git repo IS the source of truth. This means:

Version history for free — Every change is a commit
Collaboration via Git — PRs, branches, merge conflicts
Backup = push — Your remote is your backup
Works offline — No internet required

Local-First

All data stays on your machine
No telemetry, no analytics, no tracking
No user accounts or authentication
Works in air-gapped environments

AI-Optional

Full functionality without AI
Bring your own API keys
Support for local models (Ollama)
Context stays private

MIT Licensed

100% open source
Fork it, modify it, sell it
No "open core" upselling
Community-driven development

File Formats

Epic (YAML)

id: EP-001
title: "User Authentication"
status: in_progress  # planning | in_progress | complete | cancelled
priority: p0         # p0 | p1 | p2 | p3
owner: "@alice"
milestone: v1.0-mvp

description: |
  Implement secure user authentication with OAuth2 support.

acceptance_criteria:
  - "[ ] Login with email/password"
  - "[ ] OAuth2 (Google, GitHub)"
  - "[x] Password reset flow"

progress: 60

Spec (Markdown + Frontmatter)

---
id: SP-001
title: "Auth API Design"
status: draft  # draft | review | approved | implemented
epic: EP-001
author: "@bob"
---

# Auth API Design

## Overview

This spec describes the authentication API endpoints...

User Journey (Markdown + Frontmatter)

---
id: UJ-001
title: "First-time project setup"
persona: "open-source-maintainer"  # References target_users in product.yaml
goal: "Initialize prodman in an existing repository"
status: draft  # draft | validated | implemented | deprecated
priority: p1
steps:
  - order: 1
    action: "Install prodman via npm"
    touchpoint: cli  # cli | web-ui | docs | api | external
    emotion: neutral  # frustrated | confused | neutral | satisfied | delighted
    pain_points: []
    opportunities: []
  - order: 2
    action: "Run prodman init"
    touchpoint: cli
    emotion: satisfied
    pain_points: []
    opportunities:
      - "Could auto-detect project type"
epics:
  - EP-001
---

# First-time project setup

## Overview

This journey maps the experience of setting up prodman for the first time...

Development

# Clone
git clone https://github.com/git-prodman/git-prodman.git
cd git-prodman

# Install dependencies
npm install

# Run in development
npm run dev -- --help
npm run dev -- ui

# Build
npm run build

# Type check
npm run typecheck

# Build standalone binaries
npm run pkg

Contributing

Contributions welcome! Please read our contributing guidelines first.

Fork the repo
Create a feature branch (git checkout -b feat/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feat/amazing-feature)
Open a Pull Request

License

MIT — Use it however you want.

Made with ❤️ for product people who love Git

Name		Name	Last commit message	Last commit date
.prodman		.prodman
.vscode		.vscode
dist		dist
node_modules		node_modules
public/fonts		public/fonts
src		src
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE		LICENSE
README.md		README.md
idea.md		idea.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation