Metadata-Version: 2.4
Name: klondike-spec-cli
Version: 0.2.13.dev3
Summary: CLI tool for managing Klondike Spec agent workflow artifacts
Project-URL: Homepage, https://github.com/ThomasRohde/klondike-spec-cli
Project-URL: Repository, https://github.com/ThomasRohde/klondike-spec-cli
Project-URL: Issues, https://github.com/ThomasRohde/klondike-spec-cli/issues
Author: Thomas Rohde
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,copilot,klondike-spec,workflow
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: pypith>=0.1.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: mcp>=1.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == 'mcp'
Description-Content-Type: text/markdown

# 🎴 Klondike Spec CLI

> **The CLI that built itself** — A tool for managing AI agent workflows, created through the very methodology it implements.

[![PyPI version](https://badge.fury.io/py/klondike-spec-cli.svg)](https://badge.fury.io/py/klondike-spec-cli)
[![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)
[![Tests](https://github.com/ThomasRohde/klondike-spec-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ThomasRohde/klondike-spec-cli/actions)
[![Coverage](https://img.shields.io/badge/coverage-74%25-green.svg)](https://github.com/ThomasRohde/klondike-spec-cli)

---

## 🌟 The Story: When AI Builds Its Own Tools

**What happens when you ask an AI coding agent to build a tool for managing AI coding agents?**

You get Klondike Spec CLI — a project that went from concept to **100% feature completion** in just 4 coding sessions, with the AI agent using the very methodology and artifacts the tool was designed to manage.

### The Challenge

Modern AI coding agents like GitHub Copilot are powerful, but they face a fundamental limitation: **context windows reset between sessions**. Every new conversation starts fresh, losing the accumulated knowledge, decisions, and progress from previous work.

[Anthropic's research on effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) highlighted this challenge and inspired a solution: structured artifacts that bridge context windows.

### The Solution: Klondike Spec

The **Klondike Spec** framework provides:
- 📋 A **feature registry** that prevents "victory declarations" (agents claiming completion prematurely)
- 📝 A **progress log** for session-to-session handoffs
- ✅ **Verification evidence** requirements before features can be marked complete
- 🔄 **Structured workflows** that guide agents through complex, multi-session projects

> **🐍 Python-First**: Klondike Spec is currently optimized for Python development workflows, with built-in support for `uv`, `pytest`, `ruff`, and modern Python tooling. The instructions and CI/CD patterns assume a Python project structure. Contributions to support other ecosystems are welcome!

### The Meta-Journey

This CLI tool was built by an AI agent **following the Klondike Spec methodology** — tracking its own features, managing its own sessions, and providing verification evidence for each completed feature. The dog ate its own dog food, and it was delicious.

**40 features. 7 sessions. 142 tests. 100% verified.**

---

## ⚡ Built with Pith: Agent-Native CLI Design

Klondike Spec CLI is powered by [**Pith**](https://github.com/ThomasRohde/pith) — a revolutionary CLI framework designed specifically for AI agents.

Unlike traditional CLI frameworks that prioritize human interaction patterns, Pith implements **progressive discovery**:

```
Tier 1: pith → Overview of all commands
Tier 2: command → Synopsis and usage  
Tier 3: command --help → Full documentation
```

AI agents can efficiently navigate the CLI surface, discovering exactly what they need without overwhelming context. Pith also supports:

- 🎯 **Semantic intents** — Commands can be invoked by meaning, not just exact syntax
- 📊 **Structured output** — JSON mode for programmatic integration
- 🧠 **Schema export** — Full command structure for AI tooling

---

## 🌳 Isolated Worktree Sessions

One of Klondike's most powerful features is the ability to run AI agents in **isolated git worktrees**. This provides a safe sandbox where agents can make changes without affecting your main project until you're ready.

### Why Worktrees?

- 🔒 **Isolation** — Changes are made in a separate directory, protecting your main branch
- 🧪 **Experimentation** — Let the agent try risky changes without fear
- 🔀 **Parallel work** — Run multiple agent sessions simultaneously on different features
- ↩️ **Easy rollback** — Just delete the worktree if things go wrong

### Worktree Commands

```bash
# Start Copilot in an isolated worktree
klondike copilot start --worktree

# Focus on a specific feature (creates branch like klondike/f001-abc123)
klondike copilot start -w --feature F001

# Custom session name
klondike copilot start -w --name "refactor-auth"

# Auto-cleanup worktree when session ends
klondike copilot start -w --cleanup

# Apply changes back to main project after session
klondike copilot start -w --apply

# List all active worktree sessions
klondike copilot list

# Remove all worktree sessions
klondike copilot cleanup
```

### Worktree Directory Structure

Worktrees are created in a centralized location outside your project:

```
~/klondike-worktrees/
└── my-project/
    ├── .klondike-project          # Marker linking to original project
    ├── f001-abc123/               # Worktree for feature F001
    │   └── <full project copy>
    └── refactor-auth-def456/      # Named worktree session
        └── <full project copy>
```

The agent works in the worktree with a dedicated branch (`klondike/f001-abc123`), commits freely, and when done you can:
- Apply the changes with `--apply`
- Cherry-pick specific commits
- Merge the branch manually
- Or just delete it with `klondike copilot cleanup`

---

## 🚀 Installation

### Global Installation (Recommended)

Install `klondike` as a globally available command using [uv](https://github.com/astral-sh/uv) or [pipx](https://pipx.pypa.io/):

```bash
# Using uv (fastest)
uv tool install klondike-spec-cli

# Using pipx
pipx install klondike-spec-cli
```

This makes the `klondike` command available system-wide, isolated from your project dependencies.

### Project Dependency

Add to your project's dependencies:

```bash
# Using uv
uv add klondike-spec-cli

# Using pip
pip install klondike-spec-cli
```

---

## 🎯 Quick Start

### Initialize Your Project

```bash
# Create .klondike directory and .github templates
klondike init my-awesome-project

# Skip .github scaffolding if you already have it
klondike init my-awesome-project --skip-github

# See where you stand
klondike status
```

```
📊 Project: my-awesome-project v0.1.0
   Completion: 0.0%

Progress: [░░░░░░░░░░░░░░░░░░░░] 0.0%

  ⏳     Not Started         0

🎯 Ready to add features!
```

### Define Your Features

```bash
# Add features with acceptance criteria
klondike feature add -d "User authentication" -c core -p 1 \
  --criteria "Login form works,Password validation,Session management"

klondike feature add -d "Dashboard UI" -c ui -p 2 \
  --criteria "Responsive layout,Data visualization,Real-time updates"

# See your feature backlog
klondike feature list
```

### Work Through Features

```bash
# Start a coding session
klondike session start --focus "F001 - User authentication"

# Mark what you're working on
klondike feature start F001

# When complete with evidence
klondike feature verify F001 --evidence "All tests pass, demo video recorded"

# End the session
klondike session end --summary "Auth complete" --completed "Login,Logout,Sessions"
```

### Track Progress Across Sessions

```bash
# Check overall status (includes git info!)
klondike status
```

```
📊 Project: my-awesome-project v0.1.0
   Completion: 50.0%

Progress: [██████████░░░░░░░░░░] 50.0%

  ✅     Verified            1
  ⏳     Not Started         1

📅 Last Session: #1 (2025-12-07)
   Focus: F001 - User authentication

📂 Git Status: ✅ Clean (branch: main)
Recent commits:
  abc123 2025-12-07 feat(auth): implement user login

🎯 Next Priority Features:
    ⏳ Not started  F002: Dashboard UI
```

---

## 📚 Complete Command Reference

### Project Commands

| Command | Description |
|---------|-------------|
| `klondike init [name]` | Initialize .klondike directory and .github templates |
| `klondike init --skip-github` | Initialize without .github scaffolding |
| `klondike status` | Show project status, git info, and next priorities |
| `klondike validate` | Check artifact integrity and consistency |
| `klondike progress` | Regenerate agent-progress.md from JSON |
| `klondike report` | Generate detailed status report |
| `klondike release [version]` | Automate version bumping and release tagging |

### Feature Management

| Command | Description |
|---------|-------------|
| `klondike feature add` | Add a new feature with description and criteria |
| `klondike feature list` | List features with optional status filter |
| `klondike feature show <id>` | Display full feature details |
| `klondike feature start <id>` | Mark feature as in-progress |
| `klondike feature verify <id>` | Mark as verified with evidence |
| `klondike feature block <id>` | Mark as blocked with reason |
| `klondike feature edit <id>` | Edit notes, criteria, priority |

### Session Management

| Command | Description |
|---------|-------------|
| `klondike session start` | Begin session (validates artifacts, shows status) |
| `klondike session end` | End session with summary and handoff notes |

### AI Agent Integration

| Command | Description |
|---------|-------------|
| `klondike copilot start` | Launch GitHub Copilot CLI with klondike context |
| `klondike copilot start --worktree` | Launch Copilot in an isolated git worktree |
| `klondike copilot start -w --feature F001` | Worktree session focused on a specific feature |
| `klondike copilot list` | List active worktree sessions |
| `klondike copilot cleanup` | Remove all worktree sessions |
| `klondike mcp serve` | Start MCP server for AI agent integration |
| `klondike mcp install` | Generate MCP server config for VS Code |
| `klondike mcp config` | Output MCP configuration JSON |

### Import/Export

| Command | Description |
|---------|-------------|
| `klondike import-features <file>` | Import features from YAML/JSON |
| `klondike export-features <file>` | Export features to YAML/JSON |

### Shell Completion

```bash
# Bash
klondike completion bash >> ~/.bashrc

# Zsh  
klondike completion zsh > ~/.zsh/completions/_klondike

# PowerShell
klondike completion powershell >> $PROFILE
```

---

## 📁 Project Structure

After running `klondike init`, your project will have:

```
your-project/
├── .klondike/
│   ├── features.json         # 📋 Feature registry (source of truth)
│   ├── agent-progress.json   # 📝 Session log and handoffs
│   └── config.yaml           # ⚙️ CLI configuration
├── agent-progress.md         # 📖 Generated human-readable progress
└── .github/
    ├── copilot-instructions.md  # 🤖 Agent behavior rules
    ├── instructions/            # 📚 Workflow instruction files
    │   ├── git-practices.instructions.md
    │   ├── session-artifacts.instructions.md
    │   └── testing-practices.instructions.md
    ├── prompts/                 # 💬 Reusable prompt templates
    │   ├── add-features.prompt.md
    │   ├── progress-report.prompt.md
    │   ├── recover-from-failure.prompt.md
    │   ├── session-end.prompt.md
    │   ├── session-start.prompt.md
    │   └── verify-feature.prompt.md
    └── templates/               # 📐 Init scripts and schemas
        ├── agent-progress.template.md
        ├── features.schema.json
        ├── init.ps1
        └── init.sh
```

> **Tip**: Use `--skip-github` if your project already has a `.github` directory you want to preserve.

---

## 🔧 Configuration

`.klondike/config.yaml`:

```yaml
# Default category for new features
default_category: core

# Default priority (1=critical, 5=nice-to-have)
default_priority: 2

# Who verifies features
verified_by: coding-agent

# Where to generate the markdown progress file
progress_output_path: agent-progress.md

# Auto-regenerate markdown on changes
auto_regenerate_progress: true
```

---

## 🤝 Integration with Klondike Spec Framework

This CLI is designed to work seamlessly with the [**Klondike Spec**](https://github.com/ThomasRohde/klondike-spec) prompting framework for GitHub Copilot.

The framework provides:
- 📜 **Copilot instructions** that embed agent behavior rules
- 🎬 **Slash commands** (`/session-start`, `/session-end`, `/verify-feature`)
- 📐 **Templates** for consistent project structure

**The CLI handles artifact manipulation. The framework guides agent behavior.**

Together, they enable sophisticated multi-session agent workflows that maintain coherence across context window resets.

---

## 🧪 Development

```bash
# Clone and setup
git clone https://github.com/ThomasRohde/klondike-spec-cli.git
cd klondike-spec-cli
uv sync

# Run tests (142 tests)
uv run pytest -v

# Lint and type check
uv run ruff check .
uv run mypy src

# Build
uv build
```

### Project Stats

- **40+ features** — all verified with evidence
- **167 tests** — comprehensive coverage
- **7 sessions** — iterative development
- **4500+ lines** of well-structured Python

---

## 🎴 Why "Klondike"?

Like the classic card game, building complex software with AI agents requires **patience, strategy, and careful arrangement** of moving pieces. You can't just pile cards randomly — you need structure, rules, and a clear view of your progress.

Klondike Spec provides that structure. The CLI gives you the tools to maintain it.

---

## 📜 License

MIT — See [LICENSE](LICENSE) for details.

---

## 🔗 Related Projects

- [**Klondike Spec**](https://github.com/ThomasRohde/klondike-spec) — The prompting framework for GitHub Copilot
- [**Pith**](https://github.com/ThomasRohde/pith) — Agent-native CLI framework with progressive discovery

---

<div align="center">

**Built with 🤖 by AI, for AI, verified by humans**

*"The best way to predict the future is to build the tools that build the future."*

</div>
