Skip to content

Quick Start

This guide walks you through creating your first Klondike project and understanding the basic workflow.

Initialize a Project

Navigate to your project directory and run:

klondike init --name my-project

This creates:

  • .klondike/ - Directory for structured artifacts
  • .klondike/features.json - Feature registry
  • .klondike/agent-progress.json - Session and progress data
  • agent-progress.md - Human-readable progress document
  • .github/ - Copilot instructions (unless --skip-github)

Check Project Status

See an overview of your project:

klondike status

Output:

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

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

Add Features

Features are units of work you want to track. Add one:

klondike feature add "User login with email/password" \
  --category core \
  --priority 1 \
  --criteria "Login form displays,Validation works,JWT returned on success"

Good Feature Criteria

Acceptance criteria should be specific, testable, and observable:

  • ✅ "User sees success toast after save"
  • ✅ "API returns 200 with JSON body containing 'id'"
  • ❌ "Works correctly" (too vague)

List all features:

klondike feature list

Start a Session

Begin a work session with a focus area:

klondike session start --focus "F001 - User login"

This:

  1. Validates artifacts are intact
  2. Records the session start time
  3. Sets your focus for tracking

Work on a Feature

Mark a feature as in-progress:

klondike feature start F001

Now write your code! When you've completed the feature, verify it with evidence:

klondike feature verify F001 --evidence "tests/login.test.js passed"

Don't Skip Verification

Klondike requires evidence to mark features complete. This prevents premature "victory declaration" where work appears done but isn't actually tested.

End the Session

When you're done working:

klondike session end \
  --summary "Implemented login form with validation" \
  --completed "Form UI,Input validation,API integration" \
  --next "Add password reset flow,Add remember me checkbox"

This:

  1. Records what was accomplished
  2. Notes any blockers
  3. Suggests next steps for the next session
  4. Regenerates agent-progress.md

The Complete Workflow

graph TD
    A[klondike init] --> B[klondike feature add]
    B --> C[klondike session start]
    C --> D[klondike feature start F00X]
    D --> E[Write Code]
    E --> F{Feature Done?}
    F -->|Yes| G[klondike feature verify F00X]
    F -->|No| E
    G --> H{More Work?}
    H -->|Yes| D
    H -->|No| I[klondike session end]
    I --> J[Next Session]
    J --> C

Next Steps