Metadata-Version: 2.1
Name: instructionkit
Version: 0.3.1
Summary: CLI tool for managing AI coding tool instructions
Author-email: Troy Larson <troy@calvinware.com>
License: MIT License
Project-URL: Homepage, https://github.com/instructionkit/instructionkit
Project-URL: Documentation, https://github.com/instructionkit/instructionkit#readme
Project-URL: Repository, https://github.com/instructionkit/instructionkit
Project-URL: Issues, https://github.com/instructionkit/instructionkit/issues
Keywords: cli,ai,instructions,cursor,copilot,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: textual>=0.41.0
Requires-Dist: GitPython>=3.1.45
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: invoke>=2.0.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20240808; extra == "dev"

<div align="center">

# 🎯 InstructionKit

**Get your AI coding assistant following best practices in under 2 minutes**

[![CI](https://github.com/troylar/instructionkit/actions/workflows/ci.yml/badge.svg)](https://github.com/troylar/instructionkit/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/troylar/instructionkit/branch/main/graph/badge.svg)](https://codecov.io/gh/troylar/instructionkit)
[![PyPI version](https://img.shields.io/pypi/v/instructionkit.svg)](https://pypi.org/project/instructionkit/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Supports:** Cursor • GitHub Copilot • Windsurf • Claude Code

</div>

---

## 🚀 Get Started in 60 Seconds

```bash
# 1. Install
pip install instructionkit

# 2. Download instruction repository (with optional version control)
inskit download --repo https://github.com/troylar/instructionkit-examples
# Or pin to a specific version:
# inskit download --repo https://github.com/user/repo --ref v1.0.0

# 3. Browse & install with interactive TUI
inskit install
```

**✨ What you just got:**
- 🐍 Python best practices (type hints, async patterns)
- ⚛️ React & TypeScript patterns
- 🧪 Testing with pytest
- 🔐 Security (OWASP Top 10)
- 🐳 Docker optimization
- 📝 Documentation standards
- ...and more!

Your AI assistant now follows these guidelines automatically when you code. **No configuration needed.**

👉 **[Browse all 12 examples](https://github.com/troylar/instructionkit-examples)** or keep reading to use your own instructions.

---

## 🌟 What is InstructionKit?

A powerful CLI tool that enables developers to **browse, install, and manage** instructions for AI coding assistants. Download instruction repositories to your local library, browse them with an interactive TUI, and install exactly what you need.

Perfect for:
- ⚡️ **Getting started fast** with curated examples
- 🏢 **Standardizing team practices** across projects
- 📚 **Building personal libraries** of coding patterns
- 🔄 **Sharing knowledge** across your organization

> **CLI name:** Commands use `inskit` (short for InstructionKit)

## ✨ Features

<table>
<tr>
<td width="50%">

### 🎨 **Interactive TUI Browser**

- Browse your instruction library with a beautiful terminal UI
- Search and filter instructions by name, description, or repository
- Select multiple instructions with checkboxes
- Choose installation location and target tools interactively
- See exactly where files will be installed before confirming

</td>
<td width="50%">

### 📚 **Local Library Management**

- Download instruction repositories to your local library
- Keep multiple repositories organized in one place
- Update repositories to get the latest instructions
- List and delete repositories from your library
- Fast offline browsing once downloaded

</td>
</tr>
<tr>
<td>

### 🎯 **Project-Level Installation**

- All installations are project-specific
- Automatic project root detection
- Organized in tool-specific directories (`.cursor/rules/`, `.claude/rules/`, etc.)
- Clean, versioned alongside your code
- Portable tracking with relative paths (works across teams and machines)

</td>
<td>

### 📦 **Flexible Sources & Versioning**

- Download from Git repositories (GitHub, GitLab, Bitbucket, self-hosted)
- **Version Control:** Pin to tags, track branches, or lock to commits
- Download from local folders (perfect for testing and development)
- Support for private repositories with standard Git authentication
- Bundle support for installing multiple instructions at once
- Automatic updates for branch-based installations

</td>
</tr>
<tr>
<td>

### 🎯 **Smart Management**

- Auto-detect installed AI coding tools
- Track all installed instructions with metadata
- Smart conflict resolution (skip, rename, overwrite)
- Easy uninstall functionality

</td>
<td>

### 🔐 **Enterprise Ready**

- Works with private repositories
- No external dependencies beyond Git
- Secure, local-only storage
- Cross-platform support (macOS, Linux, Windows)

</td>
</tr>
</table>

## 📚 Using Your Own Instructions

Want to use company or custom instructions instead? It's just as easy:

```bash
# Download from your GitHub repo
inskit download --from https://github.com/yourcompany/instructions

# Browse and install with the TUI
inskit install
```

The interactive TUI lets you:
- 🔍 Search and filter by tags
- ☑️ Select multiple instructions
- 🎯 Choose which AI tools to install to
- 📦 See exactly what gets installed

**Managing your library:**

```bash
inskit list library              # See what's downloaded
inskit update --all              # Get latest updates
inskit delete <repo-namespace>   # Remove a repository
```

### Alternative: Direct Installation

For quick one-off installs without using the library:

```bash
# Direct install (bypasses library)
inskit install python-best-practices --from https://github.com/company/instructions

# See what's available from a repo
inskit list available --from https://github.com/company/instructions
```

## 📖 Usage

### Library Management

<details>
<summary><b>Download Instructions to Your Library</b></summary>

Build your local library of instruction repositories with version control:

```bash
# Download from Git repository (default branch)
inskit download --repo https://github.com/company/instructions

# Download specific version by tag (pinned, won't auto-update)
inskit download --repo https://github.com/company/instructions --ref v1.0.0

# Download specific branch (will auto-update)
inskit download --repo https://github.com/company/instructions --ref main

# Download specific commit (pinned, won't auto-update)
inskit download --repo https://github.com/company/instructions --ref abc123def

# Download from local folder (no version control)
inskit download --repo ./my-instructions

# Re-download to get latest updates
inskit download --repo https://github.com/company/instructions --force
```

**Version Control Benefits:**
- 📌 **Tags:** Pin to specific releases (e.g., `v1.0.0`) - won't auto-update
- 🌿 **Branches:** Track latest changes (e.g., `main`, `develop`) - auto-updates
- 📍 **Commits:** Lock to exact state (e.g., `abc123`) - won't auto-update
- 📦 **Multiple Versions:** Install different versions of same repo side-by-side

Your library is stored in `~/.instructionkit/library/` and organized by repository namespace and version.

</details>

<details>
<summary><b>List Your Library Contents</b></summary>

```bash
# Show all repositories in library
inskit list library

# Show individual instructions
inskit list library --instructions

# Filter by repository alias
inskit list library --source company
```

</details>

<details>
<summary><b>Update Library Repositories</b></summary>

```bash
# Update a specific repository
inskit update --namespace github.com_company_instructions

# Update all repositories in library
inskit update --all
```

**Smart Update Behavior:**
- 🌿 **Branches:** Automatically pull latest changes from remote
- 📌 **Tags:** Skipped (immutable - won't update)
- 📍 **Commits:** Skipped (immutable - won't update)
- 🔄 **Installed Files:** Automatically updated after pulling changes

**Example Output:**
```
Updating 3 repository(ies)...

⊘ Skipped: python-standards (tag v1.0.0 is immutable)
✓ Updated: react-patterns (branch main)
✓ Updated: api-guidelines (branch develop)

✓ Updated: 2 repository(ies)
⊘ Skipped: 1 immutable reference(s)
```

</details>

<details>
<summary><b>Delete from Library</b></summary>

```bash
# Delete a repository (keeps installed instructions)
inskit delete github.com_company_instructions

# Skip confirmation
inskit delete github.com_company_instructions --force
```

Note: Deleting from library doesn't uninstall instructions. Use `inskit uninstall` for that.

</details>

### Interactive TUI Browser

<details>
<summary><b>Using the TUI to Browse and Install</b></summary>

Launch the interactive browser:

```bash
inskit install
```

**TUI Features:**

- **Search**: Type `/` to search by name or description
- **Filter**: Select repository from dropdown
- **Select**: Use `Space` or `Enter` to toggle instruction selection
- **Select All**: Press `Ctrl+A` or click "Select All" button
- **Target Tools**: Check boxes for Cursor, Windsurf, Claude Code, etc.
- **Install**: Review summary and click "📦 Install Selected"

The TUI shows exactly where files will be installed in your project before you confirm.

</details>

<details>
<summary><b>Install Specific Instruction by Name</b></summary>

Install directly from library without TUI:

```bash
# Install by name (opens selection if multiple matches)
inskit install python-style

# The command will:
# 1. Search your library for "python-style"
# 2. If found in multiple repos, ask which one
# 3. Install the selected instruction
```

</details>

### Installing Instructions

<details>
<summary><b>Project-Level Installation</b></summary>

InstructionKit installs all instructions at the **project level**:

**How it works:**

- All instructions are installed to your current project
- Stored in tool-specific directories in your project root:
  - **Claude Code**: `.claude/rules/*.md`
  - **Cursor**: `.cursor/rules/*.mdc`
  - **Windsurf**: `.windsurf/rules/*.md`
  - **GitHub Copilot**: `.github/instructions/*.md`
- Tracked in `<project-root>/.instructionkit/installations.json`
- Automatically detects project root (looks for `.git`, `pyproject.toml`, `package.json`, etc.)
- Can be run from any directory within the project

```bash
# Install to current project
inskit install python-best-practices --from https://github.com/company/instructions

# All installations are project-level
inskit install python-style

# List shows project installations
inskit list installed
```

**Why project-level?**

- Instructions stay with your code (version controlled)
- Team members get the same instructions automatically
- Different projects can have different instructions
- Clean, organized structure per tool
- Portable across machines - uses relative paths in tracking
- No setup needed when cloning - instructions just work

</details>

### Advanced: Direct Installation (Bypasses Library)

<details>
<summary><b>Install Directly from Repository</b></summary>

For one-off installs without downloading to library first:

```bash
# Basic install (to current project)
inskit install python-best-practices --from https://github.com/company/instructions

# Install to specific tool
inskit install python-best-practices --from https://github.com/company/instructions --tool cursor

# Handle conflicts by renaming
inskit install python-best-practices --from https://github.com/company/instructions --conflict rename

# Overwrite existing
inskit install python-best-practices --from https://github.com/company/instructions --conflict overwrite
```

</details>

<details>
<summary><b>Install from Local Folder</b></summary>

```bash
# Relative path
inskit install python-best-practices --from ./my-instructions

# Absolute path
inskit install python-best-practices --from /path/to/instructions

# Great for testing before committing to Git
inskit install my-new-instruction --from ~/Documents/instruction-drafts
```

</details>

<details>
<summary><b>Install Bundles</b></summary>

```bash
# Install a bundle of related instructions
inskit install python-backend --bundle --from https://github.com/company/instructions

# This might install: python-style, testing-practices, api-design, etc.
```

</details>

### Listing & Viewing

<details>
<summary><b>List Installed Instructions</b></summary>

```bash
# Show all installed instructions in current project
inskit list installed

# Filter by AI tool
inskit list installed --tool cursor

# Filter by source repository
inskit list installed --repo https://github.com/company/instructions
```

**Shows comprehensive information:**
- Instruction name and AI tool
- Source repository URL
- **Version information** with visual badges:
  - 📌 v1.0.0 (tag - pinned version)
  - 🌿 main (branch - tracking latest)
  - 📍 abc123 (commit - locked to specific state)
- Installation date
- Project scope

**Example Output:**
```
Installed Instructions
────────────────────────────────────────────────────────────
AI Tool    Instruction       Scope    Source         Version      Installed
Claude     python-style      Project  company/...    📌 v1.0.0   2025-10-26
Cursor     react-patterns    Project  company/...    🌿 main     2025-10-26
Claude     api-guidelines    Project  company/...    📍 abc123   2025-10-26
```

</details>

<details>
<summary><b>List Available Instructions (Without Library)</b></summary>

Directly query a repository without downloading it:

```bash
# From Git repository
inskit list available --from https://github.com/company/instructions

# From local folder
inskit list available --from ./my-instructions

# Filter by tag
inskit list available --from https://github.com/company/instructions --tag python

# Show only bundles
inskit list available --from https://github.com/company/instructions --bundles-only
```

**Tip:** For regular use, it's better to `download` the repo to your library and browse with the TUI!

</details>

### Uninstalling Instructions

```bash
# Uninstall from all tools in current project
inskit uninstall python-best-practices

# Uninstall from specific tool
inskit uninstall python-best-practices --tool cursor

# Skip confirmation
inskit uninstall python-best-practices --force
```

### Viewing Detected Tools

```bash
# See which AI coding tools are installed
inskit tools
```

## 📂 Storage & Tracking

InstructionKit stores everything locally:

**Library Storage:**

- Downloaded repositories: `~/.instructionkit/library/`
- Organized by repository namespace (e.g., `github.com_company_instructions/`)
- Browse offline after downloading

**Installation Tracking:**

- Tracked in `<project-root>/.instructionkit/installations.json`
- Contains metadata for all installed instructions in the project
- Created automatically when you install instructions
- **Uses relative paths** - portable across different machines and users
- **Version control friendly** - no absolute paths with usernames
- **Recommended:** Commit to Git so team members get the same setup automatically
- Alternative: Add to `.gitignore` if instructions should be personal

**Why commit installations.json?**

- Team members automatically see which instructions are installed
- Works seamlessly when cloned to different machines
- No manual setup needed - everyone gets the same configuration
- Changes to installed instructions are tracked in version control

The `list installed` command shows all instructions in the current project.

## 📁 Creating Your Own Instructions

InstructionKit works with simple folder structures - no Git repository required!

### Minimal Structure

```
my-instructions/
├── instructionkit.yaml          # Required: Metadata file
└── instructions/
    └── my-instruction.md        # Your instruction files
```

### instructionkit.yaml Format

```yaml
name: My Instructions Repository
description: A collection of my coding instructions
version: 1.0.0

instructions:
  - name: my-instruction
    description: What this instruction does
    file: instructions/my-instruction.md
    tags:
      - tag1
      - tag2
```

### Full Example with Bundles

```
my-instructions/
├── instructionkit.yaml
├── instructions/
│   ├── python-style.md
│   ├── testing.md
│   └── api-design.md
└── README.md                    # Optional
```

**instructionkit.yaml:**

```yaml
name: My Instructions
description: Personal coding standards
version: 1.0.0

instructions:
  - name: python-style
    description: Python coding standards
    file: instructions/python-style.md
    tags: [python, style]

  - name: testing
    description: Testing best practices
    file: instructions/testing.md
    tags: [testing, quality]

  - name: api-design
    description: API design guidelines
    file: instructions/api-design.md
    tags: [api, backend]

bundles:
  - name: python-stack
    description: Complete Python development setup
    instructions:
      - python-style
      - testing
    tags: [python]
```

## 💡 Use Cases

### For Enterprise Teams

```bash
# Step 1: Download company instruction repository
inskit download --from git@github.com:company/instructions

# Step 2: In your project, browse and install with TUI
cd /path/to/project
inskit install
# - Select company standards or project-specific guidelines
# - Choose which AI tools to install to
# - Install to current project
# - Commit .instructionkit/ and tool directories to Git
# - Team members automatically get the same setup!
```

### For Open Source Projects

```bash
# Maintainers: Set up project guidelines
cd your-project
inskit download --from https://github.com/project/instructions
inskit install
# Select "contributing", "code-style", etc.
# Commit to Git so all contributors get them

# Contributors: Clone and get instructions automatically
git clone https://github.com/project/repo
cd repo
# Instructions are already there in .cursor/rules/, .claude/rules/, etc.
# Just start coding with AI assistance!
```

### For Personal Productivity

```bash
# Build your personal library
inskit download --from ~/Documents/my-instructions
inskit download --from https://github.com/awesome/prompts

# In each project, pick what you need
cd my-project
inskit install
# Search, filter, and install what's relevant for this project

# Test new instructions locally before publishing
inskit download --from ./instruction-drafts --force
inskit install  # test them out in your current project
```

### For Education

```bash
# Instructors: Set up course template
inskit download --from https://github.com/university/course-materials
cd course-template
inskit install
# Select course-wide coding standards
# Commit and share template repo with students

# Students: Assignment-specific guidance
cd assignment-1
inskit install
# Select assignment-specific instructions
# AI assistants now follow assignment requirements
```

## 🛠 Requirements

- **Python:** 3.10 or higher
- **Git:** Installed and accessible from command line (only for Git repository sources)
- **AI Tool:** At least one of: Cursor, GitHub Copilot, Windsurf, or Claude Code

## 📋 Supported AI Tools

All tools use **project-level installation** with tool-specific directories:

| Tool               | Project Path            | File Extension | Status             |
| ------------------ | ----------------------- | -------------- | ------------------ |
| **Claude Code**    | `.claude/rules/`        | `.md`          | ✅ Fully Supported |
| **Cursor**         | `.cursor/rules/`        | `.mdc`         | ✅ Fully Supported |
| **Windsurf**       | `.windsurf/rules/`      | `.md`          | ✅ Fully Supported |
| **GitHub Copilot** | `.github/instructions/` | `.md`          | ✅ Fully Supported |

**Note:** All paths are relative to your project root. InstructionKit automatically detects the project root by looking for `.git/`, `pyproject.toml`, `package.json`, etc.

## 🤝 Contributing

We welcome community contributions of all sizes. Before you get started:

- 📘 Read the [Contributing Guide](CONTRIBUTING.md) for setup, coding standards, and PR expectations
- 🤝 Review the [Code of Conduct](CODE_OF_CONDUCT.md) to keep our community respectful and inclusive
- 🐛 [Report a bug](https://github.com/troylar/instructionkit/issues/new?template=bug_report.yml) using the guided template
- 💡 [Request a feature](https://github.com/troylar/instructionkit/issues/new?template=feature_request.yml) and tell us how it helps your workflow

When you're ready to contribute code:

1. Fork the repo or create a feature branch
2. Run `invoke quality` and `invoke test` locally
3. Open a pull request using the template and link any related issues
4. Expect an automatic review request thanks to CODEOWNERS—feedback is collaborative and friendly

Curious where to start? Check out [good first issues](https://github.com/troylar/instructionkit/issues?q=is%3Aopen+label%3A%22good+first+issue%22) or start a [discussion](https://github.com/troylar/instructionkit/discussions) to explore ideas.

## 📬 Contact

- **Author:** Troy Larson
- **Email:** [troy@calvinware.com](mailto:troy@calvinware.com)

### Development Setup

```bash
# Clone repository
git clone https://github.com/troylar/instructionkit.git
cd instructionkit

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode with all dependencies
pip install -e .[dev]
```

### Common Development Tasks

```bash
# List all available tasks
invoke --list

# Run tests
invoke test                    # Run all tests
invoke test --verbose          # Verbose output
invoke test --coverage         # With coverage report
invoke test-unit               # Unit tests only
invoke test-integration        # Integration tests only

# Code quality
invoke quality                 # Run all checks
invoke quality --fix           # Auto-fix issues
invoke lint --fix              # Fix linting issues
invoke format                  # Format code
invoke typecheck               # Type checking

# Build and install
invoke clean                   # Clean build artifacts
invoke build                   # Build package
invoke install                 # Install package

# Utilities
invoke count                   # Count lines of code
invoke version                 # Show version
invoke tree                    # Show project structure
```

### Manual Testing

```bash
# Run all tests manually
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/unit/test_models.py

# Run with coverage
pytest --cov=instructionkit --cov-report=html
```

See **[DEVELOPMENT.md](DEVELOPMENT.md)** for complete development guide including:

- Detailed task documentation
- Testing strategies
- Code style guidelines
- Debugging tips
- Release process
- Contributing guidelines

## 🗺 Roadmap

- [x] **Version Control:** Pin to tags, track branches, or lock to commits ✅ v0.2.0
- [ ] **Template Variables:** Support for dynamic instruction content with variables
- [ ] **Instruction Search:** Search across all available instructions by content
- [ ] **Dependency Management:** Automatic installation of instruction dependencies
- [ ] **Remote Catalogs:** Centralized instruction catalogs for discovery
- [ ] **Instruction Validation:** Lint and validate instruction content
- [ ] **Export/Backup:** Export installed instructions for backup or migration

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Built with:

- [Typer](https://typer.tiangolo.com/) - CLI framework
- [Rich](https://rich.readthedocs.io/) - Terminal formatting
- [Textual](https://textual.textualize.io/) - Interactive TUI
- [PyYAML](https://pyyaml.org/) - YAML parsing

---

<div align="center">

**Made with ❤️ for the AI coding community**

[Report Bug](https://github.com/troylar/instructionkit/issues) • [Request Feature](https://github.com/troylar/instructionkit/issues)

</div>
