Klondike Agent Workflow

Klondike bridges context windows for long-running agent sessions. Critical: Always use CLI commands—never directly read/edit .klondike/*.json files or agent-progress.md.

CRITICAL: Common Mistakes to Avoid

❌ NEVER do these:

• klondike --help (wrong syntax - use klondike alone or klondike <command> without --help)
• klondike feature --help (wrong - just run the command, it will show usage)
• Read .klondike/features.json directly (use klondike feature list)
• Edit agent-progress.md manually (auto-generated, changes are lost)
• klondike feature start without feature ID (must be klondike feature start F001)
• Feature IDs like f001 or 1 (must be uppercase: F001)

✓ DO these:

• klondike alone shows all commands
• klondike feature list to see features
• klondike feature show F001 for details
• klondike status to see project overview

Quick Decision Tree

Starting work?     → klondike status → klondike session start --focus "F001 - desc"
Working on feature → klondike feature start F001
Feature complete?  → Test E2E → klondike feature verify F001 --evidence "..."
Blocked?           → klondike feature block F001 --reason "..."
Ending session?    → klondike session end --summary "..." --next "..."

Session Lifecycle

1. Session Start (Always Do First!)

klondike status                                    # See project state
klondike validate                                  # Check artifact integrity
klondike session start --focus "F001 - Login UI"  # Begin session
klondike feature start F001                        # Mark feature in-progress

2. During Work

• One feature at a time (tracked by feature start)
• Commit after each meaningful change
• Test incrementally, not at end
• If blocked: klondike feature block F001 --reason "..."

3. Session End (Before Leaving!)

klondike feature verify F001 --evidence "test-results/F001.png"
klondike session end --summary "Done" --next "Implement logout"

Core Commands

| Action | Command | Notes | |--------|---------|-------| | Status | klondike status | Always start here | | Add feature | klondike feature add "desc" --notes "hints" | --notes is critical | | Start feature | klondike feature start F001 | One at a time | | List features | klondike feature list | Never read JSON directly | | Show details | klondike feature show F001 | View single feature | | Verify | klondike feature verify F001 --evidence "proof" | E2E test first | | Block | klondike feature block F001 --reason "why" | When stuck | | Start session | klondike session start --focus "F001 - desc" | Begin work | | End session | klondike session end --summary "..." --next "..." | Before leaving |

Essential Rules

Always:

• Start every session with klondike status to see project state
• Use --notes when adding features (gives future agents critical context)
• Capture evidence (screenshots, logs) before feature verify
• Run pre-commit checks before every commit
• End sessions with session end --summary ... --next ...

Never:

• Use klondike --help or klondike feature --help (wrong syntax - see Common Mistakes)
• Read or edit .klondike/*.json files directly (use CLI commands)
• Edit agent-progress.md manually (auto-generated, edits are lost)
• Verify features without E2E testing (unit tests aren't enough)
• Commit code with failing tests, lint errors, or build failures

Pre-Commit Checks

Detect project type and run checks. Never commit if any fail.

Python (uv): uv run ruff check src tests && uv run pytest
Node.js: npm run lint && npm run build && CI=true npm test
Rust: cargo clippy && cargo test
Go: golangci-lint run && go test ./...

Reference Files (Load As Needed)

Load these only when you need specific details:

• commands.md: Full CLI reference with all options/flags
• workflows.md: Multi-session patterns, worktrees, complex scenarios
• troubleshooting.md: Error recovery and corrupted state fixes