KitTools

A documentation framework for AI-assisted development. Structured docs, session management, and automation hooks.

What is KitTools?

KitTools is a Claude Code plugin that provides:

Structured documentation templates — Consistent docs across projects
Session management — Track work across context refreshes
Automation hooks — Auto-timestamps, scratchpad reminders
Feature planning — Brainstorm and plan features with guided workflows

Think of it as a “documentation kit” for your projects, with AI-aware features built in. Instead of spending tokens explaining your project in chat, maintain living documentation that gives AI immediate understanding.

Installation

# Clone and install locally
git clone https://github.com/WashingBearLabs/KitTools.git
claude plugins install ./KitTools

Quick Start

Initialize — Set up kit_tools in your project:
```
/kit-tools:init-project
```
Select your project type (API, Web App, CLI, etc.) and templates will be tailored accordingly.
Seed — Populate templates with project-specific content:
```
/kit-tools:seed-project
```
Claude explores your codebase and fills in the documentation.
Work — Start a development session:
```
/kit-tools:start-session
```
Claude orients itself using your docs and creates a scratchpad for notes.
Close — End your session cleanly:
```
/kit-tools:close-session
```
Notes are processed into permanent documentation.

Skills Reference

Skill	Description
`/kit-tools:init-project`	Initialize kit_tools with project-type presets
`/kit-tools:seed-project`	Populate templates from codebase exploration
`/kit-tools:migrate`	Migrate existing docs to kit_tools structure
`/kit-tools:start-session`	Orient and create scratchpad for a work session
`/kit-tools:close-session`	Process notes and update docs at session end
`/kit-tools:checkpoint`	Mid-session checkpoint without closing
`/kit-tools:plan-feature`	Interactive feature brainstorming and planning
`/kit-tools:sync-project`	Full sync between code and docs (`--quick` for audit)
`/kit-tools:update-kit-tools`	Update project components from latest plugin versions

Hooks Reference

KitTools includes automation hooks that run automatically:

create_scratchpad

Trigger: SessionStart
What it does: Creates SESSION_SCRATCH.md if kit_tools exists
Why: Provides a place to capture notes during the session

update_doc_timestamps

Trigger: PostToolUse (Edit/Write)
What it does: Updates “Last Updated:” in kit_tools markdown files
Why: Keeps documentation timestamps accurate without manual effort

remind_scratchpad_before_compact

Trigger: PreCompact
What it does: Reminds to capture notes before context compaction
Why: Prevents losing important context when the conversation gets long

remind_close_session

Trigger: Stop
What it does: Reminds to run close-session if scratchpad has notes
Why: Ensures session notes get processed into permanent docs

Project Structure

After initialization, your project will have:

your-project/
├── kit_tools/
│   ├── AGENT_README.md      # AI navigation guide
│   ├── SYNOPSIS.md          # Project overview
│   ├── SESSION_LOG.md       # Session history
│   │
│   ├── arch/                # Architecture docs
│   │   ├── CODE_ARCH.md     # Code structure, patterns
│   │   ├── SERVICE_MAP.md   # Dependencies, integrations
│   │   ├── INFRA_ARCH.md    # Cloud resources, networking
│   │   ├── DATA_MODEL.md    # Database schema
│   │   ├── SECURITY.md      # Auth, secrets, permissions
│   │   ├── DECISIONS.md     # Architectural decision records
│   │   └── patterns/        # Detailed pattern docs
│   │
│   ├── docs/                # Operational docs
│   │   ├── LOCAL_DEV.md     # Local development setup
│   │   ├── TROUBLESHOOTING.md
│   │   ├── MONITORING.md
│   │   ├── CI_CD.md
│   │   ├── DEPLOYMENT.md
│   │   ├── API_GUIDE.md
│   │   ├── ENV_REFERENCE.md
│   │   ├── GOTCHAS.md       # Known issues
│   │   └── feature_guides/
│   │
│   ├── testing/             # Test documentation
│   └── roadmap/             # Task tracking
│       ├── MVP_TODO.md
│       ├── BACKLOG.md
│       └── FEATURE_TODO_*.md
│
└── CLAUDE.md                # Claude Code instructions

Templates Reference

KitTools provides 25+ documentation templates organized by category:

Core (Always included)

Template	Purpose
`AGENT_README.md`	AI navigation guide — read order, patterns, off-limits areas
`SYNOPSIS.md`	Project overview — what is this, current state, how to run
`CODE_ARCH.md`	Code architecture — structure, patterns, key abstractions
`LOCAL_DEV.md`	Local development setup
`GOTCHAS.md`	Known issues and landmines
`SESSION_LOG.md`	Session history
`roadmap/*`	Task and feature tracking

API (For backend services)

