Skip to content

schema-reference.md

Latest commit

 

History

History
391 lines (315 loc) · 10.7 KB

schema-reference.md

File metadata and controls

391 lines (315 loc) · 10.7 KB

Schema Reference

Complete YAML schema reference for all checkpoint and guardrail data files.

Changelog Entry

File: .checkpoint-changelog.yaml

Append-only, multi-document YAML file. Each document represents one checkpoint, separated by ---.

---
schema_version: "1"
timestamp: "2025-01-15T10:30:00-08:00"    # RFC3339, set by checkpoint check
commit_hash: "a1b2c3d"                      # Backfilled by checkpoint commit
files_changed:                              # Optional, from git diff --numstat
  - path: "internal/auth/handler.go"
    additions: 42
    deletions: 8

changes:                                    # Required, at least one entry
  - summary: "Add JWT authentication middleware"       # Required, max 80 chars
    details: "Implemented token validation and..."     # Optional, longer description
    change_type: "feature"                             # Required, see valid values below
    scope: "internal/auth"                             # Optional, affected component

context:                                    # Optional but recommended
  problem_statement: "API endpoints had no auth"       # What problem this solves
  key_insights:
    - insight: "JWT refresh tokens need separate storage"
      impact: "Must add Redis before production"
      scope: "project"                                 # checkpoint or project
  decisions_made:
    - decision: "Use RS256 over HS256 for JWT signing"
      rationale: "Allows public key verification without sharing secret"
      alternatives_considered:
        - "HS256 - rejected, requires shared secret across services"
      constraints_that_influenced: "Multi-service architecture"
      scope: "project"
  failed_approaches:
    - approach: "Session-based auth with cookies"
      why_failed: "Doesn't work for API-only clients"
      lessons_learned: "Always consider non-browser consumers"
      scope: "project"
  key_exchanges:
    - prompt_summary: "Asked LLM to implement auth middleware"
      approach_taken: "LLM proposed JWT with middleware pattern"
      human_feedback: "Approved, but switched from HS256 to RS256"

next_steps:                                 # Optional
  - summary: "Add rate limiting per authenticated user"
    details: "Use token bucket algorithm"
    priority: "med"                          # low, med, or high
    scope: "internal/middleware"              # Affected component

Valid change_type values

Value Use when
feature Adding new functionality
fix Fixing a bug or incorrect behavior
refactor Restructuring code without changing behavior
docs Documentation changes only
perf Performance improvements
other Anything that doesn't fit above

Valid priority values (next_steps)

Value Meaning
low Nice to have, no urgency
med Should be done soon
high Do this next

Valid scope values (context fields)

Value Meaning
checkpoint Relevant only to this change
project Project-wide -- gets extracted as a recommendation to .checkpoint/project.yaml

Context Entry

File: .checkpoint-context.yaml

Append-only, multi-document YAML file. Each document contains the context section from a checkpoint, stored separately for easier searching and review.

---
schema_version: "1"
timestamp: "2025-01-15T10:30:00-08:00"
context:
  problem_statement: "..."
  key_insights: [...]
  decisions_made: [...]
  failed_approaches: [...]
  key_exchanges: [...]

The structure of the context block is identical to the one in changelog entries. Context is extracted automatically during checkpoint commit.

Project Config

File: .checkpoint/project.yaml

Multi-document YAML file with two roles:

  1. Main document (first): Human-curated project overview. Edit this directly.
  2. Appended documents: Recommendations generated by checkpoint commit from project-scoped context items. Review and incorporate periodically.

Main document

schema_version: "1"
name: "my-project"
type: "go-cli"                              # Freeform project type
purpose: |
  One or two sentences describing what this project does.

repository: "github.com/user/my-project"    # Optional

architecture:
  overview: |
    High-level description of how the project is structured.
  key_paths:
    entry_point: "main.go"
    commands: "cmd/"
    core_logic: "internal/"
  data_flow: |
    Description of how data moves through the system.
  key_files:
    - path: ".checkpoint-changelog.yaml"
      purpose: "Append-only changelog"
      tracked: true

languages:
  primary: "go"
  version: "1.25"

dependencies:
  external:
    - name: "gopkg.in/yaml.v3"
      purpose: "Multi-document YAML parsing"

integrations:
  - name: "Git"
    type: "required"
    interaction: "Wraps git for status, diff, commit"

ai_authority:
  autonomous:
    - "Bug fixes with clear reproduction steps"
    - "Test additions for existing code"
    - "Documentation updates"
  requires_approval:
    - "New features not in roadmap"
    - "Architecture changes"
    - "Dependency additions"
  notes: "When in doubt, ask."

lessons_learned:
  - topic: "YAML parsing"
    failed_approach: "Single-document parsing for multi-doc files"
    why_failed: "Lost all but first document"
    lesson: "Always use yaml.Decoder for multi-document files"
    date: "2025-01-10"

