PromptyDumpty

# PromptyDumpty

![PyPI - Workflow](https://github.com/dasiths/PromptyDumpty/actions/workflows/publish-to-pypi.yml/badge.svg) [![PyPI - Version](https://img.shields.io/pypi/v/prompty-dumpty)](https://pypi.org/project/prompty-dumpty/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/prompty-dumpty)](https://pypi.org/project/prompty-dumpty/) [![License](https://img.shields.io/pypi/l/prompty-dumpty)](https://github.com/dasiths/PromptyDumpty/blob/main/LICENSE)

<img src="website/public/logo.png" width=200px />

A lightweight, universal package manager for AI coding assistants (prompts, instructions, rules, workflows, etc.).

🌐 **Visit [dumpty.dev](https://dumpty.dev)** for full documentation and guides.

## What is it?

PromptyDumpty lets you install and manage prompt packages across different AI coding assistants like GitHub Copilot, Claude, Cursor, Gemini, Windsurf, OpenCode, and more.

## Why PromptyDumpty?

### The Problem

Without a package manager, sharing AI assistant configurations is painful:

- 📋 **Manual file management** - Copying `.md` files between projects and agent folders
- 🔄 **No updates** - When prompts improve, you manually re-copy everywhere
- 🗑️ **Messy removal** - Deleting prompts leaves orphaned files scattered across directories
- 🤷 **No tracking** - Can't remember what's installed or where it came from
- 🔁 **Multi-agent duplication** - Maintaining separate versions for Copilot, Claude, Cursor, etc.
- 📧 **Ad-hoc sharing** - Sending via email/Slack with instructions like "just copy to `.claude/commands/`"

### The Solution

- **Share prompts easily**: Package and distribute your team's prompts via Git
- **Works everywhere**: One package works with multiple AI coding assistants
- **Simple**: Just YAML files and Git repos, no complex setup
- **Safe**: Clean installation and removal, clear tracking with lockfiles

## Quick Start

```bash
# Initialize in your project
dumpty init

# Install a package
dumpty install https://github.com/org/my-prompts

# List installed packages
dumpty list

# Update packages
dumpty update --all

# Remove a package
dumpty uninstall my-prompts
```

## How it works

1. **Auto-detects** your AI agent (checks for `.github/prompts/`, `.claude/commands/`, etc.)
2. **Installs** package files to the right directories
3. **Tracks** everything in a lockfile for easy management
4. **Organizes** files by package name for clean removal

## Package Structure

Organize your files however you want! The manifest defines everything:

```
my-package/
├── dumpty.package.yaml  # Package manifest
├── README.md
└── src/                 # Any structure you prefer
    ├── planning.md
    ├── review.md
    └── standards.md
```

## Creating Packages

Define what your package provides in `dumpty.package.yaml` - organized by agent and type:

```yaml
name: my-workflows
version: 1.0.0
description: Custom development workflows
manifest_version: 1.0
author: Your Name
license: MIT
homepage: https://github.com/org/my-workflows

agents:
  copilot:
    prompts:
      - name: code-review
        description: Code review workflow
        file: src/review.md
        installed_path: code-review.prompt.md
    agents:
      - name: standards
        description: Coding standards agent
        file: src/standards.md
        installed_path: standards.agent.md
    instructions:
      - name: repo-guidelines
        description: Repository-specific coding guidelines
        file: src/guidelines.md
        installed_path: guidelines.instructions.md

  claude:
    commands:
      - name: code-review
        description: Code review command
        file: src/review.md
        installed_path: review.md
```

**Key Features:**
- Organize files however makes sense to you
- Organize artifacts by type (prompts, agents, rules, commands, etc.)
- Use "files" type for generic artifacts
- Explicitly map each file to its install location per agent
- Reuse the same source file for multiple agents
- Installation paths: `{agent_dir}/{type}/{package}/{file}`

## External Repository References

Reference files from external repositories without forking.

Add `external_repository` to your manifest to pull files from another repository:

```yaml
name: curated-prompts
version: 1.0.0
manifest_version: 1.0
author: Your Name
license: MIT
external_repository: https://github.com/community/prompts@a1b2c3d4e5f6789012345678901234567890abcd

agents:
  copilot:
    prompts:
      - name: refactoring
        file: prompts/refactoring.md
        installed_path: refactoring.prompt.md
```

**Format:** `<git-url>@<40-char-commit-hash>`

When external repo is specified:
- All file paths resolve from the external repository
- Both repos are tracked in lockfile
- Use full commit hashes only (no tags/branches)

**Use cases:**
- Curate content from large community repositories
- Version-lock third-party prompts
- Create team-specific views of shared content

## Documentation

📚 **Full documentation available at [dumpty.dev](https://dumpty.d

... (truncated)