Template	Purpose
`API_GUIDE.md`	API documentation
`DATA_MODEL.md`	Database schema
`ENV_REFERENCE.md`	Environment variables

Ops (For deployed services)

Template	Purpose
`DEPLOYMENT.md`	Deploy procedures
`CI_CD.md`	Pipeline documentation
`MONITORING.md`	Logs, metrics, alerts
`INFRA_ARCH.md`	Cloud resources, networking

Patterns (Optional deep-dives)

Template	Purpose
`AUTH.md`	Authentication patterns
`ERROR_HANDLING.md`	Error handling patterns
`LOGGING.md`	Logging patterns

Project Types

When initializing, select your project type for tailored templates:

Type	Description	Templates Included
API/Backend	REST, GraphQL, microservices	Core + API + Data + Ops
Web App	React, Vue, Next.js	Core + Deployment + CI
Full Stack	Frontend + Backend	Everything
CLI Tool	Command-line apps	Core (minimal)
Library	npm, PyPI packages	Core + API docs
Mobile	iOS/Android apps	Core + Services
Custom	Pick templates manually	Your choice

Session Workflow

KitTools encourages a session-based workflow:

┌─────────────────┐
│  start-session  │  ← Orient, check for orphaned notes
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Work...     │  ← Scratchpad captures notes automatically
│                 │  ← Hooks update timestamps, remind on compact
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌─────────────┐
│checkpoint│ │close-session│
└────────┘ └─────────────┘
    │              │
    │              ▼
    │         Notes → permanent docs
    │         Scratchpad deleted
    ▼
  Continue
  working...

SESSION_SCRATCH.md

When a session starts, a scratchpad is created:

# SESSION_SCRATCH.md

> Auto-generated. Append notes as you work. Processed on session close.

## Active Feature

**Working on:** [Feature name or "General"]
**TODO File:** [e.g., `FEATURE_TODO_auth.md`]

---

## Notes

[Notes captured during the session]

On close-session, these notes are processed into permanent documentation and the scratchpad is deleted.

Feature Planning

Use /kit-tools:plan-feature to brainstorm new features:

Interactive questions refine scope and requirements
Generates FEATURE_TODO_[name].md with:
- Feature scope — Goal, Non-Goals, Success Criteria
- Origin context — Why now? What triggered this?
- Phased tasks with intent statements
- Pre-flight checklists per phase
Adds reference to backlog
Preserves brainstorming context for future sessions

Feature TODO Structure

## Feature Scope

**Goal:** [What problem does this solve?]
**Non-Goals:** [What is explicitly out of scope?]
**Success Criteria:** [How do we know it's done?]

## Origin

**Why now?** [What triggered this feature?]
**Date captured:** YYYY-MM-DD

## Tasks

### Phase 1: Foundation

> **Intent:** [Why does this phase exist?]

**Before starting this phase, confirm:**
- [ ] [Question to validate before coding]

**Tasks:**
- [ ] Task 1
- [ ] Task 2

Key Files Explained

AGENT_README.md

The entry point for AI assistants. Contains:

Read order — Which docs to read and in what order
Session checklists — Start and end checklists
Patterns to follow — Code organization, naming conventions, security patterns
Off-limits areas — Things requiring human review

SYNOPSIS.md

Quick project overview answering:

What is this project?
What state is it in?
What’s the tech stack?
How do I run it locally?
What works? What’s broken?

GOTCHAS.md

Known issues, quirks, and landmines:

### [Title]

**Location:** `path/to/file`
**Severity:** 🔴 High / 🟡 Medium / 🟢 Low

**What happens:** [Description]
**Why it exists:** [Reason]
**Workaround:** [How to avoid]

Template Versioning

All templates include version comments:

<!-- Template Version: 1.1.0 -->

Use /kit-tools:update-kit-tools to see if your project components are behind the plugin versions and selectively update.

Template vs Instance

A key design principle:

Plugin templates = Canonical versions, updated with the plugin
Project kit_tools/ = Your project’s documentation, can diverge and customize

This means:

Plugin updates don’t overwrite your customized docs
You can selectively pull in template improvements
Each project’s documentation is independent

Philosophy

This framework is built around a key insight: AI assistants are most effective when they have structured, comprehensive context about a codebase.

Instead of repeatedly explaining your project in chat, maintain living documentation that:

Gives AI immediate understanding of architecture and patterns
Prevents AI from making decisions that violate existing conventions
Enables effective troubleshooting with log locations and debug procedures
Reduces errors by documenting gotchas and known issues

The documentation also benefits human developers, but it’s optimized for AI consumption.

Core Principles

AI-first documentation — Written for AI consumption, useful for humans too
Living docs — Update as you go, not as an afterthought
Minimal viable docs — Only document what’s useful, delete what isn’t
Session logging — Track what was done for continuity across sessions

License

GPL-3.0 License