klondike-spec-cli 0.2.9

CLI tool for managing Klondike Spec agent workflow artifacts

🎴 Klondike Spec CLI

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

---

🌟 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 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 — 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

---

🚀 Installation

Global Installation (Recommended)

Install klondike as a globally available command using uv or pipx:

# 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:

# Using uv
uv add klondike-spec-cli

# Using pip
pip install klondike-spec-cli

---

🎯 Quick Start

Initialize Your Project

# 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

# 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

# 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

# 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 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
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:

# 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 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

# 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
• 142 tests — comprehensive coverage
• 7 sessions — iterative development
• 4200+ 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 for details.

---

🔗 Related Projects

• Klondike Spec — The prompting framework for GitHub Copilot
• Pith — Agent-native CLI framework with progressive discovery

---

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."