klondike-spec-cli 0.1.0

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

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.

30 features. 4 sessions. 98 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

pip install klondike-spec-cli

Or with uv (recommended):

uv add klondike-spec-cli

---

🎯 Quick Start

Initialize Your Project

# Create .klondike directory with all artifacts
klondike init my-awesome-project

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

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

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

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

---

🔧 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 (98 tests, 74% coverage)
uv run pytest -v

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

# Build
uv build

Project Stats

• 30 features — all verified with evidence
• 98 tests — comprehensive coverage
• 4 sessions — from zero to 100%
• 1600+ 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."