---

name: klondike-agent-workflow description: Manage multi-session AI agent workflows using klondike CLI. Use when working on klondike-managed projects (those with .klondike/ directory), when starting/ending coding sessions, tracking features through lifecycle, or maintaining coherence across context window resets. Triggers on session management, feature tracking, progress handoffs, and verification workflows.

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