Configuration¶

Klondike stores configuration and artifacts in the .klondike/ directory. This page documents the structure and purpose of each file.

Project Structure¶

After running klondike init, your project will have:

your-project/
├── .klondike/
│   ├── config.json          # Project configuration
│   ├── features.json         # Feature registry
│   └── agent-progress.json   # Session and progress data
├── .github/
│   ├── copilot-instructions.md  # Agent instructions
│   └── instructions/            # Additional instruction files
├── agent-progress.md         # Human-readable progress (auto-generated)
└── ... your project files

Configuration Files¶

.klondike/config.json¶

Project-level configuration:

{
  "project_name": "my-project",
  "version": "0.1.0",
  "created_at": "2024-01-15T10:30:00Z"
}

Field	Description
`project_name`	Display name for the project
`version`	Current semantic version
`created_at`	Project initialization timestamp

.klondike/features.json¶

The feature registry:

{
  "features": [
    {
      "id": "F001",
      "description": "User login with email/password",
      "category": "core",
      "priority": 1,
      "status": "verified",
      "acceptance_criteria": [
        "Login form displays correctly",
        "Validation shows errors",
        "JWT returned on success"
      ],
      "evidence": ["tests/login.test.js"],
      "notes": "",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-16T14:20:00Z"
    }
  ],
  "next_id": 2
}

Field	Description
`features`	Array of feature objects
`next_id`	Counter for generating next feature ID

Feature Object¶

Field	Type	Description
`id`	string	Unique identifier (F001, F002, etc.)
`description`	string	What the feature does
`category`	string	Feature category
`priority`	number	Priority 1-5 (1 = highest)
`status`	string	`not-started`, `in-progress`, `verified`, `blocked`
`acceptance_criteria`	array	List of testable criteria
`evidence`	array	Verification evidence (file paths, etc.)
`notes`	string	Additional notes
`block_reason`	string	Why feature is blocked (if applicable)
`created_at`	string	ISO timestamp
`updated_at`	string	ISO timestamp

Don't Edit Manually

Use klondike feature commands to modify features. Manual edits may cause validation errors.

.klondike/agent-progress.json¶

Session and progress tracking:

{
  "sessions": [
    {
      "number": 1,
      "started_at": "2024-01-15T10:30:00Z",
      "ended_at": "2024-01-15T12:45:00Z",
      "focus": "F001 - User login",
      "summary": "Completed login form with validation",
      "completed": ["Login UI", "Form validation", "API integration"],
      "blockers": [],
      "next_steps": ["Add password reset", "Add remember me"]
    }
  ],
  "current_session": null
}

Field	Description
`sessions`	Array of completed sessions
`current_session`	Active session (if any)

Session Object¶

Field	Type	Description
`number`	number	Session sequence number
`started_at`	string	ISO timestamp
`ended_at`	string	ISO timestamp (null if active)
`focus`	string	What the session focused on
`summary`	string	What was accomplished
`completed`	array	List of completed items
`blockers`	array	Issues encountered
`next_steps`	array	Recommended follow-up

Generated Files¶

agent-progress.md¶

Auto-generated from .klondike/agent-progress.json. This human-readable file serves as the handoff document between sessions.

Do not edit manually - changes will be overwritten.

Regenerate with:

klondike progress

.github/copilot-instructions.md¶

Instructions for AI agents working on the project. This file is created during klondike init and can be customized.

Categories¶

Standard categories for organizing features:

Category	Use For
`core`	Essential functionality
`ui`	User interface components
`api`	API endpoints and integration
`infrastructure`	Setup, CI/CD, tooling
`docs`	Documentation
`testing`	Test coverage
`security`	Security features
`performance`	Optimization

Priority Levels¶

Priority	Meaning	When to Use
1	Critical	Blocks everything else
2	High	Needed for MVP
3	Medium	Enhances experience
4	Low	Nice to have
5	Future	Post-MVP stretch goals

Feature Status¶

Status	Description
`not-started`	Feature has not been worked on
`in-progress`	Currently being developed
`verified`	Complete with evidence
`blocked`	Waiting on external dependency

Validation¶

Klondike validates artifacts on:

klondike validate command
klondike session start
Any feature modification

Validation checks:

JSON syntax is valid
Required fields are present
Feature IDs are unique
Status values are valid
Timestamps are valid ISO format

Backup and Recovery¶

Export Features¶

Create a backup of your feature registry:

klondike export-features backup.yaml --all

Import Features¶

Restore from backup:

klondike import-features backup.yaml

Git Recovery¶

If artifacts are corrupted, use git to recover:

# See history
git log --oneline .klondike/

# Restore previous version
git checkout HEAD~1 -- .klondike/features.json

Environment Variables¶

Klondike respects these environment variables:

Variable	Description	Default
`KLONDIKE_NO_COLOR`	Disable colored output	`false`
`KLONDIKE_JSON`	Default to JSON output	`false`

# Disable colors
export KLONDIKE_NO_COLOR=1
klondike status

# Default to JSON
export KLONDIKE_JSON=1
klondike feature list