.github Directory

This directory contains GitHub-specific files and comprehensive guidance for working on the ollama-kit project.

Files Overview

File	Purpose
copilot-instructions.md	Primary agent guidance — comprehensive instructions for AI coding agents
CONTRIBUTING.md	Human contributor guidelines
PULL_REQUEST_TEMPLATE.md	PR template with checklist
ISSUE_TEMPLATE/	Issue templates for bugs and features

For AI Coding Agents

If you're an AI agent working on this project, read these files in order:

1. Start with the Docs System

docs/index/MASTER_INDEX.md    ← Current state, active sprint
docs/design/DESIGN.md         ← Full product specification
docs/_system/agent-guidance.md ← Rules for working

2. Understand the Documentation Structure

The /docs folder is the single source of truth:

docs/
├── _system/              # System rules
│   ├── agent-guidance.md # How to work on this project
│   ├── conventions.md    # Naming and status rules
│   ├── lifecycle.md      # State transitions
│   └── bootstrap.md      # Initial setup runbook
├── design/
│   └── DESIGN.md         # Product specification (authoritative)
├── index/
│   ├── MASTER_INDEX.md   # Current state (start here!)
│   └── ROADMAP.md        # High-level milestones
├── phases/               # PHASE-XX-*.md files
├── sprints/              # SPRINT-XX.md files
├── features/             # FEAT-XXX-*.md files
├── bugs/                 # BUG-XXX-*.md files
├── refactors/            # REFACTOR-XXX-*.md files
├── decisions/            # ADR-XXXX-*.md files
│   └── DECISION_LOG.md   # Index of all ADRs
└── templates/            # Templates for creating new docs

3. Follow the Golden Rules

1. Only work on items in the active sprint — Check MASTER_INDEX.md
2. No new work without an ID and file — Every task needs a doc
3. If docs conflict, MASTER_INDEX wins — It's the source of truth
4. Do not silently expand scope — Create an ADR for significant changes

4. Status Vocabulary

Use ONLY these status values:

Status	Meaning	Used For
planned	Not started	All types
active	Currently running	Phases, Sprints only
in_progress	Being worked on	Features, Bugs, Refactors
blocked	Waiting on something	Features, Bugs, Refactors
review	Ready for review	Features, Bugs, Refactors
complete	Done	All types
deprecated	No longer relevant	All types

5. Naming Conventions

Type	Pattern	Example
Phase	PHASE-XX	PHASE-01-foundation.md
Sprint	SPRINT-XX	SPRINT-01.md
Feature	FEAT-XXX	FEAT-001-package-structure.md
Bug	BUG-XXX	BUG-001-timeout-race.md
Refactor	REFACTOR-XXX	REFACTOR-001-http-cleanup.md
Decision	ADR-XXXX	ADR-0001-zod-first-schemas.md

Workflow for Agents

Starting Work

1. Read docs/index/MASTER_INDEX.md
2. Identify active sprint
3. Pick a planned item from the sprint
4. Update item status to in_progress
5. Update MASTER_INDEX "In Progress" section
6. Do the work
7. Update item status to complete
8. Remove from MASTER_INDEX "In Progress"

Making Architectural Decisions

If you need to make a significant design choice:

1. Create docs/decisions/ADR-XXXX-name.md
2. Add entry to docs/decisions/DECISION_LOG.md
3. Link from relevant feature docs

Creating New Work Items

If a new task is needed (found during implementation):

1. Discuss with user first
2. Create appropriate doc file (feature/bug/refactor)
3. Add to current or future sprint
4. Update MASTER_INDEX.md

Project Architecture

ollama-kit is structured as:

src/
├── index.ts           # Main entry (ollama-kit)
├── client.ts          # OllamaClient class
├── createClient.ts    # Factory function
├── types/             # Shared types
├── http/              # HTTP layer
├── streaming/         # Stream parsing
├── chat/              # Chat API
├── tools/             # Tool calling
├── schemas/           # Schema adapters
├── errors/            # Error classes
├── react/             # ollama-kit/react
│   └── index.ts
└── node/              # ollama-kit/node
    └── index.ts

Key Decisions (ADRs)

ADR	Decision
ADR-0001	Zod-first schemas with JSON Schema fallback
ADR-0002	Manual tool mode default, auto-execute opt-in
ADR-0003	Proxy-first architecture for browser usage
ADR-0004	Single package with subpath exports
ADR-0005	Adapter-based tokenizer with default estimator

Questions?

1. Check docs/_system/ files for rules
2. Check docs/design/DESIGN.md for product requirements
3. Check ADRs in docs/decisions/ for past decisions
4. Ask for clarification (don't guess)