roadmap:
  planned:
    - summary: "Add search command"
      priority: "high"
      blockers: []
  deferred:
    - summary: "Web dashboard"
      reason: "CLI-first approach, defer until core is stable"
      reconsider_when: "After v1.0 release"

Recommendations document (appended)

These are appended automatically by checkpoint commit when context items have scope: project. Review periodically and merge valuable items into the main document.

---
schema_version: "1"
document_type: "recommendations"
timestamp: "2025-01-15T10:30:00-08:00"
recommended_additions:
  key_insights:
    - insight: "Batch operations over 1000 rows use different code path"
      impact: "Need to test both small and large batches"
  failed_approaches:
    - approach: "Database triggers for audit logging"
      why_failed: "No access to application context"
      lessons_learned: "Audit at application layer"
  design_principles:
    - principle: "All API responses use {data, error, metadata} structure"
      rationale: "Consistent format simplifies client error handling"
recommended_deletions:
  - section: "lessons_learned"
    item: "Outdated lesson about old framework"
    reason: "Framework was replaced in v0.5"

Tools Config

File: .checkpoint/tools.yaml

Defines build, test, lint, and run commands for the project.

schema_version: "1"

build:
  default:
    command: "make build"
    output: "bin/myapp"
    notes: "Builds for current platform"
  install:
    command: "make install"
    notes: "Install to GOPATH/bin"

test:
  default:
    command: "make test"
    notes: "Run all tests"
  coverage:
    command: "make test-coverage"
    notes: "Run with coverage report"

lint:
  default:
    command: "make lint"
    notes: "Run linter"
  fix:
    command: "make fmt"
    notes: "Auto-format code"

check:
  default:
    command: "make check"
    notes: "Run fmt, vet, lint, test"

run:
  default:
    command: "make run"
    notes: "Run with no args"
  with_args:
    command: "make run-with ARGS=\"<args>\""
    example: "make run-with ARGS=\"start .\""
    notes: "Run with specific arguments"

maintenance:
  deps:
    command: "make deps"
    notes: "Download dependencies"
  clean:
    command: "make clean"
    notes: "Remove build artifacts"

verify:
  pre_commit:
    - command: "go build ./..."
      description: "Ensure compilation"
      required: true
    - command: "go test ./..."
      description: "Run tests"
      required: true

Each tool command has:

  • command -- The shell command to run
  • output -- Optional, path to build output
  • notes -- Optional, description
  • example -- Optional, usage example

The verify.pre_commit section lists commands that checkpoint commit runs before finalizing. If any required command fails, the commit is aborted.

Guidelines Config

File: .checkpoint/guidelines.yaml

Coding standards and conventions for the project.

schema_version: "1"

naming:
  commands:
    pattern: "lowercase single word"
    examples:
      - "start, check, commit, explain"
  files:
    pattern: "snake_case.go"
    examples:
      - "commit_test.go"
  functions:
    exported: "PascalCase"
    internal: "camelCase"
  packages:
    pattern: "lowercase, single word preferred"
    examples:
      - "internal/changelog"

structure:
  new_command: |
    1. Create cmd/{name}.go
    2. Add command function
    3. Wire into root command
  new_package: |
    1. Create internal/{name}/{name}.go
    2. Keep focused on single responsibility
    3. Add tests

errors:
  style: |
    Wrap errors with context: fmt.Errorf("operation: %w", err)
  user_facing: |
    Include hints for resolution.

testing:
  pattern: "{file}_test.go in same package"
  naming: "Test{Function}_{Scenario}"
  style: "Table-driven tests for multiple scenarios"

rules:
  - "Run make check before any commit"
  - "All user-facing errors need actionable hints"
  - "One checkpoint = one git commit"

avoid:
  - "Global state in command files"
  - "Silent failures"
  - "Adding deps when stdlib works"

principles:
  - "Append-only: corruption isolated to tail"
  - "Minimal deps: stdlib + essential libraries only"
  - "Git-native: everything tracked, travels with project"

collaboration:
  protocol: "propose > approve > implement > summarize"
  principles:
    - "Ask for clarification rather than assuming"
    - "Human approves architecture, AI proposes implementation"
    - "Reference project patterns before introducing new ones"

Skills Config

File: .checkpoint/skills.yaml

Defines which tools and capabilities are available to LLMs working on the project.

schema_version: "1"

global:                           # From ~/.config/checkpoint/skills/
  - ripgrep
  - git
  - go

local:                            # From .checkpoint/skills/
  - checkpoint-workflow

config:                           # Skill-specific settings
  go:
    version: "1.25"
    module: "my-project"

auto_detect:
  include_in_explain:             # Skills included in guardrail explain output
    - checkpoint-workflow
    - ripgrep
    - git

Skills are markdown files ({name}.md) stored in either the global skills directory (~/.config/checkpoint/skills/) or the local project skills directory (.checkpoint/skills/). Each skill describes a tool's capabilities, common commands, and when to use it.