Metadata-Version: 2.4
Name: pongogo
Version: 0.3.0
Summary: AI agent knowledge routing system for software development
Project-URL: Homepage, https://github.com/pongogo/pongogo
Project-URL: Documentation, https://github.com/pongogo/pongogo#readme
Project-URL: Repository, https://github.com/pongogo/pongogo
Project-URL: Issues, https://github.com/pongogo/pongogo/issues
Author-email: Pongogo <hello@pongogo.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,knowledge,mcp,routing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: fastmcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-docker>=2.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Description-Content-Type: text/markdown

# Pongogo

Portable AI agent knowledge routing system. Install Pongogo on any repository to get intelligent instruction routing for AI coding assistants.

## Quick Start

```bash
# Install Pongogo CLI
pip install pongogo

# Configure MCP server for Claude Code (requires Docker)
pongogo setup-mcp

# Initialize in your repository
cd your-project
pongogo init
```

This creates a `.pongogo/` directory with configuration and seeded instruction files that help AI assistants understand your project's patterns and practices.

## Installation

### Zero-Config Install (Recommended)

The fastest way to get started:

```bash
curl -sSL https://get.pongogo.com | bash
```

The installer will:
1. Check if Docker is available
2. If Docker present: Pull the Docker image and configure Claude Code
3. If no Docker: Help you install Docker first

### Docker Installation

Docker is **required** for the MCP server to ensure proper multi-repo isolation:

```bash
# Pull the image
docker pull ghcr.io/pongogo/pongogo:stable

# Configure Claude Code
pongogo setup-mcp
```

> **Why Docker?** When using Pongogo across multiple repositories on the same machine, Docker ensures each workspace gets isolated state via volume mounts.

### Requirements

- **Docker** (required for MCP server)
- **Python 3.10+** (for CLI tools)
- Claude Code installed

## Usage

### Initialize Pongogo

```bash
pongogo init
```

Creates a `.pongogo/` directory with:

- `config.yaml` - Configuration for enabling/disabling instruction categories
- `instructions/` - Seeded instruction files (42 files across 14 categories)

### Command Options

| Flag | Short | Description |
|------|-------|-------------|
| `--minimal` | `-m` | Install only core instruction categories |
| `--force` | `-f` | Overwrite existing `.pongogo/` directory |
| `--no-interactive` | `-y` | Accept all defaults without prompting |

## Configuration

After initialization, customize `.pongogo/config.yaml`:

```yaml
# Enable/disable instruction categories
categories:
  software_engineering: true
  project_management: true
  agentic_workflows: true
  # ... set to false to disable

# Customize placeholders for your project
placeholders:
  wiki_path: wiki/
  docs_path: docs/
  owner_repo: your-org/your-repo
```

## Instruction Categories

| Category | Files | Description |
|----------|-------|-------------|
| software_engineering | 3 | Git safety, commit formats, Python standards |
| project_management | 6 | Work logging, scope prevention, task management |
| agentic_workflows | 4 | Agent decision making, compliance patterns |
| safety_prevention | 3 | Validation-first execution, systematic prevention |
| trust_execution | 3 | Trust-based execution, feature development |
| _pongogo_core | 10 | Core Pongogo workflows |
| + 8 more categories | | |

## MCP Server Integration

Pongogo includes an MCP (Model Context Protocol) server that routes instructions to AI coding assistants.

### Configure Claude Code

```bash
# Configure Claude Code (requires Docker)
pongogo setup-mcp

# Preview configuration without changes
pongogo setup-mcp --dry-run
```

### Upgrading

```bash
# Check for updates
/pongogo-status

# Upgrade
/pongogo-upgrade
# or: docker pull ghcr.io/pongogo/pongogo:stable
```

## Architecture

Pongogo routes instructions based on context:

```
User message → MCP Server → Semantic Router → Matched Instructions → Agent
```

The routing engine uses:
- **Pattern matching**: Keyword and regex patterns
- **Context disambiguation**: Positive/negative pattern weights
- **Lexicon database**: 329 entries for guidance, friction, and hedging detection

## Status

- ✅ `pongogo init` CLI
- ✅ Seeded instruction files (42 files, 14 categories)
- ✅ MCP server with Docker distribution
- ✅ Claude Code integration
- ✅ CI/CD with release train (alpha/beta/stable)

## License

MIT License - see [LICENSE](LICENSE)

---

**Named after "Pongo"** — the scientific name for the orangutan genus — reflecting the intelligent, collaborative nature of the system.
